---
title: "MachineMail"
description: "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."
canonical: "https://machinemail.dev/docs"
---

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

Source: https://machinemail.dev/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](https://machinemail.dev/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](https://machinemail.dev/app/api-keys), then create an inbox and send from it:

```bash title="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:

```json title="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](https://machinemail.dev/docs/getting-started/quickstart) walks the whole loop, including receiving replies by webhook and SSE.

## Where to go next

- [Getting started](https://machinemail.dev/docs/getting-started): Sign up, get a key, create an inbox and send your first message. Or let your agent register itself.
- [Concepts](https://machinemail.dev/docs/concepts/inboxes): Organizations and pods, API keys, inboxes, threads and messages, drafts, domains, events and webhooks.
- [Guides](https://machinemail.dev/docs/guides/give-an-agent-an-inbox): Task-sized recipes: one inbox per agent, OTPs and signups, replying in thread, verifying webhooks, custom domains.
- [Trust layer](https://machinemail.dev/docs/trust): What the trust report checks, what each field means, and how to gate an agent's actions on it.
- [Agents](https://machinemail.dev/docs/agents): The hosted MCP server, client setup, and auth.md self-registration with human claiming.
- [CLI](https://machinemail.dev/docs/cli): The `machinemail` command line tool: sign in, create inboxes, send, wait for verification codes and script the API from a terminal.
- [API reference](https://machinemail.dev/docs/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](https://machinemail.dev/docs/llms.txt) indexes every page, [/docs/llms-full.txt](https://machinemail.dev/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.