# Mailpipe

Mailpipe is email infrastructure for developers and AI agents: receive-only and full send/receive inboxes, an HTTP API, an SDK, and an MCP server. AI agents can claim their own free email identity in one unauthenticated call.

## Agents

AI agents that need an email address (to sign up for a service, receive a verification link, or get notified) can claim a free, RECEIVE-ONLY identity at `<handle>@agents.mailpipe.dev`. Free Agent IDs are read-only by capability — the inbox has no outbound. Paying $14/mo SEND-ENABLES that SAME address: send to anyone, instantly, no DNS (agents.mailpipe.dev is already a verified sending domain). The human operator gets a receipt and a dashboard login to audit what the agent sends.

- Free Agent ID (anonymous, two-step): `POST https://www.mailpipe.dev/api/v1/agents/signup`
  - Body: `{ "handle": "scout-7", "operator_email": "human@example.com", "agent_name": "Scout" }` (`agent_name` optional)
  - Pre-auth — no credential needed. Returns `{ id, status, address, poll }`. Nothing is provisioned until the human operator clicks the email link (24h window).
  - Poll `GET https://www.mailpipe.dev/api/v1/agents/signup/{id}` until `status` is `active`. The FIRST poll after verification returns `api_key` exactly once (scopes `mail:read`, `mailbox:read`, pinned to the one mailbox). Store it.
- Free Agent ID (headless, authenticated, one call): `POST https://www.mailpipe.dev/api/v1/agents/provision`
  - Auth: an operator session cookie OR `Authorization: Bearer <jwt>` / API key. Returns the read-only `api_key` immediately — no email round-trip.
- Handle precheck (optional): `GET https://www.mailpipe.dev/api/v1/agents/handle-available?handle=scout-7` → whether the handle is free (and suggested alternatives if taken) before you commit to a signup.
- Key recovery (if an agent loses its API key): rotate with the current key via `POST https://www.mailpipe.dev/api/v1/agents/rotate-key` (mints a fresh read-only key pinned to the same mailbox, revokes the old one), or operator-initiated recovery via `POST https://www.mailpipe.dev/api/v1/agents/{id}/recover` (re-sends the operator approval link; then re-poll the signup URL for a new key).
- Paid send-enable ($14/mo — send to anyone from the SAME `<handle>@agents.mailpipe.dev`, instant, no DNS): `POST https://www.mailpipe.dev/api/v1/agents/upgrade`
  - Auth: the agent's own API key. Returns a Stripe `checkout_url` for the human operator (operators fund agents; an agent cannot pay for itself). On payment the operator gets a receipt + a login to audit sent mail. Poll `GET .../api/v1/agents/upgrade` (status: `pending_payment` -> `ready`) for the one-time full-send key plus `send_org_id` + `send_endpoint` (POST your sends there). A dedicated per-agent domain is a future premium.
- MCP server: `@mailpipe/mcp-server` (run with `npx @mailpipe/mcp-server`) exposes `mailpipe_agent_handle_available`, `mailpipe_agent_provision`, `mailpipe_agent_signup`, `mailpipe_agent_status`, `mailpipe_agent_rotate_key`, and `mailpipe_agent_upgrade` as tools.

## Docs

- Agents guide: https://www.mailpipe.dev/docs/agents
- Quick start: https://www.mailpipe.dev/docs/quick-start
- API reference: https://www.mailpipe.dev/docs/api
- MCP server: https://www.mailpipe.dev/docs/mcp