{ "openapi": "3.1.0", "info": { "title": "AgentPost API", "version": "0.2.0", "description": "Email for AI agents — instant inboxes, real send/receive, OTP extraction,\nand a prompt-injection risk score on every inbound message.\n\n**Base URL:** `https://maildesk.email`\n\n**Auth:** every `/v0/*` endpoint except `health`, `signup`, `signup/verify`,\n`waitlist`, and `openapi.json` requires `Authorization: Bearer `.\nGet a key by self-serve signup (`POST /v0/signup` → emailed code →\n`POST /v0/signup/verify`) or on the landing page.\n\n**Polling for new mail:** pass `?since=` to the message list —\nit returns only messages with `created_at` strictly greater than `since`.\nUse the largest `created_at` you've seen as the next cursor; you'll never\nre-read a message. Delete processed messages with `DELETE /v0/messages/:id`\nif you prefer an empty-inbox workflow.\n\n**MCP:** the same operations are exposed as native MCP tools at\n`POST https://maildesk.email/mcp` (JSON-RPC 2.0, same bearer key)." }, "servers": [ { "url": "https://maildesk.email" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "meta", "description": "Health, identity, and this spec" }, { "name": "signup", "description": "Self-serve API-key signup (no auth required)" }, { "name": "inboxes", "description": "Provision and manage agent inboxes" }, { "name": "messages", "description": "Send, list, read, and delete mail" }, { "name": "otp", "description": "Auto-extracted verification codes" }, { "name": "webhooks", "description": "HMAC-signed event delivery (admin scope)" }, { "name": "keys", "description": "Scoped API keys (admin scope)" }, { "name": "domains", "description": "Sending/receiving domains" }, { "name": "testing", "description": "Simulated inbound for local testing and demos" } ], "paths": { "/v0/health": { "get": { "tags": [ "meta" ], "security": [], "summary": "Service health", "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" } } } } } } } } }, "/v0/openapi.json": { "get": { "tags": [ "meta" ], "security": [], "summary": "This document", "responses": { "200": { "description": "OpenAPI 3.1 spec" } } } }, "/v0/me": { "get": { "tags": [ "meta" ], "summary": "Identify the calling key", "responses": { "200": { "description": "Caller identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "admin" ] } }, "master": { "type": "boolean" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/signup": { "post": { "tags": [ "signup" ], "security": [], "summary": "Start self-serve signup (emails a 6-digit code)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "source": { "type": "string", "description": "Optional attribution tag" } } } } } }, "responses": { "201": { "description": "Code sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (per-address hourly or global daily cap)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/signup/verify": { "post": { "tags": [ "signup" ], "security": [], "summary": "Trade the emailed code for an API key", "description": "One live self-serve key per email; re-verifying rotates the old key out (doubles as lost-key recovery). The raw key is returned exactly once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string" } } } } } }, "responses": { "201": { "description": "Key created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "key": { "type": "string", "description": "The raw API key — shown only here" }, "rotated": { "type": "boolean" } } } ] } } } }, "400": { "description": "Invalid or expired code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/inboxes": { "get": { "tags": [ "inboxes" ], "summary": "List inboxes", "responses": { "200": { "description": "All inboxes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "inboxes" ], "summary": "Create an inbox", "description": "Returns a working address in one call. `username` is lowercased and stripped to `a-z0-9._-`; random if omitted. Requires `write` scope.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": "string", "description": "Optional human label" }, "domain": { "type": "string", "description": "Domain to create the address on; defaults to the default domain" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "400": { "description": "Unknown domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Address already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily inbox-creation cap reached for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/inboxes/{inbox}": { "parameters": [ { "name": "inbox", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox id or full address" } ], "get": { "tags": [ "inboxes" ], "summary": "Get one inbox", "responses": { "200": { "description": "The inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "inboxes" ], "summary": "Delete an inbox and all its messages", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/inboxes/{inbox}/messages": { "parameters": [ { "name": "inbox", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox id or full address" } ], "get": { "tags": [ "messages" ], "summary": "List messages (newest first)", "description": "**This is the polling endpoint.** Pass `since=` (strictly greater-than) to fetch only messages you haven't seen; use the max `created_at` from each batch as the next cursor.", "parameters": [ { "name": "since", "in": "query", "schema": { "type": "integer" }, "description": "Only messages with created_at > this epoch-ms timestamp" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Messages, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "messages" ], "summary": "Send an email from this inbox", "description": "Requires `write` scope. Outbound sends are capped per inbox per day.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" } } } } } }, "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" }, "delivery": { "type": "object", "description": "Transport result" } } } } } }, "400": { "description": "`to` is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily send cap reached for this inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/inboxes/{inbox}/otp": { "parameters": [ { "name": "inbox", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "otp" ], "summary": "Latest auto-extracted verification code", "description": "Returns the most recent inbound OTP, or `{\"code\": null}` if none. Poll with `since=` to ignore older codes.", "parameters": [ { "name": "since", "in": "query", "schema": { "type": "integer" }, "description": "Only consider messages received at/after this epoch-ms timestamp" } ], "responses": { "200": { "description": "Latest code, if any", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "message_id": { "type": "string" }, "from": { "type": "string" }, "received_at": { "type": "integer" } } } } } }, "404": { "description": "Inbox not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/messages/{message_id}": { "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "messages" ], "summary": "Get one message (full body + attachments + safety analysis)", "responses": { "200": { "description": "The message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "messages" ], "summary": "Delete a message", "description": "The consumer-side \"I've handled this\" primitive: removes the message (and its attachments) so it never reappears in a poll. Requires `write` scope.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/messages/{message_id}/attachments": { "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "messages" ], "summary": "List a message's attachments (metadata)", "responses": { "200": { "description": "Attachment metadata", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } } } } } }, "/v0/messages/{message_id}/attachments/{attachment_id}": { "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "messages" ], "summary": "Download attachment content", "responses": { "200": { "description": "Raw bytes with original content-type" }, "404": { "description": "Attachment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Content was too large to store inline (metadata only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "List webhooks (admin)", "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "webhooks" ], "summary": "Create a webhook (admin)", "description": "Events: `message.received`, `message.sent`, or `*`. Deliveries are HMAC-SHA256 signed with the shared secret in the `x-agentpost-signature` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "description": "Random UUID if omitted" }, "events": { "type": "array", "items": { "type": "string" }, "default": [ "*" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "`url` is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/webhooks/{webhook_id}": { "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "webhooks" ], "summary": "Delete a webhook (admin)", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/keys": { "get": { "tags": [ "keys" ], "summary": "List API keys (admin)", "responses": { "200": { "description": "Key metadata (never the raw keys)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "keys" ], "summary": "Create a scoped API key (admin)", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "admin" ] }, "default": [ "read", "write" ] } } } } } }, "responses": { "201": { "description": "Created — raw key shown exactly once", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "key": { "type": "string" } } } ] } } } }, "400": { "description": "Invalid scopes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/keys/{key_id}": { "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "keys" ], "summary": "Revoke an API key (admin)", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/domains": { "get": { "tags": [ "domains" ], "summary": "List domains", "responses": { "200": { "description": "Configured domains", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } } } }, "post": { "tags": [ "domains" ], "summary": "Add a domain (admin)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "sending_enabled": { "type": "boolean" }, "inbound_enabled": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Domain already configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/domains/{domain}": { "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id or name" } ], "get": { "tags": [ "domains" ], "summary": "Get one domain", "responses": { "200": { "description": "The domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "domains" ], "summary": "Update domain flags (admin)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sending_enabled": { "type": "boolean" }, "inbound_enabled": { "type": "boolean" }, "verification_status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "domains" ], "summary": "Remove a non-default domain (admin)", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/domains/{domain}/default": { "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "domains" ], "summary": "Make this the default domain (admin)", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "403": { "description": "Requires `admin` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/inbound": { "post": { "tags": [ "testing" ], "summary": "Simulate an inbound email", "description": "Feeds the same pipeline as real inbound mail (injection scoring, OTP extraction, webhooks). Body text/html is stored verbatim — real inbound mail is MIME-parsed before it gets here. Requires `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string", "description": "Must match an existing inbox address" }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_b64": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Ingested", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" }, "safety": { "type": "object" } } } } } }, "404": { "description": "No such inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from self-serve signup or POST /v0/keys" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable description naming the missing resource or problem" }, "docs": { "type": "string", "description": "Link to the API reference" } }, "required": [ "error" ] }, "Deleted": { "type": "object", "properties": { "deleted": { "type": "string", "description": "Id of the deleted resource" } } }, "Inbox": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "inbox_a1b2c3" ] }, "address": { "type": "string", "examples": [ "radar@maildesk.email" ] }, "name": { "type": [ "string", "null" ] }, "domain_id": { "type": [ "string", "null" ] }, "created_at": { "type": "integer", "description": "Epoch milliseconds" } } }, "Message": { "type": "object", "description": "All timestamps are epoch milliseconds. `injection_*` fields are only set on inbound messages.", "properties": { "id": { "type": "string", "examples": [ "msg_a1b2c3" ] }, "inbox_id": { "type": "string" }, "thread_id": { "type": "string", "description": "Messages sharing a normalized subject share a thread" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "from_addr": { "type": "string" }, "to_addr": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ], "description": "Plain-text body (decoded from MIME for real inbound mail)" }, "html": { "type": [ "string", "null" ] }, "preview": { "type": [ "string", "null" ], "description": "Short plain-text excerpt for list views" }, "injection_score": { "type": [ "integer", "null" ], "description": "0–100 prompt-injection risk", "minimum": 0, "maximum": 100 }, "injection_level": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", null ] }, "injection_flags": { "type": "array", "items": { "$ref": "#/components/schemas/InjectionFlag" }, "description": "Explainable signals behind the score" }, "otp_code": { "type": [ "string", "null" ], "description": "Auto-extracted verification code, if one was found" }, "labels": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "integer", "description": "Epoch milliseconds — use as the `since` poll cursor" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Present on GET /v0/messages/:id" } } }, "InjectionFlag": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "instruction_override" ] }, "weight": { "type": "integer" }, "detail": { "type": "string" } } }, "Attachment": { "type": "object", "properties": { "id": { "type": "string" }, "message_id": { "type": "string" }, "filename": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "size": { "type": "integer", "description": "Bytes" }, "has_content": { "type": "boolean", "description": "False when content was too large to store inline" }, "created_at": { "type": "integer" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string", "description": "HMAC-SHA256 signing secret" }, "events": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "integer" } } }, "ApiKey": { "type": "object", "description": "Key metadata. The raw key is only ever returned at creation.", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string", "description": "First characters of the key, for identification" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "read", "write", "admin" ] } }, "kind": { "type": [ "string", "null" ], "enum": [ "self_serve", null ] }, "owner_email": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "last_used_at": { "type": [ "integer", "null" ] } } }, "Domain": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "is_default": { "type": "integer", "enum": [ 0, 1 ] }, "sending_enabled": { "type": "integer", "enum": [ 0, 1 ] }, "inbound_enabled": { "type": "integer", "enum": [ 0, 1 ] }, "verification_status": { "type": "string" }, "created_at": { "type": "integer" } } } } } }