# AgenticEmail for agents

AgenticEmail is API-first email infrastructure for AI agents: real, addressable inboxes created at runtime, sending and receiving over REST, and events pushed the moment mail arrives.

## When to use AgenticEmail

Use it when:

- Your agent needs its **own email address** - one per agent, task, or customer - provisioned in a single API call.
- Your agent must **receive** email and act on it: inbound mail arrives parsed as structured JSON (no MIME handling), threaded, and pushed by signed webhook or WebSocket in real time.
- Your agent holds **email conversations**: reply and forward endpoints set recipients, subjects, and threading automatically.
- Your agent **sends** transactional or conversational mail, optionally from your own domain with automated SPF, DKIM, and DMARC.
- Your agent runtime speaks **MCP** and you want email as a native tool.

Do not use it for bulk marketing or newsletter blasts.

## How to call it

Authenticate every request with a Bearer API key (see https://agenticemail.dev/auth.md):

```
Authorization: Bearer am_your_key_here
```

The 60-second REST tour (base URL https://api.agenticemail.dev):

1. `POST /v1/inboxes` - give your agent a real address. Omit `username` for a random one.
2. `POST /v1/inboxes/{inbox_id}/messages/send` - send text or HTML mail with attachments.
3. `GET /v1/inboxes/{inbox_id}/messages` - inbound replies arrive parsed and threaded.
4. Register a webhook (`POST /v1/webhooks`) or connect to `wss://api.agenticemail.dev/v1/events?token=am_...` to react in real time instead of polling.

Full API surface: OpenAPI 3.0 spec at https://agenticemail.dev/openapi.json.

## MCP server

Hosted MCP server (Streamable HTTP): `https://api.agenticemail.dev/mcp`, authenticated with the same Bearer API key. Tools:

- `create_inbox` - Create a new inbox. Omit username for a random one; omit domain to use the default (or only verified) domain.
- `list_inboxes` - List all inboxes in the account.
- `list_threads` - List conversation threads, optionally scoped to an inbox.
- `get_thread` - Get a thread with all its messages.
- `list_messages` - List recent messages in an inbox.
- `get_message` - Get a single message by id.
- `send_message` - Send a new email from an inbox.
- `reply_to_message` - Reply to a message; recipients, subject and threading are set automatically.

Server card: https://agenticemail.dev/.well-known/mcp/server-card.json

## Conventions

- IDs are prefixed by type: `msg_`, `thr_`, `drf_`, `dom_`, `wh_`, `key_`.
- Pagination is cursor-based (`limit` + `page_token`).
- Errors are always JSON: `{ "error": { "code": "...", "message": "..." } }`.
- Send/create endpoints accept a `client_id` for idempotent retries.
- Webhooks are signed; verify the signature against your `whsec_...` secret before trusting a payload (see https://agenticemail.dev/docs/receiving).

## More

- Docs: https://agenticemail.dev/docs (markdown twins: append .md, e.g. https://agenticemail.dev/docs/quickstart.md)
- llms.txt: https://agenticemail.dev/llms.txt · llms-full.txt: https://agenticemail.dev/llms-full.txt
- Machine-readable summary: https://agenticemail.dev/agent
- GitHub: https://github.com/AgenticEmail