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

Getting started

• What is MachineMail: 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: 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: 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: 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: How MachineMail groups resources. An organization owns everything; pods split it into isolated groups, such as one per end customer.
• API keys: 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: 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: 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: Drafts let an agent prepare a message without sending it, for human review or for scheduled sending with send_at.
• Domains: 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: 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: 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: 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: Mark the domains and addresses you work with as trusted, so their genuinely signed mail is never quarantined or withheld from your agents.
• Sending: 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: 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: Give an AI agent a MachineMail inbox from the dashboard: claim it with the agent prompt, approve an MCP app or approve the CLI, then manage access in Settings.
• Create a key for an agent: 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: 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: 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.
• Approve drafts before they send: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: Every field of the trust report attached to inbound messages, how level and score are computed, and a full JSON example.

Signals

• Authentication: 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: How MachineMail turns inbound mail into agent-safe text by stripping hidden text, invisible Unicode, HTML tricks, quoted history and boilerplate.
• Links: How MachineMail checks every link in inbound mail for mismatched text, lookalike and punycode domains, raw IPs, shorteners and brand impersonation.
• Attachments: 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: 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: 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: 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: 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: 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: How an AI agent registers itself with MachineMail through auth.md: discovery, the three registration types, tokens and scopes, sandbox limits and revocation.
• Claiming an agent: 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

• CLI: 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: Install the machinemail CLI on macOS, Linux or Windows, pin a version, and set up shell completions for bash, zsh and fish.
• Authentication: 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: 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: 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: 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: 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: 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: 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: 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: Send, receive, search and manage messages. The machinemail messages commands: arguments, flags, examples and the API routes they call.
• threads: Conversation threads. The machinemail threads commands: arguments, flags, examples and the API routes they call.
• drafts: Drafts, and sends scheduled for later. The machinemail drafts commands: arguments, flags, examples and the API routes they call.
• inbound: 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: Inboxes (an inbox id is its email address). The machinemail inboxes commands: arguments, flags, examples and the API routes they call.
• pods: Pods group inboxes, domains and webhooks. The machinemail pods commands: arguments, flags, examples and the API routes they call.
• lists: 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: Addresses we will not send to. The machinemail suppressions commands: arguments, flags, examples and the API routes they call.

Domains

• domains: Custom domains, DNS records, catch-all. The machinemail domains commands: arguments, flags, examples and the API routes they call.

Webhooks

• webhooks: Webhook endpoints, deliveries and replay. The machinemail webhooks commands: arguments, flags, examples and the API routes they call.
• events: Replayable event log and live streams. The machinemail events commands: arguments, flags, examples and the API routes they call.

Admin

• org: The authenticated organization. The machinemail org commands: arguments, flags, examples and the API routes they call.
• api-keys: Organization, pod and inbox scoped keys. The machinemail api-keys commands: arguments, flags, examples and the API routes they call.
• agent-registrations: Agent registrations bound to the organization. The machinemail agent-registrations commands: arguments, flags, examples and the API routes they call.
• metrics: Counts and rates. The machinemail metrics commands: arguments, flags, examples and the API routes they call.
• health: Liveness and readiness. The machinemail health commands: arguments, flags, examples and the API routes they call.
• import: Copy pods, domains, inboxes, webhooks and allow and block lists from AgentMail into MachineMail with the import agentmail command: flags and examples.

CLI

• Utilities: 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: Sign in with an API key and inspect the credential. The machinemail auth commands: arguments, flags, examples and the API routes they call.
• config: Read and change CLI settings (config file, keys masked). The machinemail config commands: arguments, flags, examples and the API routes they call.
• profiles: Named sets of API key and base URL; switch between them. The machinemail profiles commands: arguments, flags, examples and the API routes they call.