{"openapi":"3.0.0","info":{"version":"0.1.0","title":"AgenticEmail API","description":"AgenticEmail is API-first email infrastructure for AI agents: create real, addressable inboxes at runtime, send and receive mail over REST, and react to new messages the moment they arrive.\n\n## Authentication\n\nEvery request needs an API key, passed as a Bearer token:\n\n```\nAuthorization: Bearer am_...\n```\n\nCreate keys in the [dashboard](https://app.agenticemail.dev/keys). A key can be restricted to specific permissions (`message_read`, `message_send`, ...) and pinned to a single inbox, so each agent gets exactly the access it needs.\n\n## The 60-second tour\n\n1. `POST /v1/inboxes` — give your agent a real address. Omit `username` for a random one.\n2. `POST /v1/inboxes/{inbox_id}/messages/send` — send text or HTML mail with attachments.\n3. `GET /v1/inboxes/{inbox_id}/messages` — inbound replies arrive parsed and threaded, no MIME handling required.\n4. Register a webhook or open the WebSocket stream to react in real time instead of polling.\n\n## Conventions\n\n- **IDs** are prefixed by type: `msg_`, `thr_`, `drf_`, `dom_`, `wh_`, `key_`.\n- **Pagination** is cursor-based: pass `limit` (max 100) and the `page_token` returned as `next_page_token`. A `null` token means you have the last page.\n- **Errors** always have the shape `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }` with a matching HTTP status.\n- **Idempotency**: send and create endpoints accept a `client_id`; retries with the same value return the original resource instead of acting twice.\n- **Timestamps** are ISO 8601 UTC.\n\n## Real-time events\n\nEvent types: `message.received`, `message.sent`, `message.delivered`, `message.bounced`, `message.complained`, `message.opened`, `message.clicked`, `domain.verified`, `reply.suggested` (an AI-drafted reply, emitted only when the server has an OpenRouter API key configured).\n\n- **Webhooks** — register a URL and receive signed POSTs. Requests follow the [Standard Webhooks](https://www.standardwebhooks.com) spec: verify the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers with your webhook secret (`whsec_...`, shown once at creation).\n- **WebSocket** — connect to `wss://api.agenticemail.dev/v1/events?token=am_...` for the same events as a live stream. Optionally send `{ \"type\": \"subscribe\", \"inbox_ids\": [...], \"event_types\": [...] }` to narrow the stream.\n\n## MCP server\n\nModel-based agents can use email as a native tool via the hosted MCP server at `https://api.agenticemail.dev/mcp`, authenticated with the same Bearer API key."},"servers":[{"url":"https://api.agenticemail.dev","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Inboxes","description":"Real, addressable mailboxes your agents send from and receive to. Create one per agent, task, or customer — instantly, at runtime."},{"name":"Messages","description":"Send, read, search, label, reply, and forward. Inbound mail is parsed into clean JSON; the raw MIME and attachments stay available."},{"name":"Threads","description":"Messages grouped by conversation. The fastest way to hand an agent full conversational context."},{"name":"Drafts","description":"Compose now, send later. Set `send_at` to schedule delivery automatically."},{"name":"Webhooks","description":"Signed HTTP callbacks for message and domain events, with per-delivery logs and one-click redelivery."},{"name":"Domains","description":"Bring your own sending domain. AgenticEmail generates the SPF, DKIM, DMARC, and receiving records and verifies them for you."},{"name":"DNS","description":"Connect a DNS provider (Cloudflare OAuth or API token) so required records are created automatically instead of by hand."},{"name":"Lists","description":"Allow and block lists per organization or per inbox, applied when receiving, sending, and replying."},{"name":"API Keys","description":"Create and revoke keys. Scope a key to specific permissions or pin it to a single inbox."},{"name":"Stats","description":"Sending and receiving metrics for your organization."},{"name":"Account","description":"The organization behind the current API key."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from the [dashboard](https://app.agenticemail.dev/keys), e.g. `am_...`. Keys can be restricted to specific permissions and pinned to a single inbox."}},"schemas":{},"parameters":{}},"paths":{"/v1/inboxes":{"post":{"tags":["Inboxes"],"summary":"Create an inbox","description":"Provisions a real, addressable mailbox in one call. The new inbox can send and receive immediately.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"Local part of the address. Omitted: a random one is generated.","example":"support"},"domain":{"type":"string","description":"A verified domain you own. Omitted: your default (or only verified) domain is used.","example":"yourdomain.com"},"display_name":{"type":"string","description":"Friendly name shown in recipients' mail clients.","example":"Acme Support"},"client_id":{"type":"string","description":"Idempotency key. Retrying with the same value returns the existing inbox."}}}}}},"responses":{"201":{"description":"Inbox created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"username":{"type":"string"},"domain":{"type":"string"},"display_name":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","org_id","username","domain","display_name","system_prompt","created_at"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Inbox already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"get":{"tags":["Inboxes"],"summary":"List inboxes","parameters":[{"schema":{"type":"string","description":"Page size, 1-100. Defaults to 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the previous response's `next_page_token`. Omit for the first page."},"required":false,"name":"page_token","in":"query"}],"responses":{"200":{"description":"Inboxes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"username":{"type":"string"},"domain":{"type":"string"},"display_name":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","org_id","username","domain","display_name","system_prompt","created_at"]}},"next_page_token":{"type":"string","nullable":true}},"required":["data","next_page_token"]}}}}}}},"/v1/inboxes/{inbox_id}":{"get":{"tags":["Inboxes"],"summary":"Get an inbox","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"responses":{"200":{"description":"Inbox","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"username":{"type":"string"},"domain":{"type":"string"},"display_name":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","org_id","username","domain","display_name","system_prompt","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"tags":["Inboxes"],"summary":"Update an inbox","description":"Change the display name or the inbox's AI system prompt (used by the chat assistant; null/empty falls back to the built-in default).","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"username":{"type":"string"},"domain":{"type":"string"},"display_name":{"type":"string","nullable":true},"system_prompt":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","org_id","username","domain","display_name","system_prompt","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Inboxes"],"summary":"Delete an inbox","description":"The address stops accepting mail immediately. This cannot be undone.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/send":{"post":{"tags":["Messages"],"summary":"Send a message","description":"Sends an email from the inbox. Supports plain text, HTML, and base64 attachments. Pass `client_id` to make the call safely retryable.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Recipient addresses.","example":["customer@example.com"]},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"subject":{"type":"string","example":"Thanks for reaching out"},"text":{"type":"string","description":"Plain-text body. Provide `text`, `html`, or both.","example":"Hi there - an agent will follow up shortly."},"html":{"type":"string","description":"HTML body."},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","example":"report.pdf"},"content_type":{"type":"string","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded file content."}},"required":["filename","content"]}},"labels":{"type":"array","items":{"type":"string"},"description":"Labels to attach to the stored message."},"client_id":{"type":"string","description":"Idempotency key. Retrying with the same value returns the original message instead of sending twice."}},"required":["to","subject"]}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"Send failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/batch":{"post":{"tags":["Messages"],"summary":"Send a batch","description":"Sends up to 100 messages in one request. Each entry succeeds or fails independently; the response reports a per-index result, so one bad address never blocks the rest.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Recipient addresses.","example":["customer@example.com"]},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"subject":{"type":"string","example":"Thanks for reaching out"},"text":{"type":"string","description":"Plain-text body. Provide `text`, `html`, or both.","example":"Hi there - an agent will follow up shortly."},"html":{"type":"string","description":"HTML body."},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","example":"report.pdf"},"content_type":{"type":"string","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded file content."}},"required":["filename","content"]}},"labels":{"type":"array","items":{"type":"string"},"description":"Labels to attach to the stored message."},"client_id":{"type":"string","description":"Idempotency key. Retrying with the same value returns the original message instead of sending twice."}},"required":["to","subject"]},"minItems":1,"maxItems":100}},"required":["messages"]}}}},"responses":{"200":{"description":"Batch results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"ok":{"type":"boolean"},"message":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["index","ok","message","error"]}}},"required":["data"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages":{"get":{"tags":["Messages"],"summary":"List messages","description":"Returns inbound and outbound messages, newest first, parsed into JSON. All filter parameters combine with AND.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"Page size, 1-100. Defaults to 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the previous response's `next_page_token`. Omit for the first page."},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","description":"Free-text search across subject, sender address, and body."},"required":false,"name":"q","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items carrying this label. Repeat the parameter to match multiple values."},"required":false,"name":"labels","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items from this sender address. Repeat the parameter to match multiple values."},"required":false,"name":"senders","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items addressed to this recipient. Repeat the parameter to match multiple values."},"required":false,"name":"recipients","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items whose subject contains this text. Repeat the parameter to match multiple values."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Only items created before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","description":"Only items created after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Set to `true` for oldest first. Defaults to newest first."},"required":false,"name":"ascending","in":"query"},{"schema":{"type":"string","description":"Set to `true` to also return messages suppressed by a block list."},"required":false,"name":"include_blocked","in":"query"}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]}},"next_page_token":{"type":"string","nullable":true}},"required":["data","next_page_token"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/search":{"get":{"tags":["Messages"],"summary":"Search messages","description":"Free-text search with `q` across subject, sender, and body, plus the same filters as the list endpoint.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"Page size, 1-100. Defaults to 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the previous response's `next_page_token`. Omit for the first page."},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","description":"Free-text search across subject, sender address, and body."},"required":false,"name":"q","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items carrying this label. Repeat the parameter to match multiple values."},"required":false,"name":"labels","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items from this sender address. Repeat the parameter to match multiple values."},"required":false,"name":"senders","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items addressed to this recipient. Repeat the parameter to match multiple values."},"required":false,"name":"recipients","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items whose subject contains this text. Repeat the parameter to match multiple values."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Only items created before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","description":"Only items created after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Set to `true` for oldest first. Defaults to newest first."},"required":false,"name":"ascending","in":"query"},{"schema":{"type":"string","description":"Set to `true` to also return messages suppressed by a block list."},"required":false,"name":"include_blocked","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]}},"next_page_token":{"type":"string","nullable":true}},"required":["data","next_page_token"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}":{"get":{"tags":["Messages"],"summary":"Get a message","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"}],"responses":{"200":{"description":"Message","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"tags":["Messages"],"summary":"Add or remove labels","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"add_labels":{"type":"array","items":{"type":"string"}},"remove_labels":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}/reply":{"post":{"tags":["Messages"],"summary":"Reply to a message","description":"Sends a reply in the same thread with correct `In-Reply-To`/`References` headers. Recipients default to the original `Reply-To` (or sender); pass `to`/`cc`/`bcc` to override.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"text":{"type":"string"},"html":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","example":"report.pdf"},"content_type":{"type":"string","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded file content."}},"required":["filename","content"]}},"client_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Reply sent","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"Send failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}/forward":{"post":{"tags":["Messages"],"summary":"Forward a message","description":"Forwards the message, including its attachments, with an optional note in `text`.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"minItems":1},"text":{"type":"string"},"client_id":{"type":"string"}},"required":["to"]}}}},"responses":{"201":{"description":"Forwarded","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"message_id":{"type":"string"},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"blocked":{"type":"boolean"},"created_at":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"size_bytes":{"type":"number","nullable":true}},"required":["id","filename","content_type","size_bytes"]}}},"required":["id","inbox_id","thread_id","direction","status","message_id","subject","from","to","labels","blocked","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"Send failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}/raw":{"get":{"tags":["Messages"],"summary":"Download raw MIME","description":"Returns the original RFC 822 source, for when parsed JSON is not enough.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"}],"responses":{"200":{"description":"Raw MIME","content":{"message/rfc822":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/content":{"get":{"tags":["Messages"],"summary":"Read an attachment as structured content","description":"Extracts the attachment as structured text instead of raw bytes: PDFs are converted to markdown (with OCR-need flags for scanned pages), `text/*` parts are decoded as-is. Other content types return 415 - use the raw download endpoint for those.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"attachment_id","in":"path"}],"responses":{"200":{"description":"Structured content","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"content_type":{"type":"string"},"format":{"type":"string","enum":["markdown","text"]},"content":{"type":"string"},"pdf_type":{"type":"string"},"pages_needing_ocr":{"type":"array","items":{"type":"number"}},"title":{"type":"string","nullable":true}},"required":["filename","content_type","format","content"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"415":{"description":"Unsupported content type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}":{"get":{"tags":["Messages"],"summary":"Download an attachment","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"message_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"attachment_id","in":"path"}],"responses":{"200":{"description":"Attachment","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/drafts":{"post":{"tags":["Drafts"],"summary":"Create a draft","description":"Saves an unsent message. All fields are optional until you send it. Set `send_at` to schedule automatic delivery.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"content":{"type":"string"}},"required":["filename","content"]}},"send_at":{"type":"string","nullable":true,"format":"date-time","description":"ISO 8601 timestamp to schedule automatic sending. Set to null to cancel a schedule.","example":"2026-07-06T09:00:00Z"}}}}}},"responses":{"201":{"description":"Draft created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"payload":{"type":"object","additionalProperties":{"nullable":true}},"sent_message_id":{"type":"string","nullable":true},"send_at":{"type":"string","nullable":true},"send_status":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","inbox_id","payload","sent_message_id","send_at","send_status","created_at","updated_at"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"get":{"tags":["Drafts"],"summary":"List drafts","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"responses":{"200":{"description":"Drafts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"payload":{"type":"object","additionalProperties":{"nullable":true}},"sent_message_id":{"type":"string","nullable":true},"send_at":{"type":"string","nullable":true},"send_status":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","inbox_id","payload","sent_message_id","send_at","send_status","created_at","updated_at"]}}},"required":["data"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/drafts/{draft_id}":{"get":{"tags":["Drafts"],"summary":"Get a draft","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"draft_id","in":"path"}],"responses":{"200":{"description":"Draft","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"payload":{"type":"object","additionalProperties":{"nullable":true}},"sent_message_id":{"type":"string","nullable":true},"send_at":{"type":"string","nullable":true},"send_status":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","inbox_id","payload","sent_message_id","send_at","send_status","created_at","updated_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"tags":["Drafts"],"summary":"Update a draft","description":"Replaces the draft payload. Include `send_at` to (re)schedule, or set it to null to cancel a pending schedule.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"draft_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"content":{"type":"string"}},"required":["filename","content"]}},"send_at":{"type":"string","nullable":true,"format":"date-time","description":"ISO 8601 timestamp to schedule automatic sending. Set to null to cancel a schedule.","example":"2026-07-06T09:00:00Z"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"payload":{"type":"object","additionalProperties":{"nullable":true}},"sent_message_id":{"type":"string","nullable":true},"send_at":{"type":"string","nullable":true},"send_status":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","inbox_id","payload","sent_message_id","send_at","send_status","created_at","updated_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Drafts"],"summary":"Delete a draft","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"draft_id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/drafts/{draft_id}/send":{"post":{"tags":["Drafts"],"summary":"Send a draft now","description":"Sends immediately, regardless of any `send_at` schedule. Fails with 400 if the draft is missing recipients or a subject.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"draft_id","in":"path"}],"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"thread_id":{"type":"string"}},"required":["id","status","thread_id"]}}}},"400":{"description":"Draft incomplete","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"Send failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/chat":{"post":{"tags":["Chat"],"summary":"Chat with the inbox AI assistant","description":"Runs the AI assistant with tool access (read, draft, send, label) scoped to this inbox. Returns the assistant's reply, the tools it used, and any drafts prepared for the composer. Requires an OpenRouter API key on the server.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}},"required":["role","content"]}},"thread_id":{"type":"string"}},"required":["messages"]}}}},"responses":{"200":{"description":"Assistant reply","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string"}},"required":["tool"]}},"actions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["message","steps","actions"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"501":{"description":"AI is not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/threads":{"get":{"tags":["Threads"],"summary":"List threads in an inbox","description":"Conversations for one inbox, most recently active first. Fetch a single thread to get its full message history.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"Page size, 1-100. Defaults to 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the previous response's `next_page_token`. Omit for the first page."},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","description":"Free-text search across subject, sender address, and body."},"required":false,"name":"q","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items carrying this label. Repeat the parameter to match multiple values."},"required":false,"name":"labels","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items from this sender address. Repeat the parameter to match multiple values."},"required":false,"name":"senders","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items addressed to this recipient. Repeat the parameter to match multiple values."},"required":false,"name":"recipients","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items whose subject contains this text. Repeat the parameter to match multiple values."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Only items created before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","description":"Only items created after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Set to `true` for oldest first. Defaults to newest first."},"required":false,"name":"ascending","in":"query"}],"responses":{"200":{"description":"Threads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread"]}},"next_page_token":{"type":"string","nullable":true}},"required":["data","next_page_token"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/threads/search":{"get":{"tags":["Threads"],"summary":"Search threads in an inbox","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"Page size, 1-100. Defaults to 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the previous response's `next_page_token`. Omit for the first page."},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","description":"Free-text search across subject, sender address, and body."},"required":false,"name":"q","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items carrying this label. Repeat the parameter to match multiple values."},"required":false,"name":"labels","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items from this sender address. Repeat the parameter to match multiple values."},"required":false,"name":"senders","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items addressed to this recipient. Repeat the parameter to match multiple values."},"required":false,"name":"recipients","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items whose subject contains this text. Repeat the parameter to match multiple values."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Only items created before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","description":"Only items created after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Set to `true` for oldest first. Defaults to newest first."},"required":false,"name":"ascending","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread"]}},"next_page_token":{"type":"string","nullable":true}},"required":["data","next_page_token"]}}}},"404":{"description":"Inbox not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/threads/{thread_id}/suggest-reply":{"post":{"tags":["Threads"],"summary":"Draft an AI-suggested reply for a thread","description":"Uses the thread's full context to draft a plain-text reply. The suggestion is for review — it is not sent. Requires the server to have an OpenRouter API key configured.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"}],"responses":{"200":{"description":"Suggested reply","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"501":{"description":"AI replies are not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/threads/{thread_id}":{"get":{"tags":["Threads"],"summary":"Get a thread with its messages","description":"The thread plus every message in it, oldest first — ready to drop into an agent's context.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"}],"responses":{"200":{"description":"Thread","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"},"messages":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread","messages"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"tags":["Threads"],"summary":"Add or remove thread labels (inbox-scoped)","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"add_labels":{"type":"array","items":{"type":"string"}},"remove_labels":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/threads":{"get":{"tags":["Threads"],"summary":"List threads across all inboxes","parameters":[{"schema":{"type":"string","description":"Page size, 1-100. Defaults to 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the previous response's `next_page_token`. Omit for the first page."},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","description":"Free-text search across subject, sender address, and body."},"required":false,"name":"q","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items carrying this label. Repeat the parameter to match multiple values."},"required":false,"name":"labels","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items from this sender address. Repeat the parameter to match multiple values."},"required":false,"name":"senders","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items addressed to this recipient. Repeat the parameter to match multiple values."},"required":false,"name":"recipients","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items whose subject contains this text. Repeat the parameter to match multiple values."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Only items created before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","description":"Only items created after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Set to `true` for oldest first. Defaults to newest first."},"required":false,"name":"ascending","in":"query"}],"responses":{"200":{"description":"Threads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread"]}},"next_page_token":{"type":"string","nullable":true}},"required":["data","next_page_token"]}}}}}}},"/v1/threads/search":{"get":{"tags":["Threads"],"summary":"Search threads across all inboxes","parameters":[{"schema":{"type":"string","description":"Page size, 1-100. Defaults to 20."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the previous response's `next_page_token`. Omit for the first page."},"required":false,"name":"page_token","in":"query"},{"schema":{"type":"string","description":"Free-text search across subject, sender address, and body."},"required":false,"name":"q","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items carrying this label. Repeat the parameter to match multiple values."},"required":false,"name":"labels","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items from this sender address. Repeat the parameter to match multiple values."},"required":false,"name":"senders","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items addressed to this recipient. Repeat the parameter to match multiple values."},"required":false,"name":"recipients","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only items whose subject contains this text. Repeat the parameter to match multiple values."},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","description":"Only items created before this ISO 8601 timestamp."},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","description":"Only items created after this ISO 8601 timestamp."},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Set to `true` for oldest first. Defaults to newest first."},"required":false,"name":"ascending","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread"]}},"next_page_token":{"type":"string","nullable":true}},"required":["data","next_page_token"]}}}}}}},"/v1/threads/{thread_id}":{"get":{"tags":["Threads"],"summary":"Get a thread by ID","parameters":[{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"}],"responses":{"200":{"description":"Thread","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"},"messages":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread","messages"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"tags":["Threads"],"summary":"Add or remove thread labels","parameters":[{"schema":{"type":"string"},"required":true,"name":"thread_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"add_labels":{"type":"array","items":{"type":"string"}},"remove_labels":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"labels":{"type":"array","items":{"type":"string"}},"message_count":{"type":"number"},"last_message_at":{"type":"string"},"created_at":{"type":"string"},"suggested_reply":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"unread":{"type":"boolean"}},"required":["id","inbox_id","subject","snippet","labels","message_count","last_message_at","created_at","suggested_reply","from","unread"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/lists/{direction}/{type}":{"get":{"tags":["Lists"],"summary":"List entries (one inbox)","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"}],"responses":{"200":{"description":"Entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string","nullable":true},"direction":{"type":"string"},"type":{"type":"string"},"entry":{"type":"string"},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","inbox_id","direction","type","entry","reason","created_at"]}}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Lists"],"summary":"Add an entry (one inbox)","description":"Adds an address or domain to the allow/block list identified by the path.","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"type":"string","description":"An email address or domain to match.","example":"spammer@example.com"},"reason":{"type":"string","description":"Why this entry exists. Only stored for block entries."}},"required":["entry"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string","nullable":true},"direction":{"type":"string"},"type":{"type":"string"},"entry":{"type":"string"},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","inbox_id","direction","type","entry","reason","created_at"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}":{"get":{"tags":["Lists"],"summary":"Get an entry (one inbox)","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"},{"schema":{"type":"string"},"required":true,"name":"entry","in":"path"}],"responses":{"200":{"description":"Entry","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string","nullable":true},"direction":{"type":"string"},"type":{"type":"string"},"entry":{"type":"string"},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","inbox_id","direction","type","entry","reason","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Lists"],"summary":"Remove an entry (one inbox)","parameters":[{"schema":{"type":"string"},"required":true,"name":"inbox_id","in":"path"},{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"},{"schema":{"type":"string"},"required":true,"name":"entry","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/lists/{direction}/{type}":{"get":{"tags":["Lists"],"summary":"List entries (org-wide)","parameters":[{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"}],"responses":{"200":{"description":"Entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string","nullable":true},"direction":{"type":"string"},"type":{"type":"string"},"entry":{"type":"string"},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","inbox_id","direction","type","entry","reason","created_at"]}}},"required":["data"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Lists"],"summary":"Add an entry (org-wide)","description":"Adds an address or domain to the allow/block list identified by the path.","parameters":[{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"type":"string","description":"An email address or domain to match.","example":"spammer@example.com"},"reason":{"type":"string","description":"Why this entry exists. Only stored for block entries."}},"required":["entry"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string","nullable":true},"direction":{"type":"string"},"type":{"type":"string"},"entry":{"type":"string"},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","inbox_id","direction","type","entry","reason","created_at"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/lists/{direction}/{type}/{entry}":{"get":{"tags":["Lists"],"summary":"Get an entry (org-wide)","parameters":[{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"},{"schema":{"type":"string"},"required":true,"name":"entry","in":"path"}],"responses":{"200":{"description":"Entry","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string","nullable":true},"direction":{"type":"string"},"type":{"type":"string"},"entry":{"type":"string"},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","inbox_id","direction","type","entry","reason","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Lists"],"summary":"Remove an entry (org-wide)","parameters":[{"schema":{"type":"string","description":"When the rule applies: `receive` (inbound mail), `send`, or `reply`.","example":"receive"},"required":true,"name":"direction","in":"path"},{"schema":{"type":"string","description":"`allow` or `block`.","example":"block"},"required":true,"name":"type","in":"path"},{"schema":{"type":"string"},"required":true,"name":"entry","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create a webhook","description":"Registers an HTTPS endpoint for the chosen event types. The response includes the signing `secret` (`whsec_...`) exactly once — store it to verify the `webhook-signature` header on deliveries.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://your-app.com/api/agenticemail"},"event_types":{"type":"array","items":{"type":"string"},"description":"Which events to deliver, e.g. `message.received`, `message.delivered`, `message.bounced`.","example":["message.received"]},"inbox_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Limit deliveries to these inboxes. Omit or null for all inboxes."},"provider":{"type":"string","enum":["generic","discord","slack"],"description":"Delivery format. `discord`/`slack` post a human-readable message to an incoming-webhook URL; `generic` (default) sends the signed JSON envelope.","example":"discord"}},"required":["url","event_types"]}}}},"responses":{"201":{"description":"Webhook created; secret shown once","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"provider":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"inbox_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string"},"secret":{"type":"string"}},"required":["id","url","provider","event_types","inbox_ids","enabled","created_at","secret"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"get":{"tags":["Webhooks"],"summary":"List webhooks","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"provider":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"inbox_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","url","provider","event_types","inbox_ids","enabled","created_at"]}}},"required":["data"]}}}}}}},"/v1/webhooks/{webhook_id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a test event","description":"Queues a synthetic event delivery to verify the endpoint. Shows up in the delivery log within a couple of seconds.","parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook_id","in":"path"}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"delivery_id":{"type":"string"}},"required":["delivery_id"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/webhooks/{webhook_id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook","parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook_id","in":"path"}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"provider":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"inbox_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","url","provider","event_types","inbox_ids","enabled","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook","description":"Change the URL, event types, inbox filter, or pause deliveries with `enabled: false`.","parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"inbox_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"provider":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"inbox_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","url","provider","event_types","inbox_ids","enabled","created_at"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook_id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/webhooks/{webhook_id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List delivery attempts","description":"Delivery log for debugging: status, attempt count, last HTTP status, and last error per event. Failed deliveries retry automatically with backoff.","parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook_id","in":"path"}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_type":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"number"},"last_status_code":{"type":"number","nullable":true},"last_error":{"type":"string","nullable":true},"created_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true}},"required":["id","event_type","status","attempts","last_status_code","last_error","created_at","delivered_at"]}}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver":{"post":{"tags":["Webhooks"],"summary":"Redeliver an event","description":"Queues the delivery to be sent again immediately.","parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook_id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"delivery_id","in":"path"}],"responses":{"202":{"description":"Requeued"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/domains":{"post":{"tags":["Domains"],"summary":"Add a domain","description":"Registers a sending domain and returns the DNS `records` (SPF, DKIM, DMARC, receiving) to publish. Pass `dns_connection_id` to have them created in your DNS provider automatically, or fetch the zone file and add them by hand, then call verify.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"dns_connection_id":{"type":"string"},"return_path":{"type":"string"},"tracking_subdomain":{"type":"string"},"open_tracking":{"type":"boolean"},"click_tracking":{"type":"boolean"}},"required":["domain"]}}}},"responses":{"201":{"description":"Domain created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string"},"return_path":{"type":"string","nullable":true},"tracking_subdomain":{"type":"string","nullable":true},"open_tracking":{"type":"boolean"},"click_tracking":{"type":"boolean"},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"verified_at":{"type":"string","nullable":true},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"priority":{"type":"number","nullable":true},"purpose":{"type":"string","enum":["dkim","spf","dmarc","receiving","tracking"]}},"required":["type","name","content","priority","purpose"]}}},"required":["id","name","status","region","return_path","tracking_subdomain","open_tracking","click_tracking","is_default","created_at","verified_at","records"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Domain taken","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"get":{"tags":["Domains"],"summary":"List domains","responses":{"200":{"description":"Domains","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string"},"return_path":{"type":"string","nullable":true},"tracking_subdomain":{"type":"string","nullable":true},"open_tracking":{"type":"boolean"},"click_tracking":{"type":"boolean"},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"verified_at":{"type":"string","nullable":true},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"priority":{"type":"number","nullable":true},"purpose":{"type":"string","enum":["dkim","spf","dmarc","receiving","tracking"]}},"required":["type","name","content","priority","purpose"]}}},"required":["id","name","status","region","return_path","tracking_subdomain","open_tracking","click_tracking","is_default","created_at","verified_at","records"]}}},"required":["data"]}}}}}}},"/v1/domains/{domain_id}/sync-dns":{"post":{"tags":["Domains"],"summary":"Push DNS records via a connection","description":"Creates or updates the required records in your connected DNS provider (e.g. Cloudflare), so no manual DNS editing is needed.","parameters":[{"schema":{"type":"string"},"required":true,"name":"domain_id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dns_connection_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Synced","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string"},"return_path":{"type":"string","nullable":true},"tracking_subdomain":{"type":"string","nullable":true},"open_tracking":{"type":"boolean"},"click_tracking":{"type":"boolean"},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"verified_at":{"type":"string","nullable":true},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"priority":{"type":"number","nullable":true},"purpose":{"type":"string","enum":["dkim","spf","dmarc","receiving","tracking"]}},"required":["type","name","content","priority","purpose"]}}},"required":["id","name","status","region","return_path","tracking_subdomain","open_tracking","click_tracking","is_default","created_at","verified_at","records"]}}}},"400":{"description":"No DNS connection","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/domains/{domain_id}":{"get":{"tags":["Domains"],"summary":"Get a domain","description":"Includes verification status and the exact DNS records to publish.","parameters":[{"schema":{"type":"string"},"required":true,"name":"domain_id","in":"path"}],"responses":{"200":{"description":"Domain","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string"},"return_path":{"type":"string","nullable":true},"tracking_subdomain":{"type":"string","nullable":true},"open_tracking":{"type":"boolean"},"click_tracking":{"type":"boolean"},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"verified_at":{"type":"string","nullable":true},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"priority":{"type":"number","nullable":true},"purpose":{"type":"string","enum":["dkim","spf","dmarc","receiving","tracking"]}},"required":["type","name","content","priority","purpose"]}}},"required":["id","name","status","region","return_path","tracking_subdomain","open_tracking","click_tracking","is_default","created_at","verified_at","records"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"tags":["Domains"],"summary":"Delete a domain","parameters":[{"schema":{"type":"string"},"required":true,"name":"domain_id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Cannot delete","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/domains/{domain_id}/verify":{"post":{"tags":["Domains"],"summary":"Check verification","description":"Re-checks DKIM and MX records now. Pending domains are also re-checked automatically in the background.","parameters":[{"schema":{"type":"string"},"required":true,"name":"domain_id","in":"path"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"dkim_status":{"type":"string"},"mx_ok":{"type":"boolean"}},"required":["status","dkim_status","mx_ok"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/domains/{domain_id}/zone-file":{"get":{"tags":["Domains"],"summary":"Download a BIND zone file","description":"All required records in standard zone-file format, ready to import into any DNS provider.","parameters":[{"schema":{"type":"string"},"required":true,"name":"domain_id","in":"path"}],"responses":{"200":{"description":"Zone file","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/dns/detect":{"get":{"tags":["DNS"],"summary":"Detect a domain's DNS host","description":"Looks up the domain's nameservers to identify its DNS provider, and reports whether one-click Cloudflare OAuth is available.","parameters":[{"schema":{"type":"string"},"required":true,"name":"domain","in":"query"}],"responses":{"200":{"description":"Detected DNS host","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"nameservers":{"type":"array","items":{"type":"string"}},"cloudflare_oauth":{"type":"boolean"}},"required":["provider","nameservers","cloudflare_oauth"]}}}}}}},"/v1/dns/cloudflare/connect":{"get":{"tags":["DNS"],"summary":"Start Cloudflare OAuth","description":"Returns an authorize URL. Send the user there to grant DNS access; the connection is created on callback. Pass `domain_id` to auto-configure that domain's DNS once connected.","parameters":[{"schema":{"type":"string"},"required":false,"name":"domain_id","in":"query"}],"responses":{"200":{"description":"Authorize URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"400":{"description":"Cloudflare not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/dns/cloudflare/token":{"post":{"tags":["DNS"],"summary":"Connect Cloudflare with an API token","description":"Alternative to OAuth: provide a Cloudflare API token with DNS edit permission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}}}},"responses":{"201":{"description":"Connection created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"}},"required":["id","provider","scopes","created_at"]}}}},"400":{"description":"Invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/dns/connections":{"get":{"tags":["DNS"],"summary":"List DNS connections","responses":{"200":{"description":"Connections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"}},"required":["id","provider","scopes","created_at"]}}},"required":["data"]}}}}}}},"/v1/dns/connections/{connection_id}":{"delete":{"tags":["DNS"],"summary":"Remove a DNS connection","parameters":[{"schema":{"type":"string"},"required":true,"name":"connection_id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/stats":{"get":{"tags":["Stats"],"summary":"Get overview stats","description":"Inbox and domain counts, plus 24-hour send/receive/delivery totals with hourly activity buckets.","responses":{"200":{"description":"Overview stats","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}}}}},"/v1/me":{"get":{"tags":["Account"],"summary":"Get the current organization","description":"Identifies the organization behind the API key. Useful as a smoke test for authentication.","responses":{"200":{"description":"Current account","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ai_enabled":{"type":"boolean"},"plan":{"type":"string"},"is_admin":{"type":"boolean"}},"required":["org","ai_enabled","plan","is_admin"]}}}}}},"patch":{"tags":["Account"],"summary":"Rename the current organization","description":"Update the organization's display name (workspace name).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120}},"required":["name"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ai_enabled":{"type":"boolean"},"plan":{"type":"string"},"is_admin":{"type":"boolean"}},"required":["org","ai_enabled","plan","is_admin"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/api-keys":{"post":{"tags":["API Keys"],"summary":"Create an API key","description":"Returns the full `token` (`am_...`) exactly once — store it securely. A key can never grant more than the key that created it.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"support-agent"},"scopes":{"type":"array","nullable":true,"items":{"type":"string","enum":["message_read","message_send","message_update","inbox_read","inbox_create","inbox_delete","thread_read","thread_update","draft_read","draft_write","list_read","list_write","webhook_read","webhook_write","domain_read","domain_write","apikey_read","apikey_create","apikey_delete"]},"description":"Permissions granted to the key. Omit or null for full access (within the creating key's own scope)."},"scope_inbox_id":{"type":"string","nullable":true,"description":"Pin the key to a single inbox so it can see nothing else."}},"required":["name"]}}}},"responses":{"201":{"description":"Key created; token is shown once","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"token_prefix":{"type":"string"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"}},"scope_inbox_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true},"token":{"type":"string"}},"required":["id","name","token_prefix","scopes","scope_inbox_id","created_at","last_used_at","token"]}}}}}},"get":{"tags":["API Keys"],"summary":"List API keys","description":"Tokens are never returned again; only the prefix is shown.","responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"token_prefix":{"type":"string"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"}},"scope_inbox_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"last_used_at":{"type":"string","nullable":true}},"required":["id","name","token_prefix","scopes","scope_inbox_id","created_at","last_used_at"]}}},"required":["data"]}}}}}}},"/v1/api-keys/{api_key_id}":{"delete":{"tags":["API Keys"],"summary":"Revoke an API key","description":"Takes effect immediately; in-flight requests fail with 401.","parameters":[{"schema":{"type":"string"},"required":true,"name":"api_key_id","in":"path"}],"responses":{"204":{"description":"Revoked"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/billing/summary":{"get":{"tags":["Billing"],"summary":"Current plan, limits, and usage","description":"The organization's plan, subscription status, plan limits (null = unlimited), and current usage (inboxes, emails sent this month).","responses":{"200":{"description":"Billing summary","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"plan":{"type":"string"},"status":{"type":"string","nullable":true},"limits":{"type":"object","properties":{"inboxes":{"type":"number","nullable":true},"emails_per_month":{"type":"number","nullable":true}},"required":["inboxes","emails_per_month"]},"usage":{"type":"object","properties":{"inboxes":{"type":"number"},"emails_this_month":{"type":"number"}},"required":["inboxes","emails_this_month"]}},"required":["enabled","plan","status","limits","usage"]}}}}}}},"/v1/admin/users":{"get":{"tags":["Admin"],"summary":"List all users","description":"Platform administration: every user with their organization and resolved plan. Requires an @agenticemail.dev dashboard session.","responses":{"200":{"description":"Users","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"org":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"plan_override":{"type":"string","nullable":true},"is_admin_org":{"type":"boolean"}},"required":["id","name","plan","plan_override","is_admin_org"]}},"required":["id","name","email","created_at","org"]}}},"required":["data"]}}}},"403":{"description":"Admin only","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/admin/orgs/{org_id}":{"patch":{"tags":["Admin"],"summary":"Override an organization's plan","description":"Pin an organization to a plan regardless of its subscription, or pass null to clear the override.","parameters":[{"schema":{"type":"string"},"required":true,"name":"org_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","nullable":true,"enum":["free","pro","enterprise"]}},"required":["plan"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"plan_override":{"type":"string","nullable":true},"is_admin_org":{"type":"boolean"}},"required":["id","name","plan","plan_override","is_admin_org"]}}}},"403":{"description":"Admin only","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}}}}