SpiderMail

API Reference

The complete customer-facing SpiderMail API. All paths are under https://spideriq.ai/api/v1. Every request authenticates with a bearer token (Authorization: Bearer <client_id>:<api_key>:<api_secret>) — see Authentication.

Reads are synchronous and return data. Sending is a job: you submit, get a job_id, and poll for the result. GET read endpoints that return messages support ?format=yaml for low-token output.

Mailboxes

  • POST /mail/mailboxes — register a mailbox. Body: email_address (required), display_name, provider (zoho|google_workspace|outlook), imap_host, imap_port (default 993), imap_username, imap_password, smtp_host, smtp_port (default 587), smtp_username, smtp_password. Subject to the per-plan max_mailboxes quota (403 resource_quota_exceeded when full).

  • GET /mail/mailboxes — list mailboxes (passwords never returned).

  • GET /mail/mailboxes/stats — per-mailbox counts (total, unread, starred) plus a workspace rollup.

  • PATCH /mail/mailboxes/{email} — update display_name, is_active, default_template_id (0 to clear), template_variables.

  • POST /mail/mailboxes/{email}/test — test IMAP + SMTP connectivity. Returns imap_ok / smtp_ok (+ error strings).

  • DELETE /mail/mailboxes/{email} — delete the mailbox and all its stored messages.

See Connecting a Mailbox.

Inbox and Messages

  • GET /mail/inbox — list messages. Query: email (omit for Master Inbox across all mailboxes), view_id (apply a saved view), unread_only, folder (INBOX|Sent|Drafts|Trash), direction (inbound|outbound), limit (1–100, default 20), offset, format (json|yaml).

  • GET /mail/folders — folder list with counts. Query: email (required).

  • GET /mail/messages/{message_id} — full message; marks it read. Query: format, include_attachments (default true).

  • PATCH /mail/messages/{message_id} — update flags. Body: is_read, is_starred, labels (array), notes.

  • POST /mail/messages/bulk — bulk update. Body: message_ids (array, 1–100), action (mark_read|mark_unread|archive|delete|add_label), label (required for add_label).

See Reading Your Inbox.

Threads

  • GET /mail/threads/{thread_id} — every message in a conversation. Query: format, include_attachments.

Search

  • GET /mail/search — search one mailbox. Query: email (required), q (full-text), from_addr (substring), subject (substring), since / before (ISO 8601). See Search.

Session

  • GET /mail/session — agent bootstrap: mailbox info + unread count + recent messages in one call. Query: email (required), include_recent (0–50, default 10), format.

Snooze

  • POST /mail/messages/{message_id}/snooze — body: snoozed_until (ISO 8601, required).

  • DELETE /mail/messages/{message_id}/snooze — unsnooze; returns to original folder.

  • GET /mail/snoozed — list snoozed messages. Query: email.

Labels

  • GET /mail/labels — list label definitions.

  • POST /mail/labels — body: name (1–50), color (hex, default #6B7280).

  • PATCH /mail/labels/{label_id} — update name / color.

  • DELETE /mail/labels/{label_id} — delete the label.

Apply labels by setting a message's labels array. See Labels, Snooze & Views.

Saved Views

  • GET /mail/views — list visible views. Query: include_shared (default true).

  • POST /mail/views — body: name (1–200), color, filter_config, column_config, sort_by (default date), sort_direction (ASC|DESC), is_shared (default false). filter_config keys: mailboxes, unread_only, starred_only, has_attachments, from_contains, subject_contains, labels, received_after, received_before, direction.

  • GET /mail/views/{view_id} — one view.

  • PATCH /mail/views/{view_id} — update (creator only).

  • DELETE /mail/views/{view_id} — delete (creator only).

Templates

  • GET /mail/templates — list. Query: template_type (signature|header|layout|full).

  • GET /mail/templates/{template_id} — one template.

  • POST /mail/templates — body: name (required, [\w\-]+), template_type (default full), html_source (required, Jinja2), text_source, variables (auto-detected if omitted), description, is_default.

  • PATCH /mail/templates/{template_id} — update any field.

  • DELETE /mail/templates/{template_id} — soft delete (sets inactive).

  • POST /mail/templates/{template_id}/preview — render with sample data. Body: variables (object; legacy alias template_data). Returns rendered_html, variables_used, missing_variables.

See Email Templates.

AI Compose

  • POST /mail/compose/assist — draft or polish text (returns copy, does not send). Body: action (write|rewrite|expand|shorten|formal|casual|fix_grammar), context (required, the text to work from), tone (professional|friendly|casual|formal, default professional), subject, thread_context. See AI Compose.

Security and Quarantine

  • GET /mail/security/events — list scanner events. Query: email, event_type, limit (1–200, default 50), offset.

  • GET /mail/quarantine — list quarantined inbound messages. Query: email, limit, offset.

  • POST /mail/messages/{message_id}/release — release a message from quarantine.

See Agent Security.

Sending (send, reply, forward)

Sending is asynchronous. Submit a job, then poll GET /jobs/{job_id}/results.

  • POST /jobs/spiderMail/submit — body: { "payload": SpiderMailJobPayload, "priority": 0–10 }.

SpiderMailJobPayload fields:

  • action (required) — send | reply | forward.

  • from_email (required) — a connected mailbox.

  • to (array) — recipients. Required for send and forward.

  • cc (array) — CC recipients.

  • subject — required for send.

  • body_text (required) — plain-text body; Markdown is rendered to HTML.

  • body_html — explicit HTML body (creates multipart/alternative).

  • attachments (array) — each { filename, content_base64, mime_type? }.

  • reply_to_message_id (int) — required for reply and forward.

  • reply_all (bool, default false) — reply action only.

  • test (bool, default false) — route to the test queue.

  • GET /jobs/{job_id}/results — poll for delivery. completed returns { message_id, sent_at }; failed returns the real exception name + message.

See Sending, Replying & Forwarding.

Response formats

GET endpoints that return messages (/mail/inbox, /mail/messages/{id}, /mail/threads/{id}, /mail/session) accept ?format=yaml for clean, low-token YAML — the recommended default for AI agents. Without it, responses are JSON.

Next steps

  1. MCP Tools — the same surface as typed agent tools.

  2. CLI Reference.

  3. Authentication.