# 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 the agent.

## Docs

Quickstarts, concepts and guides

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

### Getting started
- [What is MachineMail](https://machinemail.dev/docs/getting-started.md): MachineMail is an email API for AI agents. Every agent gets its own address, every inbound message carries a trust report, and the API is wire-compatible with AgentMail's /v0.
- [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 the API key, keep your code and the AgentMail SDKs, and pick up 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): Inboxes are email addresses your agents own. Learn about 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 stores email as messages grouped into threads, how labels and read state work, what extracted_text and the trust report give your agent, and how to fetch 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 inbox addresses and catch-all. Covers 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.
- [Sending](https://machinemail.dev/docs/concepts/sending.md): How sending email from a MachineMail inbox works. From addresses and display names, recipients, reply-to, text and HTML bodies, custom 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.
- [OTP codes and sign-up flows](https://machinemail.dev/docs/guides/otp-and-signups.md): Use ephemeral or catch-all inboxes to receive verification codes and magic links during sign-ups, extract them safely from the trust report, and let the inbox expire afterwards.
- [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.
- [Verify webhooks](https://machinemail.dev/docs/guides/verify-webhooks.md): Check the X-MachineMail-Signature header on every webhook delivery in TypeScript, Python and Go, reject replays, deduplicate 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, with filters, keepalives, reconnection, backfill from the event log and deduplication by event_id.
- [Use a custom domain](https://machinemail.dev/docs/guides/custom-domain.md): Add your own domain to MachineMail, publish the MX, SPF, DKIM and DMARC records (by hand, from a zone file or with Domain Connect), verify it, and turn on catch-all addresses.
- [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 use the trust report's attachment risk and extracted text before an agent opens anything.
- [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 of your customers in its own pod with its own inboxes, domains, webhooks, lists, events and pod-scoped API keys, using 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): Where MachineMail gets SPF, DKIM and DMARC results for inbound mail, why it ignores headers a sender can forge, checks alignment with the From domain, and how authentication feeds the trust level and score.
- [Content scrubbing](https://machinemail.dev/docs/trust/content.md): How MachineMail produces agent-safe text from inbound mail by removing hidden text, invisible Unicode, HTML tricks, quoted history and boilerplate, and how instruction-like content is detected.
- [Links](https://machinemail.dev/docs/trust/links.md): How MachineMail analyses every link in inbound mail for mismatched text, lookalike and punycode domains, raw IPs, shorteners, brand impersonation and other phishing signals.
- [Attachments](https://machinemail.dev/docs/trust/attachments.md): How MachineMail rates inbound attachments as low, medium or high risk from their extension, declared content type and actual bytes, and which attachments get extracted text.
- [Classifier](https://machinemail.dev/docs/trust/classifier.md): How the two-stage injection and phishing classifier scores inbound mail, rules first and a hosted model second, and what each probability, the category and the backend field mean.

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

## 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
- [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 Code, claude.ai, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Zed, Windsurf, Goose, OpenCode and other MCP clients to the hosted MachineMail MCP server, by signing in with OAuth or with 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 anonymous, service_auth and identity_assertion registration types, tokens and scopes, sandbox limits, the token endpoint and revocation, with full HTTP examples.
- [Claiming an agent](https://machinemail.dev/docs/agents/claiming.md): How a human claims an agent that registered itself through auth.md - entering the 6-digit code on the dashboard claim page, what changes after the claim, code and registration expiry, and revoking agents.

## CLI

Install, sign in and script MachineMail from a terminal

- [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, build it from source with Bun, and set up shell completions for bash, zsh and fish.
- [Authentication](https://machinemail.dev/docs/cli/authentication.md): Sign the CLI in through the browser with the device flow, give it an API key in CI, keep several keys in profiles, log out and revoke, and see where the key is stored and who can read it.

### Using the CLI
- [Output and scripting](https://machinemail.dev/docs/cli/output-and-scripting.md): How the CLI chooses between tables and JSON, NDJSON for streams, --json, --fields and --all, errors on stderr, exit codes, color and CI behavior, and patterns for shell scripts and agents with jq.
- [Agent workflows](https://machinemail.dev/docs/cli/agent-workflows.md): The CLI commands built for agents - a throwaway inbox and wait --otp for sign-ups, read with its trust verdict and agent-safe text, send, tail for live mail, and register and claim for an agent that starts with no account.
- [Configuration](https://machinemail.dev/docs/cli/configuration.md): Where the CLI keeps its config file and what is in it, profiles, the config keys, every environment variable it reads, and pointing it at another API base URL such as a local or self-hosted instance.
- [Troubleshooting](https://machinemail.dev/docs/cli/troubleshooting.md): Diagnose CLI problems with machinemail doctor and --verbose, and fix the common errors - no API key, a rejected key, an unreachable API, a broken config file, wait timeouts, deletes that need --yes and sign-in codes that expire.

### 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 their types and defaults, examples, and the API routes each command calls.

### Getting started
- [Sign-in and setup](https://machinemail.dev/docs/cli/commands/setup.md): Commands that sign the CLI in and out, show and check the credential in use, and register an agent without a human. Usage, flags and examples for `machinemail login`, `machinemail whoami`, `machinemail doctor`, `machinemail register`, `machinemail claim`, `machinemail logout`.

### Mail
- [Mail workflow](https://machinemail.dev/docs/cli/commands/mail.md): Top-level commands for the jobs agents and people do most: send a message, read one with its trust verdict, wait for a message or a verification code, and follow events live. Usage, flags and examples for `machinemail send`, `machinemail read`, `machinemail wait`, `machinemail tail`.
- [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): Allow and block lists for the organization, a pod or an inbox. A non-empty allow list is allow-only: one receive/allow entry blocks mail from every sender not on it. The `machinemail lists` commands: arguments, flags, examples and the API routes they call.
- [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.

### CLI
- [Utilities](https://machinemail.dev/docs/cli/commands/utilities.md): Open the dashboard, print shell completions and print the CLI version. Usage, flags and examples for `machinemail open`, `machinemail completion`, `machinemail 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.

## API reference

The HTTP API, MCP tools and webhook events

- [API overview](https://machinemail.dev/docs/reference.md): Base URL, versioning, authentication, request and response conventions.

### HTTP API
- [Authentication](https://machinemail.dev/docs/reference/authentication.md): API keys, key scopes, permissions, agent access tokens and the dashboard session.
- API
  - [Endpoints](https://machinemail.dev/docs/reference/api.md): Every MachineMail HTTP endpoint, grouped by resource.
  - [Inboxes](https://machinemail.dev/docs/reference/api/inboxes.md): Inboxes. inbox_id is the email address.
  - [Messages](https://machinemail.dev/docs/reference/api/messages.md): Send, receive, search and manage messages.
  - [Threads](https://machinemail.dev/docs/reference/api/threads.md): Conversation threads.
  - [Drafts](https://machinemail.dev/docs/reference/api/drafts.md): Drafts (unsent messages a person can send or delete) and scheduled sends (send_at).
  - [Trust](https://machinemail.dev/docs/reference/api/trust.md): Trust reports for inbound messages.
  - [Domains](https://machinemail.dev/docs/reference/api/domains.md): Custom domains, DNS records, catch-all.
  - [Webhooks](https://machinemail.dev/docs/reference/api/webhooks.md): Webhook endpoints, deliveries and replay.
  - [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: one receive/allow entry blocks mail from every sender not on it.
  - [Suppressions](https://machinemail.dev/docs/reference/api/suppressions.md): Addresses we will not send to.
  - [Events](https://machinemail.dev/docs/reference/api/events.md): Replayable event log and live streams.
  - [Metrics](https://machinemail.dev/docs/reference/api/metrics.md): Counts and rates.
  - [Export](https://machinemail.dev/docs/reference/api/export.md): Inbox export.
  - [Organization](https://machinemail.dev/docs/reference/api/organization.md): The authenticated organization.
  - [Auth](https://machinemail.dev/docs/reference/api/auth.md): The credential making the request: its organization, pod, inbox and permissions.
  - [Pods](https://machinemail.dev/docs/reference/api/pods.md): Pods group inboxes, domains and webhooks.
  - [API Keys](https://machinemail.dev/docs/reference/api/api-keys.md): Organization, pod and inbox scoped keys.
  - [Inbound](https://machinemail.dev/docs/reference/api/inbound.md): Raw message injection and the inbound webhooks of the mail providers.
  - [Health](https://machinemail.dev/docs/reference/api/health.md): Liveness and readiness.
  - [OpenAPI](https://machinemail.dev/docs/reference/api/openapi.md): This document.
  - [Agent Auth](https://machinemail.dev/docs/reference/api/agent-auth.md): The MachineMail authorization server: OAuth sign-in for apps and MCP clients (authorization code with PKCE, client registration) and the auth.md protocol for agent onboarding.
  - [Agent Registrations](https://machinemail.dev/docs/reference/api/agent-registrations.md): Agent registrations bound to the organization.
  - [Connected Apps](https://machinemail.dev/docs/reference/api/connected-apps.md): Apps and MCP clients connected with OAuth.
  - [MCP](https://machinemail.dev/docs/reference/api/mcp.md): Remote MCP server (Streamable HTTP) and its description document.
  - [CLI Auth](https://machinemail.dev/docs/reference/api/cli-auth.md): Signing the CLI in with the browser (RFC 8628 device authorization grant).
  - [Objects](https://machinemail.dev/docs/reference/api/objects.md): Every object the API accepts or returns, field by field.
  - [Dashboard Auth](https://machinemail.dev/docs/reference/api/dashboard-auth.md): Cookie sessions for the dashboard.
- [Errors](https://machinemail.dev/docs/reference/errors.md): The error envelope, every error type, and the messages the API returns.
- [Pagination](https://machinemail.dev/docs/reference/pagination.md): limit, page_token and next_page_token, and the endpoints that page differently.
- [Rate limits](https://machinemail.dev/docs/reference/rate-limits.md): Which endpoints are rate limited, the limits, and the 429 response.
- [Limits](https://machinemail.dev/docs/reference/limits.md): Inbox, address, TTL, message, attachment, batch, sandbox and retention limits.

### Events and tools
- [Webhook events](https://machinemail.dev/docs/reference/webhook-events.md): Every event type, the payload of each, signature verification, retries and replay.
- [MCP tools](https://machinemail.dev/docs/reference/mcp-tools.md): The tools, resources and prompt of the remote MCP server at /mcp.

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

## Pricing

- [Pricing](https://machinemail.dev/pricing.md): plans, what counts as a message, and answers to common questions, 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