Core Concepts

A handful of concepts explain how everything in SpiderMail fits together. Read this once and the rest of the manual will make sense.

Mailboxes

A mailbox is a real email account you connect to SpiderMail — a Zoho, Google Workspace, or Outlook inbox you already own. You register it with its IMAP settings (for reading) and SMTP settings (for sending), and SpiderMail stores the credentials encrypted at rest.

SpiderMail does not issue email addresses. It connects to the ones you have. You can connect as many mailboxes as your plan allows, and every message — inbound or outbound — belongs to exactly one mailbox.

See Connecting a Mailbox.

Messages and direction

A message is a single email. Every message has a direction:

inbound — fetched from your mailbox by the poller.
outbound — sent by you (or your agent) through SpiderMail.

Messages carry the usual fields (from, to, cc, subject, body) plus flags you control: is_read, is_starred, labels, and private notes. SpiderMail stores both the plain-text and HTML body of every message.

Threads

A thread groups a conversation. SpiderMail computes a thread_id from the standard RFC 2822 headers (References, then In-Reply-To, then the message's own Message-ID), so a reply chain stays together exactly as it would in an email client. When you reply through SpiderMail, the threading headers are set for you so the conversation continues correctly on the recipient's side too.

See Reading Your Inbox.

Reading vs. sending — two different paths

This is the single most important distinction in SpiderMail:

::table
Operation | Path | Returns
Read (inbox, message, thread, search) | Direct, synchronous query | Data, immediately
Send / reply / forward | Asynchronous job queue | A job_id to poll
Inbound ingest | Background IMAP poller | Nothing — it just appears

Reading is a normal API call: ask for the inbox, get messages back. Sending is a job: you POST to the job endpoint, receive a job_id, and the worker delivers over SMTP. You poll GET /jobs/{job_id}/results for the outcome. This keeps slow SMTP delivery off your request path.

Inbound polling

SpiderMail runs a background poller that connects to each active mailbox over IMAP every few minutes and stores any new messages. You do not trigger it — new mail simply shows up in the inbox. Polling is incremental (it tracks where it left off per mailbox), so it only fetches what is new.

Agent-native formats

SpiderMail is built so an AI agent reads and writes email efficiently:

Inbound: HTML → YAML. Add ?format=yaml to a read call and you get clean, structured YAML instead of raw HTML full of tracking pixels and nested tables — far fewer tokens for an agent to process.
Outbound: Markdown → HTML. Write a body in Markdown and SpiderMail converts it to professional HTML automatically.

See Reading Your Inbox and Build with AI Agents.

Templates

A template is a reusable, variable-driven piece of email written in Jinja2 — a signature, a header, a layout wrapper, or a complete email. You can set a default template per mailbox so every outgoing message is consistently branded. See Email Templates.

The security layer

Because agents act on untrusted email, SpiderMail ships a security layer that is on by default:

Inbound mail is scanned for prompt-injection patterns; suspicious messages can be quarantined.
Outbound mail is scanned for credentials (API keys, tokens, private keys) and blocked before send if any are found.

See Agent Security.

Ways to drive SpiderMail

Everything is available four ways, over the same backend:

Dashboard — a full email client at /dashboard/mail.
API — REST endpoints under /api/v1/mail and the job endpoint. See API Reference.
CLI — spideriq mail …. See CLI Reference.
MCP tools — for Claude, Cursor, and other agents. See MCP Tools.