SpiderMail

MCP Tools

The SpiderMail MCP tools let an agent run a mailbox without touching HTTP. They ship in the @spideriq/mcp-mail package; wire it into your MCP client and authenticate once (see Build with AI Agents for setup). Every tool also accepts a workspace argument (defaults to default) to select which signed-in workspace to act on.

Read tools accept a format of json, yaml, or md (set SPIDERIQ_FORMAT=yaml in the MCP config to default them to YAML).

Reading tools

list_mailboxes

List your SpiderMail mailboxes.

  • format (string, optional) — json | yaml | md.

get_inbox

Get inbox messages with optional filtering by mailbox, folder, and read status.

  • mailbox (string, optional) — filter by mailbox email.

  • folder (string, optional, default inbox) — folder name.

  • unread_only (boolean, optional, default false).

  • limit (number, optional, default 20) — max results.

  • offset (number, optional) — pagination offset.

list_messages

List messages in a mailbox.

  • mailbox_id (string, required) — mailbox id or email address.

  • unread_only (boolean, optional, default false).

  • page (number, optional, default 1).

  • per_page (number, optional, default 20).

  • format (string, optional).

read_message

Read a specific email message.

  • mailbox_id (string, required) — mailbox id or email.

  • message_id (string, required).

  • format (string, optional).

get_thread

Get a conversation thread with all related messages.

  • thread_id (string, required).

search_mail

Full-text search across all mailboxes. Filter by sender, recipient, and date range.

  • query (string, required).

  • from (string, optional) — filter by sender email.

  • to (string, optional) — filter by recipient email.

  • mailbox (string, optional).

  • date_from / date_to (string, optional) — ISO dates.

  • limit (number, optional, default 20).

test_mailbox

Test a mailbox connection (IMAP/SMTP).

  • email (string, required) — mailbox email to test.

compose_assist

Get AI assistance for composing an email — tone adjustment, suggestions, rewrites. Returns text only; does not send.

  • prompt (string, required) — what to write or how to improve the draft.

  • draft (string, optional) — existing draft to improve.

  • context (string, optional) — recipient info, conversation history.

  • tone (string, optional) — professional | casual | friendly | formal.

Writing tools

send_email

Send, reply to, or forward an email through a registered mailbox. Returns { success, job_id, status, next_step } — poll the job for delivery.

  • action (string, optional, default send) — send | reply | forward.

  • from_email (string, required) — a registered mailbox.

  • to (array of string, optional) — required for send / forward.

  • cc (array of string, optional).

  • subject (string, optional) — required for send.

  • body_text (string, required) — plain-text body.

  • body_html (string, optional).

  • reply_to_message_id (number, optional) — required for reply / forward.

  • reply_all (boolean, optional) — reply action only.

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

create_mailbox

Connect a new email mailbox (IMAP/OAuth2) for sending and receiving.

  • email (string, required).

  • display_name (string, optional).

  • provider (string, optional) — zoho | google_workspace | outlook.

  • imap_host (string, optional), imap_port (number, optional, default 993).

  • smtp_host (string, optional), smtp_port (number, optional, default 587).

  • password (string, required) — email or app-specific password.

delete_mailbox

Delete a mailbox and all its data.

  • email (string, required) — mailbox email to delete.

Authentication and shared tools

The mail package also bundles the shared SpiderIQ authentication and system tools (request access, check auth status, health check). Authenticate with spideriq auth request before calling any mail tool; an unauthenticated call returns a "Not authenticated. Call request_access first." error. See Authentication.

Next steps

  1. Build with AI Agents — wiring and the agent loop.

  2. CLI Reference for the command-line surface.

  3. API Reference for anything not exposed as a tool.