--- title: "What is MachineMail" description: "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." canonical: "https://machinemail.dev/docs/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. Source: https://machinemail.dev/docs/getting-started MachineMail gives an AI agent its own email address and a REST API to send, receive and reply. It also inspects every inbound message before your agent sees it, so a hostile email cannot quietly take over the agent that reads it. It is a hosted service. The API lives at `https://api.machinemail.dev`, the dashboard at [machinemail.dev](https://machinemail.dev), and the MCP server at `https://mcp.machinemail.dev/mcp`. ## What you get - **Inboxes on demand.** Create an address on the shared `machinemail.dev` domain with one call, or on your own domain. Inbox count is not a billing quota. On the shared domain each organization can hold up to 1,000 addresses. - **Ephemeral and catch-all inboxes.** Give an inbox a `ttl_seconds` and it deletes itself, messages and all, when it expires. Turn on catch-all for a custom domain and any address on it works the moment mail arrives. - **A trust report on every inbound message.** Authentication results (SPF, DKIM, DMARC), what MachineMail knows about the sender, an agent-safe version of the body with quotes, signatures and hidden text removed, link and attachment checks, and classifier scores for phishing and prompt injection. Mail that tries to instruct your agent is quarantined. See [Trust](https://machinemail.dev/docs/trust). - **Threads, drafts and replies.** Standard email threading, reply, reply-all, forward, drafts and scheduled sends. - **Events three ways.** Signed webhooks with retries and replay, a Server-Sent Events stream, and a WebSocket. Every event is also stored in a replayable log. - **A CLI.** `machinemail` (or `mm`) covers every endpoint from a terminal, with commands for agents such as `wait --otp`, and prints JSON when piped. See [CLI](https://machinemail.dev/docs/cli). - **MCP.** A hosted Streamable HTTP MCP server with tools such as `wait_for_message`, so an agent can block until a verification code arrives. See [MCP server](https://machinemail.dev/docs/agents/mcp). - **Agent self-registration.** An agent can sign itself up by reading `/auth.md`, get a sandbox inbox straight away, and later be claimed by a human. See [auth.md](https://machinemail.dev/docs/agents/auth-md). - **AgentMail compatibility.** MachineMail serves AgentMail's `/v0` paths, field names and enum values. The AgentMail SDKs work with a base URL change. See [Switching from AgentMail](https://machinemail.dev/docs/getting-started/from-agentmail). ## How it fits an agent An agent typically uses MachineMail in a loop: 1. **Get an address.** Create an inbox for the agent, or one per task. 2. **Use it.** Sign up for a service, email a person, or wait for someone to write in. 3. **Wait for mail.** Receive a webhook, listen on the event stream, poll the messages list, or call the MCP `wait_for_message` tool. 4. **Check trust before acting.** Read `trust.level` and `trust.reasons`, and hand the model `trust.content.text` instead of the raw body. 5. **Act and reply.** Reply in the same thread, label the message, or ignore it. ```text title="The loop" create inbox ──► mail arrives ──► trust report ──► agent decides ──► reply in thread │ ├─ webhook (signed POST) ├─ SSE / WebSocket └─ polling or MCP wait_for_message ``` ## Core objects | Object | ID | What it is | | ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | Organization | `org_...` | Your account. Owns everything below. | | Pod | `pod_...` | A partition inside an organization, for example one per end customer. Every organization has a default pod. | | Inbox | the email address | An address that can send and receive. `inbox_id` is the address itself, for example `support-agent@machinemail.dev`. | | Thread | `thd_...` | A conversation, grouped by `In-Reply-To` and `References`. | | Message | `msg_...` | One email, inbound or outbound. Inbound messages carry `trust`. | | Draft | `drf_...` | An unsent message, optionally scheduled with `send_at`. | | Domain | `dom_...` | A custom domain with its DNS records and verification state. | | Webhook | `whk_...` | An HTTPS endpoint that receives signed events. | | Event | `evt_...` | One entry in the event log. | | API key | `key_...` | A bearer credential scoped to an organization, pod or inbox. | Read more in [Organizations and pods](https://machinemail.dev/docs/concepts/organizations-and-pods), [Inboxes](https://machinemail.dev/docs/concepts/inboxes) and [Threads and messages](https://machinemail.dev/docs/concepts/threads-and-messages). ## API basics - Authenticate with `Authorization: Bearer `. Keys look like `mm_live_` followed by 32 characters. - Bodies and responses are JSON with snake\_case fields. Timestamps are ISO 8601 in UTC. - Lists take `limit` (default 50, max 500) and `page_token`, and return `count`, `limit` and `next_page_token`. - `client_id` on create calls is an idempotency key: send the same one twice and you get the existing resource back with `200` instead of `201`. - Errors look like `{"error": {"type": "not_found", "message": "...", "param": "..."}}`. Resources outside your key's scope return `404`, not `403`. Details are in the [API reference](https://machinemail.dev/docs/reference). ## Next - [Quickstart](https://machinemail.dev/docs/getting-started/quickstart): Sign up, create an inbox, send and receive in a few minutes. - [Let your agent set itself up](https://machinemail.dev/docs/getting-started/agent-quickstart): Paste one prompt into Claude Code, Cursor, Codex or OpenCode. - [Switching from AgentMail](https://machinemail.dev/docs/getting-started/from-agentmail): Change the base URL and the key. Keep your code. - [Trust](https://machinemail.dev/docs/trust): What the trust report checks and how agents should use it.