MachineMail Docs

MachineMail is an email API built for software that reads and writes its own mail. Create an inbox with one call, send and receive from it, and get each inbound message back as structured JSON with an agent-safe body and a verdict on whether it can be trusted.

Free addresses. Inboxes on the shared machinemail.dev domain cost nothing. Make one per agent, per task or per signup flow. Ephemeral inboxes expire on their own, and a catch-all domain turns every address into an inbox the moment mail arrives.
A trust layer on every message. SPF, DKIM and DMARC, sender history, hidden text and zero-width characters, link and attachment checks, and a classifier that flags prompt injection, phishing and requests for credentials. Your agent reads the cleaned body and the verdict, not raw HTML from a stranger.
AgentMail-compatible. The /v0 API follows AgentMail’s paths, field names and enums, so an existing client switches with a base URL change.
Built for agents. A hosted MCP server, real-time events over webhooks, Server-Sent Events and WebSockets, and auth.md self-registration: an agent can sign itself up and get an API key, and a human claims it later.

30 seconds with curl

Get an API key from the dashboard, then create an inbox and send from it:

Terminal

export MACHINEMAIL_API_KEY=mm_live_...

# Create an inbox on the shared domain
curl https://api.machinemail.dev/v0/inboxes \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "research-agent"}'

# Send from it
curl https://api.machinemail.dev/v0/inboxes/research-agent@machinemail.dev/messages/send \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": ["you@example.com"], "subject": "Hello", "text": "Sent by an agent."}'

# Read what came back, trust report included
curl https://api.machinemail.dev/v0/inboxes/research-agent@machinemail.dev/messages \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Every inbound message carries a trust object. Check trust.level before your agent acts on anything in the message. This one tried to give the agent instructions in hidden text, so it was quarantined:

message.trust (abridged)

{
  "level": "quarantined",
  "score": 0.12,
  "authentication": { "spf": "pass", "dkim": "fail", "dmarc": "fail", "aligned": false },
  "classification": { "contains_instructions_to_agent": 0.94, "is_phishing": 0.62 },
  "reasons": ["DKIM failed", "Hidden text addressed to an AI assistant"]
}

The quickstart walks the whole loop, including receiving replies by webhook and SSE.

Where to go next

Getting started

Concepts

Organizations and pods, API keys, inboxes, threads and messages, drafts, domains, events and webhooks.

Guides

Task-sized recipes: one inbox per agent, OTPs and signups, replying in thread, verifying webhooks, custom domains.

Trust layer

What the trust report checks, what each field means, and how to gate an agent’s actions on it.

Agents

The hosted MCP server, client setup, and auth.md self-registration with human claiming.

CLI

The machinemail command line tool: sign in, create inboxes, send, wait for verification codes and script the API from a terminal.

API reference

Every /v0 endpoint, object and webhook payload, with request and response schemas.

For agents reading this

These docs are available as Markdown. /docs/llms.txt indexes every page, /docs/llms-full.txt is all of them in one file, any page is available at its URL plus .md, and any page URL requested with Accept: text/markdown returns Markdown.