# MachineMail

> Email for AI agents. Every agent gets its own address for free, and every inbound message arrives with a trust report so nothing in the inbox can hijack it.

## Docs

Quickstarts, concepts and guides

- [Overview](https://machinemail.dev/docs/index.md)

### Getting started
- [What is MachineMail](https://machinemail.dev/docs/getting-started.md): An email API for AI agents: each agent gets its own address, every inbound message carries a trust report, and the /v0 API is wire-compatible with AgentMail.
- [Quickstart](https://machinemail.dev/docs/getting-started/quickstart.md): Sign up with a magic link, get an API key, create an inbox, send an email and receive replies by polling, webhook and Server-Sent Events.
- [Agent quickstart](https://machinemail.dev/docs/getting-started/agent-quickstart.md): Paste one prompt into Claude Code, Cursor, Codex or OpenCode and the agent signs itself up through auth.md, gets a sandbox inbox and asks you to claim it.
- [Switching from AgentMail](https://machinemail.dev/docs/getting-started/from-agentmail.md): MachineMail serves AgentMail's /v0 API. Change the base URL and API key, keep your code and SDKs, and gain trust reports, catch-all and ephemeral inboxes.

### Concepts
- [Organizations and pods](https://machinemail.dev/docs/concepts/organizations-and-pods.md): How MachineMail groups resources. An organization owns everything; pods split it into isolated groups, such as one per end customer.
- [API keys](https://machinemail.dev/docs/concepts/api-keys.md): How MachineMail API keys work, how to scope them to a pod or a single inbox, and how to limit them to specific permissions.
- [Inboxes](https://machinemail.dev/docs/concepts/inboxes.md): The addresses your agents own: named, generated, ephemeral and catch-all inboxes, the shared machinemail.dev domain, custom domains, pausing and deletion.
- [Threads and messages](https://machinemail.dev/docs/concepts/threads-and-messages.md): How MachineMail groups messages into threads, labels and read state, what extracted_text and the trust report give your agent, and attachments and raw MIME.
- [Drafts](https://machinemail.dev/docs/concepts/drafts.md): Drafts let an agent prepare a message without sending it, for human review or for scheduled sending with send_at.
- [Domains](https://machinemail.dev/docs/concepts/domains.md): Add your own domain to MachineMail for custom addresses and catch-all: DNS records, verification states, DNS host detection, Domain Connect and the zone file.
- [Events](https://machinemail.dev/docs/concepts/events.md): Everything that happens in MachineMail is recorded as an event. Read the event log, stream events over SSE or WebSocket, or receive them as webhooks.
- [Webhooks](https://machinemail.dev/docs/concepts/webhooks.md): MachineMail webhooks POST signed events to your HTTPS endpoint, filtered by event type, pod or inbox, with retries for five days and a replayable delivery log.
- [Lists and suppressions](https://machinemail.dev/docs/concepts/lists-and-suppressions.md): Allow and block lists control who can email your inboxes and who they can send to. Suppressions stop sending to addresses that bounced or complained.
- [Trusted domains](https://machinemail.dev/docs/concepts/trusted-domains.md): Mark the domains and addresses you work with as trusted, so their genuinely signed mail is never quarantined or withheld from your agents.
- [Sending](https://machinemail.dev/docs/concepts/sending.md): Sending from a MachineMail inbox: from addresses, display names, recipients, reply-to, text and HTML bodies, headers, attachments, replies, forwards and limits.

### Guides
- [Give an agent an inbox](https://machinemail.dev/docs/guides/give-an-agent-an-inbox.md): Build the full loop for an email-driven agent. Create an inbox, wait for mail, read the trust report, act, reply in the same thread and mark the message read.
- [Connect an agent without code](https://machinemail.dev/docs/guides/connect-an-agent.md): Give an AI agent a MachineMail inbox from the dashboard: claim it with the agent prompt, approve an MCP client or approve the CLI, then manage access in Settings.
- [Create a key for an agent](https://machinemail.dev/docs/guides/api-key-for-an-agent.md): Create a narrow MachineMail API key for one agent from the dashboard or the API: pick its scope and permissions, copy it once, hand it over, revoke it later.
- [OTP codes and sign-up flows](https://machinemail.dev/docs/guides/otp-and-signups.md): Receive sign-up verification codes and magic links in ephemeral or catch-all inboxes, extract them safely using the trust report, and let the inbox expire.
- [Reply in thread](https://machinemail.dev/docs/guides/reply-in-thread.md): Reply, reply-all and forward from an inbox, keep conversations threaded with In-Reply-To and References, prepare replies as drafts, and label whole threads.
- [Write a new message in the dashboard](https://machinemail.dev/docs/guides/send-from-the-dashboard.md): Write and send a new email from any MachineMail inbox in the dashboard: pick the sender, add recipients and attachments, undo a send, or keep the message as a draft.
- [Approve drafts before they send](https://machinemail.dev/docs/guides/approve-drafts.md): Review the drafts your agents save in the MachineMail dashboard: edit them, send now or retry a failed send, undo a send in the first seconds, or delete them.
- [Review quarantined mail](https://machinemail.dev/docs/guides/review-quarantine.md): Find quarantined threads in the MachineMail dashboard, read the trust report, compare agent-safe and raw views, then release it or block the sender's domain.
- [Verify webhooks](https://machinemail.dev/docs/guides/verify-webhooks.md): Verify the X-MachineMail-Signature header on webhook deliveries in TypeScript, Python and Go, reject replays, dedupe retries, and test or replay deliveries.
- [Realtime events](https://machinemail.dev/docs/guides/realtime-events.md): Consume MachineMail events live over Server-Sent Events or WebSocket: filters, keepalives, reconnection, backfill from the event log and dedupe by event_id.
- [Use a custom domain](https://machinemail.dev/docs/guides/custom-domain.md): Add your own domain to MachineMail: publish MX, SPF, DKIM and DMARC records by hand, from a zone file or with Domain Connect, verify it and turn on catch-all.
- [Invite your team and secure your account](https://machinemail.dev/docs/guides/team-and-security.md): Invite people to a MachineMail organization, set roles, add passkeys, turn off email codes, sign out other sessions, and switch, create or delete organizations.
- [Attachments](https://machinemail.dev/docs/guides/attachments.md): Send files as base64 or from a URL, embed inline images, download attachments from received mail, and check their trust risk before an agent opens one.
- [Search and export](https://machinemail.dev/docs/guides/search-and-export.md): Find messages, threads and inboxes with full-text search and filters, fetch messages in batches, and export an inbox as mbox or JSON lines.
- [Multi-tenant apps with pods](https://machinemail.dev/docs/guides/multi-tenant-with-pods.md): Isolate each customer in its own pod with its own inboxes, domains, webhooks, lists, events and pod-scoped API keys, all in one MachineMail organization.

## Trust & safety

How every inbound message is checked before your agent reads it

- [Trust layer](https://machinemail.dev/docs/trust.md): Why email is a prompt-injection vector for AI agents, what MachineMail checks on every inbound message, and where the resulting trust report shows up.
- [Trust report](https://machinemail.dev/docs/trust/trust-report.md): Every field of the trust report attached to inbound messages, how level and score are computed, and a full JSON example.

### Signals
- [Authentication](https://machinemail.dev/docs/trust/authentication.md): How MachineMail gets SPF, DKIM and DMARC results for inbound mail without trusting forgeable headers, checks From alignment and feeds the trust level and score.
- [Content scrubbing](https://machinemail.dev/docs/trust/content.md): How MachineMail turns inbound mail into agent-safe text by stripping hidden text, invisible Unicode, HTML tricks, quoted history and boilerplate.
- [Links](https://machinemail.dev/docs/trust/links.md): How MachineMail checks every link in inbound mail for mismatched text, lookalike and punycode domains, raw IPs, shorteners and brand impersonation.
- [Attachments](https://machinemail.dev/docs/trust/attachments.md): How MachineMail rates inbound attachments low, medium or high risk from their extension, declared type and actual bytes, and which ones get extracted text.
- [Classifier](https://machinemail.dev/docs/trust/classifier.md): How MachineMail's two-stage classifier scores inbound mail for injection and phishing, rules first and a hosted model second, and what each output field means.

### In practice
- [Using trust in agents](https://machinemail.dev/docs/trust/using-trust-in-agents.md): Patterns for agents that read email: gate tool use on the trust level, respect quarantine, feed the model only agent-safe text and wrap email as untrusted data.

## Agents & MCP

MCP, client setup and agent self-registration

- [Agents](https://machinemail.dev/docs/agents.md): The three ways an AI agent uses MachineMail - the REST API, the hosted MCP server, and self-registration through auth.md - and how to choose between them.

### MCP
- [MachineMail MCP server](https://machinemail.dev/docs/agents/mcp.md): The hosted MachineMail MCP server - endpoint, stateless Streamable HTTP transport, OAuth sign-in or an API key, and the tools, resources and prompt it exposes.
- [Client setup](https://machinemail.dev/docs/agents/clients.md): Connect ChatGPT, Claude, Cursor, VS Code, Codex, Gemini CLI and other MCP clients to the hosted MachineMail MCP server, signing in with OAuth or an API key.

### Self-registration
- [auth.md registration](https://machinemail.dev/docs/agents/auth-md.md): How an AI agent registers itself with MachineMail through auth.md: discovery, the three registration types, tokens and scopes, sandbox limits and revocation.
- [Sandbox](https://machinemail.dev/docs/agents/sandbox.md): MachineMail's sandbox for agents: how an agent gets a working inbox and token with no account and no API key, what the sandbox can do, its limits, and how a claim ends it.
- [Claiming an agent](https://machinemail.dev/docs/agents/claiming.md): How a human claims an agent that registered through auth.md: entering the 6-digit code on the dashboard, what the claim changes, expiry, and revoking agents.

## CLI

Install, sign in and script MachineMail from a terminal

- [MachineMail CLI](https://machinemail.dev/docs/cli.md): The machinemail command line tool - what it covers, how to install it and sign in, and the first commands to run, from a terminal or a script.

### Get started
- [Installation](https://machinemail.dev/docs/cli/installation.md): Install the machinemail CLI on macOS, Linux or Windows, pin a version, and set up shell completions for bash, zsh and fish.
- [Authentication](https://machinemail.dev/docs/cli/authentication.md): Sign the MachineMail CLI in through the browser or with an API key in CI, keep several keys in profiles, log out and revoke, and see where the key is stored.

### Using the CLI
- [Output and scripting](https://machinemail.dev/docs/cli/output-and-scripting.md): How the MachineMail CLI picks tables or JSON, NDJSON streams, --json, --fields and --all, errors and exit codes, CI behavior and scripting patterns with jq.
- [Agent workflows](https://machinemail.dev/docs/cli/agent-workflows.md): MachineMail CLI commands built for agents: throwaway inboxes and wait --otp for sign-ups, read with trust verdicts, send, tail live mail, register and claim.
- [Configuration](https://machinemail.dev/docs/cli/configuration.md): Where the CLI keeps its config file and what is in it, profiles, the config keys, the base URL and every environment variable it reads.
- [Troubleshooting](https://machinemail.dev/docs/cli/troubleshooting.md): Diagnose MachineMail CLI problems with doctor and --verbose, and fix common errors: missing or rejected keys, an unreachable API, broken config and timeouts.

### Command reference
- [Command reference](https://machinemail.dev/docs/cli/commands.md): Every machinemail command, generated from the CLI's own command tree: usage, arguments, flags with types and defaults, examples and the API routes they call.

### Getting started
- [Sign-in and setup](https://machinemail.dev/docs/cli/commands/setup.md): MachineMail CLI commands to sign in and out, show and check the credential in use with whoami and doctor, and register or claim an agent without a human.

### Mail
- [Mail workflow](https://machinemail.dev/docs/cli/commands/mail.md): The MachineMail CLI mail commands: send a message, read one with its trust verdict, wait for a message or a verification code, and tail events live.
- [messages](https://machinemail.dev/docs/cli/commands/messages.md): Send, receive, search and manage messages. The `machinemail messages` commands: arguments, flags, examples and the API routes they call.
- [threads](https://machinemail.dev/docs/cli/commands/threads.md): Conversation threads. The `machinemail threads` commands: arguments, flags, examples and the API routes they call.
- [drafts](https://machinemail.dev/docs/cli/commands/drafts.md): Drafts, and sends scheduled for later. The `machinemail drafts` commands: arguments, flags, examples and the API routes they call.
- [inbound](https://machinemail.dev/docs/cli/commands/inbound.md): Inject raw RFC 5322 messages (needs the inbound_raw permission). The `machinemail inbound` commands: arguments, flags, examples and the API routes they call.

### Inboxes
- [inboxes](https://machinemail.dev/docs/cli/commands/inboxes.md): Inboxes (an inbox id is its email address). The `machinemail inboxes` commands: arguments, flags, examples and the API routes they call.
- [pods](https://machinemail.dev/docs/cli/commands/pods.md): Pods group inboxes, domains and webhooks. The `machinemail pods` commands: arguments, flags, examples and the API routes they call.
- [lists](https://machinemail.dev/docs/cli/commands/lists.md): Manage allow and block lists for the organization, a pod or an inbox from the MachineMail CLI: create, get, list and delete entries, with flags and examples.
- [suppressions](https://machinemail.dev/docs/cli/commands/suppressions.md): Addresses we will not send to. The `machinemail suppressions` commands: arguments, flags, examples and the API routes they call.

### Domains
- [domains](https://machinemail.dev/docs/cli/commands/domains.md): Custom domains, DNS records, catch-all. The `machinemail domains` commands: arguments, flags, examples and the API routes they call.

### Webhooks
- [webhooks](https://machinemail.dev/docs/cli/commands/webhooks.md): Webhook endpoints, deliveries and replay. The `machinemail webhooks` commands: arguments, flags, examples and the API routes they call.
- [events](https://machinemail.dev/docs/cli/commands/events.md): Replayable event log and live streams. The `machinemail events` commands: arguments, flags, examples and the API routes they call.

### Admin
- [org](https://machinemail.dev/docs/cli/commands/org.md): The authenticated organization. The `machinemail org` commands: arguments, flags, examples and the API routes they call.
- [api-keys](https://machinemail.dev/docs/cli/commands/api-keys.md): Organization, pod and inbox scoped keys. The `machinemail api-keys` commands: arguments, flags, examples and the API routes they call.
- [agent-registrations](https://machinemail.dev/docs/cli/commands/agent-registrations.md): Agent registrations bound to the organization. The `machinemail agent-registrations` commands: arguments, flags, examples and the API routes they call.
- [metrics](https://machinemail.dev/docs/cli/commands/metrics.md): Counts and rates. The `machinemail metrics` commands: arguments, flags, examples and the API routes they call.
- [health](https://machinemail.dev/docs/cli/commands/health.md): Liveness and readiness. The `machinemail health` commands: arguments, flags, examples and the API routes they call.
- [import](https://machinemail.dev/docs/cli/commands/import.md): Copy pods, domains, inboxes, webhooks and allow and block lists from AgentMail into MachineMail with the import agentmail command: flags and examples.

### CLI
- [Utilities](https://machinemail.dev/docs/cli/commands/utilities.md): MachineMail CLI utility commands: open the dashboard in a browser, print a shell completion script for bash, zsh or fish, and print the CLI version.
- [auth](https://machinemail.dev/docs/cli/commands/auth.md): Sign in with an API key and inspect the credential. The `machinemail auth` commands: arguments, flags, examples and the API routes they call.
- [config](https://machinemail.dev/docs/cli/commands/config.md): Read and change CLI settings (config file, keys masked). The `machinemail config` commands: arguments, flags, examples and the API routes they call.
- [profiles](https://machinemail.dev/docs/cli/commands/profiles.md): Named sets of API key and base URL; switch between them. The `machinemail profiles` commands: arguments, flags, examples and the API routes they call.

### More
- [connected-apps](https://machinemail.dev/docs/cli/commands/connected-apps.md): Apps and MCP clients connected with OAuth. The `machinemail connected-apps` commands: arguments, flags, examples and the API routes they call.
- [trusted-domains](https://machinemail.dev/docs/cli/commands/trusted-domains.md): Manage the domains and addresses whose signed mail is never quarantined, for the organization, a pod or an inbox, from the MachineMail CLI: flags and examples.

## API reference

The HTTP API, MCP tools and webhook events

- [MachineMail API reference](https://machinemail.dev/docs/reference.md): MachineMail API conventions: the base URL, /v0 versioning, authentication, requests and responses, pagination, idempotency, request IDs, CORS and scoped routes.

### HTTP API
- [Authentication](https://machinemail.dev/docs/reference/authentication.md): How to authenticate with the MachineMail API: API keys, key scopes and permissions, agent access tokens, and the dashboard session, passkeys and invitations.
- API
  - [Endpoints](https://machinemail.dev/docs/reference/api.md): Every MachineMail HTTP endpoint grouped by resource, with the base URL, the API version and where to fetch the OpenAPI document. Start here to find a route.
  - [Inboxes](https://machinemail.dev/docs/reference/api/inboxes.md): Create, list, search, read, update, pause and delete MachineMail inboxes, and check whether an address is available. The inbox_id is the email address.
  - [Messages](https://machinemail.dev/docs/reference/api/messages.md): Send, reply to, forward, list, search, read and update messages in a MachineMail inbox, one at a time or in batches, and download attachments and raw MIME.
  - [Threads](https://machinemail.dev/docs/reference/api/threads.md): List, search, read, update and delete conversation threads in MachineMail, across the whole organization, within a pod or in a single inbox.
  - [Drafts](https://machinemail.dev/docs/reference/api/drafts.md): Create, update, send and delete drafts: unsent messages a person or agent can review before they go out, including sends scheduled for later with send_at.
  - [Trust](https://machinemail.dev/docs/reference/api/trust.md): Fetch the trust report for an inbound message: trust level and score, authentication results, sender, content, link and attachment checks and classification.
  - [Domains](https://machinemail.dev/docs/reference/api/domains.md): Add custom domains to MachineMail, get their DNS records, zone file and Domain Connect setup, verify them and turn on catch-all, for the organization or a pod.
  - [Webhooks](https://machinemail.dev/docs/reference/api/webhooks.md): Create and manage webhook endpoints for the organization, a pod or an inbox: set custom headers, send test events, list deliveries and replay failed ones.
  - [Lists](https://machinemail.dev/docs/reference/api/lists.md): Allow and block lists for the organization, a pod or an inbox. A non-empty allow list is allow-only: it blocks mail from every sender not on it.
  - [Trusted Domains](https://machinemail.dev/docs/reference/api/trusted-domains.md): Domains and addresses the organization, a pod or an inbox trusts: mail they genuinely sign is never quarantined or withheld from agents. Preview an entry first.
  - [Suppressions](https://machinemail.dev/docs/reference/api/suppressions.md): List, add, check and remove the addresses MachineMail will not send to. Permanent bounces and complaints add an address to the suppression list automatically.
  - [Events](https://machinemail.dev/docs/reference/api/events.md): Read MachineMail's replayable event log for the organization, a pod or an inbox, or follow events live over Server-Sent Events or a WebSocket.
  - [Metrics](https://machinemail.dev/docs/reference/api/metrics.md): Query MachineMail metrics for the organization, a pod or an inbox: event counts over a time range, rolling bounce and complaint rates, and current usage.
  - [Export](https://machinemail.dev/docs/reference/api/export.md): Export every message in a MachineMail inbox, oldest first, as one mbox file of raw MIME or as JSON Lines with one Message object per line.
  - [Organization](https://machinemail.dev/docs/reference/api/organization.md): Read, update and delete your MachineMail organization, invite and manage its members, and check the plan, its allowances and usage in the current period.
  - [Auth](https://machinemail.dev/docs/reference/api/auth.md): GET /v0/auth/me returns the credential making the request: its organization, pod and inbox and its permissions. Use it to discover what a key can reach.
  - [Pods](https://machinemail.dev/docs/reference/api/pods.md): Create, list, update and delete pods: groups of inboxes, domains and webhooks that keep each tenant separate inside one MachineMail organization.
  - [API Keys](https://machinemail.dev/docs/reference/api/api-keys.md): Create, list, update and delete MachineMail API keys scoped to the whole organization, to one pod or to a single inbox, each with its own permissions.
  - [Inbound](https://machinemail.dev/docs/reference/api/inbound.md): Store a raw RFC 5322 message in your inboxes as if it had been received. Requires the inbound_raw permission; authentication results in the message are ignored.
  - [Health](https://machinemail.dev/docs/reference/api/health.md): Liveness and readiness checks for the MachineMail API, with no authentication: /health while the process serves requests, /health/ready when storage answers.
  - [OpenAPI](https://machinemail.dev/docs/reference/api/openapi.md): Fetch the MachineMail OpenAPI 3.1 document as JSON from GET /v0/openapi.json, with no authentication, to generate clients or load the API into your tools.
  - [Agent Auth](https://machinemail.dev/docs/reference/api/agent-auth.md): MachineMail's authorization server: OAuth sign-in with PKCE and client registration for apps and MCP clients, and the auth.md agent onboarding endpoints.
  - [Agent Registrations](https://machinemail.dev/docs/reference/api/agent-registrations.md): List, inspect and revoke the agents that registered themselves through auth.md and are bound to your MachineMail organization. Needs an organization key.
  - [Connected Apps](https://machinemail.dev/docs/reference/api/connected-apps.md): List the apps and MCP clients people in your organization connected to MachineMail with OAuth, and disconnect one to revoke its tokens immediately.
  - [MCP](https://machinemail.dev/docs/reference/api/mcp.md): The remote MCP server endpoint (stateless JSON-RPC over Streamable HTTP), its description document and signed attachment links, with API key or OAuth auth.
  - [CLI Auth](https://machinemail.dev/docs/reference/api/cli-auth.md): The device authorization endpoints (RFC 8628) behind CLI sign-in: start a sign-in, approve or deny it in the browser, and poll until the CLI receives its key.
  - [Objects](https://machinemail.dev/docs/reference/api/objects.md): Every object the MachineMail API accepts or returns, field by field, with types and required fields. Endpoint pages link here for nested objects.
  - [Dashboard Auth](https://machinemail.dev/docs/reference/api/dashboard-auth.md): Cookie-session endpoints behind the MachineMail dashboard: sign-in codes, magic links, passkeys, invitations, organizations and sessions. Not for integrations.
- [Errors](https://machinemail.dev/docs/reference/errors.md): The MachineMail API error envelope, every error type and the messages each area returns, plus agent onboarding and MCP errors and how to handle them.
- [Pagination](https://machinemail.dev/docs/reference/pagination.md): How MachineMail list endpoints page with limit, page_token and next_page_token: walking every page, sort order, and the endpoints that page differently.
- [Rate limits](https://machinemail.dev/docs/reference/rate-limits.md): The REST API's request rate and its RateLimit headers, the other rate limited endpoints (sign-in, agent registration, claims, sandbox sends, MCP feedback), their limits and the 429 response.
- [Limits](https://machinemail.dev/docs/reference/limits.md): Plan limits and how they are enforced, and inbox, address, TTL, message, attachment, batch, sandbox and retention limits.

### Events and tools
- [Webhook events](https://machinemail.dev/docs/reference/webhook-events.md): Every MachineMail webhook event type and its payload, the event envelope, delivery retries and replay, and how to verify the signature on each delivery.
- [MCP tools](https://machinemail.dev/docs/reference/mcp-tools.md): The tools, resources and triage prompt of MachineMail's remote MCP server at /mcp, with its transport, authentication, permissions and errors.

### Migrating
- [AgentMail compatibility](https://machinemail.dev/docs/reference/agentmail-compatibility.md): How MachineMail's /v0 API compares with AgentMail's: what works the same, what differs, what is missing, how to switch and what MachineMail adds.

## Pricing

- [Pricing](https://machinemail.dev/pricing.md): plans, what counts as a message, and answers to common questions, as Markdown

## Comparisons

- [MachineMail vs AgentMail](https://machinemail.dev/compare/agentmail.md): where each is ahead, with a source for every claim, as Markdown
- [All comparisons](https://machinemail.dev/compare/index.md)

## Changelog

- [Changelog](https://machinemail.dev/changelog/index.md): what is new in MachineMail, newest first, as Markdown

## Optional

- [Everything in one file](https://machinemail.dev/docs/llms-full.txt): every page above, as Markdown
- [auth.md](https://machinemail.dev/auth.md): how an agent registers itself and gets an API key, as Markdown