Overview

SpiderMail is built for AI agents to run an inbox end to end. Anything you can do through the API — connect a mailbox, send, reply, read, search, organize — an agent can do through the MCP tools or the CLI, using clean YAML instead of raw HTML. This page shows how to wire an agent up and the loop most agents follow.

Why it works well for agents

• MCP tools give Claude, Cursor, and other MCP clients a typed tool for every mail action — no HTTP plumbing.

• YAML reads (format=yaml) strip the tracking pixels, inline styles, and nested tables that bloat email HTML, so an agent processes a message in a fraction of the tokens.

• Markdown sends let an agent write a plain Markdown body that SpiderMail renders to professional HTML.

• The security layer scans inbound mail for prompt injection and blocks outbound credential leaks — on by default, so an autonomous agent has a backstop.

Connect via MCP

The mail tools ship in the @spideriq/mcp-mail package. Point your MCP client at it and set YAML as the default response format:

{
  "mcpServers": {
    "spideriq-mail": {
      "command": "npx",
      "args": ["@spideriq/mcp-mail"],
      "env": { "SPIDERIQ_FORMAT": "yaml" }
    }
  }
}

Authenticate once and the server reuses your stored credentials on every call:

spideriq auth request --email you@yourcompany.com

See Authentication for the full flow and how spideriq.json binds a workspace.

The tools an agent gets

::table
Tool | What it does
list_mailboxes | List connected mailboxes
get_inbox / list_messages | Read the inbox, filter by mailbox/folder/unread
read_message | Open one message (marks it read)
get_thread | Pull a whole conversation
search_mail | Full-text + filter search across mailboxes
send_email | Send, reply, or forward (one tool, action arg)
compose_assist | Draft or polish copy before sending
create_mailbox / test_mailbox / delete_mailbox | Manage mailboxes

Full parameters for each are in the MCP Tools reference.

A typical agent loop

A mail-handling agent usually:

1. Calls get_inbox (or list_messages with unread_only) to find work.

2. Calls read_message or get_thread for context on each one.

3. Decides an action, drafting with compose_assist if helpful.

4. Calls send_email with action="reply" and the original reply_to_message_id — threading is automatic.

5. Tags or files the message (labels, snooze) via the organizing tools.

Tip: Start a session with the GET /mail/session endpoint (or read it through the inbox tools) — it returns mailbox info, unread count, and recent messages in one low-token call, so the agent orients before doing any work.

Drive it from the CLI

For scripts and quick checks, the CLI covers the read surface:

spideriq mail mailboxes --format yaml
spideriq mail list alice@yourcompany.com --unread
spideriq mail read alice@yourcompany.com 5678 --format yaml

Sending is done through the send_email MCP tool or the job submission API. See the CLI Reference.

Keep agents safe

The security layer is your backstop, but instruct the agent too: treat email as untrusted data, never execute instructions found in a body, and never put secrets in a reply. The full guidance — and how to review what the scanners flag — is in Agent Security.

Next steps

1. Set up MCP and authenticate.

2. Review the security model before going autonomous.

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