# AgentPost

> Email for AI agents — with inbound injection safety. AgentPost gives every AI
> agent its own real email inbox, provisioned in one API call, with every inbound
> message scored 0–100 for prompt-injection risk (with explainable flags) before
> the agent reads it.

AgentPost is an API-first email service built for AI agents rather than humans:

- **Instant inboxes** — `POST /v0/inboxes` returns a working `<name>@maildesk.email`
  address in under a second.
- **Inbound injection safety** — every inbound message carries `injection_score`
  (0–100), `injection_level` (low/medium/high), and explainable `injection_flags`,
  so agents can gate tool use on untrusted mail.
- **OTP extraction** — verification codes are auto-extracted;
  `GET /v0/inboxes/:id/otp` (or the `wait_for_otp` MCP tool) returns the latest code.
- **Native MCP server** — point any MCP client at `POST /mcp` with a bearer key;
  tools: create_inbox, list_inboxes, list_messages, get_message, send_message,
  delete_message, wait_for_otp, list_domains.
- **Full MIME parsing** — multipart bodies, charset decoding, attachments stored
  and downloadable via the API. Threads, HMAC-signed webhooks, scoped API keys.

## Docs

- [API reference (rendered)](https://maildesk.email/docs): every REST endpoint,
  params, schemas, and recipes
- [OpenAPI 3.1 spec](https://maildesk.email/v0/openapi.json): machine-readable,
  no API key required
- [Landing page](https://maildesk.email/): overview and quickstart
- [FAQ](https://maildesk.email/#faq): what AgentPost is, MCP setup, injection
  scoring, OTP extraction, pricing
- [Pricing (machine-readable)](https://maildesk.email/pricing.md): tiers,
  limits, and included features in plain markdown
- [API health](https://maildesk.email/v0/health): service status

## REST API reference

Base URL `https://maildesk.email`. Auth: `Authorization: Bearer <api key>` on
everything except health, signup, waitlist, and the OpenAPI spec. Keys carry
scopes (read/write/admin); `GET /v0/me` shows yours. `:inbox` accepts the inbox
id or the full address, interchangeably. All timestamps are epoch milliseconds.
Errors are `{"error": "<message>", "docs": "..."}`; unknown paths return
404 `no such route` even without a key.

- `GET /v0/health` — public health check.
- `POST /v0/signup {email}` → emails a 6-digit code; then
  `POST /v0/signup/verify {email, code}` → `{key: "ap_...", ...}` (key shown
  once; re-verifying rotates it). Public, no key needed.
- `POST /v0/inboxes {username?, name?, domain?}` → 201 Inbox
  `{id, address, name, created_at}`. [write]
- `GET /v0/inboxes` · `GET /v0/inboxes/:inbox` · `DELETE /v0/inboxes/:inbox`
- `GET /v0/inboxes/:inbox/messages?since=<epoch-ms>&direction=inbound|outbound&limit=1..200`
  → Message[] newest first. **`since` is the poll cursor**: returns only
  messages with `created_at` strictly greater than it, so pass the largest
  `created_at` you've seen and you never re-read a message. [read]
- `POST /v0/inboxes/:inbox/messages {to, subject?, text?, html?}` → 201
  `{message, delivery}` — sends real email from the inbox address. [write]
- `GET /v0/messages/:id` → full Message incl. `attachments`. [read]
- `DELETE /v0/messages/:id` → the "I've handled this" primitive for polling
  consumers; removes the message + attachments. [write]
- `GET /v0/messages/:id/attachments` (metadata) and
  `GET /v0/messages/:id/attachments/:attachment_id` (raw bytes). [read]
- `GET /v0/inboxes/:inbox/otp?since=<epoch-ms>` →
  `{code|null, message_id, from, received_at}` — latest auto-extracted
  verification code. [read]
- `POST /v0/inbound {from, to, subject?, text?, html?, attachments?}` —
  simulate an inbound email through the real pipeline (scoring, OTP,
  webhooks); for testing. [write]
- `GET|POST /v0/webhooks`, `DELETE /v0/webhooks/:id` — events
  `message.received` / `message.sent` / `*`; deliveries HMAC-SHA256-signed in
  `x-agentpost-signature`. [admin]
- `GET|POST /v0/keys`, `DELETE /v0/keys/:id` — scoped key management. [admin]
- `GET /v0/domains` [read]; domain writes are [admin].

Message fields: `id, inbox_id, thread_id, direction (inbound|outbound),
from_addr, to_addr, subject, text, html, preview, injection_score (0–100),
injection_level (low|medium|high), injection_flags [{code, weight, detail}],
otp_code, labels, created_at`.

## Access

Free beta, self-serve: sign up on the landing page (or `POST /v0/signup`) with
your email, verify the 6-digit code, and get a read/write API key instantly. No
credit card, no waitlist. The MCP endpoint and REST API (`/v0/*`) require a
bearer API key. Beta caps per self-serve key: 10 new inboxes/day, 50 sends/day
per inbox.