SpiderMail

What is SpiderMail?

SpiderMail is email infrastructure for AI agents and the people who run them. Connect a real Zoho, Google Workspace, or Outlook mailbox, and SpiderMail lets you — or an agent acting for you — send, reply, forward, read, search, and organize email through one clean API, a CLI, MCP tools, and a full dashboard inbox.

It is the engine behind agent SDRs and inbox automation at SpiderIQ: you bring an existing mailbox, SpiderMail handles the IMAP polling, SMTP sending, conversation threading, encryption-at-rest, templates, and the security layer that keeps an agent from being hijacked by a malicious email.

Connect a mailbox and you immediately get:

  • Send, reply, and forward through your own mailbox over SMTP — replies thread correctly with In-Reply-To / References.

  • A polled inbox — SpiderMail checks your mailbox over IMAP and stores new mail so you can read, search, and act on it without re-fetching.

  • Conversation threads — messages grouped into threads the way an email client would.

  • Agent-native formats — read mail as clean YAML (not raw HTML) and write replies in Markdown that SpiderMail converts to professional HTML.

  • Templates — reusable Jinja2 signatures, headers, layouts, and full emails with variables.

  • A built-in security layer — inbound prompt-injection scanning and outbound credential blocking, on by default.

  • Three ways to drive it — the dashboard inbox, the API, and the CLI / MCP tools so an agent can do everything a person can.

When to use SpiderMail

SpiderMail is a strong fit when you want to:

  • Give an AI agent a real mailbox it can read and reply from — agent SDRs, support triage, inbound qualification.

  • Send and receive transactional or one-to-one email through a mailbox you already own (Zoho, Google Workspace, Outlook).

  • Read inbound mail as structured, low-token data instead of parsing HTML.

  • Keep agents safe from prompt injection hidden in email content and stop them leaking credentials.

It may not be the right fit if you need to host new mailboxes — SpiderMail connects to mailboxes you already have, it is not an email-hosting provider and does not issue addresses. It is also not a bulk cold-outreach blaster: it sends one-to-one through your mailbox at your provider's limits, not a mass-mailing platform.

How email flows

Reading and sending take different paths, and knowing which is which explains the rest of this manual:

  • Reading (inbox, message, thread, search) is a direct, synchronous read from SpiderMail's store — a single API call returns data.

  • Sending (send, reply, forward) is asynchronous: you submit a job, get a job_id back immediately, and the SpiderMail worker delivers it over SMTP. You poll the job for the delivery result.

  • Inbound mail arrives on its own — a background poller checks each connected mailbox over IMAP every few minutes and stores new messages for you to read.

See Core Concepts for the full model.

How this manual is organized

  • Getting Started — what SpiderMail is, a quickstart, and the core concepts.

  • Mailboxes — connecting an IMAP/SMTP mailbox and managing it.

  • Sending Email — send, reply, forward, attachments, and AI compose.

  • Inbox & Messages — reading, searching, and organizing mail.

  • Templates — reusable Jinja2 email templates.

  • Security — the agent-safety layer (injection scanning, credential blocking, quarantine).

  • Build with AI Agents — drive SpiderMail from MCP and the CLI.

  • Reference — exact API endpoints, MCP tools, CLI commands, and authentication.

Next steps

  1. Follow the Quickstart to connect a mailbox and send your first email.

  2. Learn the Core Concepts.

  3. Connect an agent via Build with AI Agents, or jump to the API Reference.