# AgentInbox API AgentInbox gives an AI agent its own email address. You sign up over HTTP, create an inbox, and give a payment link to your human owner. When it is paid, the inbox is active and you can send and receive mail. Base URL: https://api.agentinbox.im (final URL not fixed yet) Full reference: docs/api.md ## Lifecycle 1. POST /v1/agents with name and owner_email. Keep api_key: shown once, cannot be recovered. 2. Send "Authorization: Bearer " on every other request (not on sign-up or /healthz). 3. Optional: GET /v1/domains to see the domains you can choose from. POST /v1/inboxes with name (and optionally domain). The inbox is pending_payment. 4. Give payment_url to your owner. Do not pay it yourself. 5. Poll GET /v1/inboxes/{inbox} until status is "active". 6. Send with POST /v1/inboxes/{inbox}/messages. Read with GET /v1/inboxes/{inbox}/messages. ## Conventions - JSON in and out, except raw message and attachment downloads. - Unknown request fields are rejected (400 unknown_field). Body limit 64 KB; 40 MB for sending. - Times are RFC 3339 UTC. IDs are opaque strings. - Another agent's inbox/message answers 404, same as a missing one. - Errors: {"error": {"code": "...", "message": "..."}}. Branch on code. 402 payment_required and 403 inbox_suspended also have payment_url when there is an invoice to pay. ## Endpoints GET /healthz (no key) -> 200 {"status":"ok"} POST /v1/agents (no key) body: name (string, required, 1-200 bytes after trim), owner_email (string, required, bare address like owner@example.com) 201: agent {id, name, owner_email, created_at}, api_key, next_step errors: 422 invalid_name, 422 invalid_owner_email, 400 invalid_json, 400 unknown_field, 413 body_too_large GET /v1/agent 200: {id, name, owner_email, created_at} GET /v1/domains (no key) 200: {"domains": [{"domain": "agentinbox.im", "default": true}, ...]}. Call it to see your choices. POST /v1/inboxes body: name (string, required; the part before @; see names below) domain (string, optional; one of GET /v1/domains; default: the default domain) billing_period (string, optional; "month" or "year"; default "month"; a year costs 11 months) Address is name@domain; the same name on two domains is two different inboxes. 201 new inbox, 200 if you already own that address (retry; retries a failed invoice; keeps the existing billing_period, and next_step says so if you asked for another) returns inbox: {id, address, status, billing_period, payment_url?, next_step?, created_at} Each period gets an invoice, due in 7 days. Overdue -> suspended until paid. errors: 422 invalid_name, 422 reserved_name, 422 invalid_domain, 422 invalid_billing_period, 409 address_taken, 502 billing_failed (repeat the same request), 503 billing_not_configured, 400 invalid_json, 400 unknown_field, 413 body_too_large GET /v1/inboxes 200: {"inboxes": [inbox, ...]} GET /v1/inboxes/{inbox} 200: inbox. next_step only while pending_payment or suspended; payment_url when there is an invoice to pay. errors: 404 inbox_not_found POST /v1/inboxes/{inbox}/messages (inbox must be active; sender is the inbox address) body: to, cc, bcc: arrays of strings, "bob@example.com" or "Bob ". At least one recipient in total. subject: string, optional text: string, optional. html: string, optional. attachments: optional array of {filename (required), content_type (optional MIME, default application/octet-stream), content_base64 (required, standard base64)} in_reply_to: optional, the id of a message in this inbox (threads the reply) header Idempotency-Key: optional, always send one (a UUID). 1-255 printable ASCII chars, given once. 202: message object with deliveries (accepted and queued, not yet delivered) errors: 402 payment_required (body also has payment_url), 403 inbox_suspended (payment_url if overdue), 403 inbox_not_active, 403 domain_not_available, 404 inbox_not_found, 422 no_recipients, 422 invalid_recipient, 422 invalid_attachment, 422 reply_not_found, 422 invalid_idempotency_key (checked after the inbox status, before the body), 400 invalid_json, 400 unknown_field, 413 body_too_large Idempotency: same key in the same inbox again = 200 + header Idempotent-Replay: true, with the first message and its deliveries as they are now. Nothing is sent again. New body is NOT compared: a reused key returns the first message. Keys are per inbox. Without a key, a retry sends twice. After a timeout or 5xx, retry with the same key. GET /v1/inboxes/{inbox}/messages?limit=&cursor= 200: {"messages": [message, ...], "next_cursor": "..."} Newest first, inbound and outbound. No html field and no deliveries in the list. limit: 1-100, default 50. cursor: pass next_cursor unchanged; omit for page 1. Empty next_cursor = last page. Poll the first page for new mail and look for unseen ids. errors: 404 inbox_not_found, 400 invalid_limit, 400 invalid_cursor GET /v1/inboxes/{inbox}/messages/{message} 200: message with html; outbound messages also have deliveries. errors: 404 inbox_not_found, 404 message_not_found GET /v1/inboxes/{inbox}/threads/{thread} 200: {"thread_id": "...", "messages": [message, ...]} oldest first, with html, no deliveries. errors: 404 inbox_not_found, 404 thread_not_found GET /v1/inboxes/{inbox}/messages/{message}/raw 200: raw message, message/rfc822. errors: 404 inbox_not_found, 404 message_not_found, 500 internal_error GET /v1/inboxes/{inbox}/messages/{message}/attachments/{attachment} 200: file bytes. Attachment id comes from the message's attachments. errors: 404 inbox_not_found, 404 message_not_found, 404 attachment_not_found, 500 internal_error POST /v1/webhooks body: url (string, required; absolute https, has a host, no user:pass, max 2048 bytes; an IP host must be public) 201: {id, url, created_at, secret}. secret is whsec_ + 64 hex, shown once, cannot be recovered. Covers all your inboxes. Max 5 webhooks. errors: 422 invalid_url, 409 webhook_limit, 400 invalid_json, 400 unknown_field, 413 body_too_large GET /v1/webhooks 200: {"webhooks": [{id, url, created_at}, ...]} oldest first, no secrets DELETE /v1/webhooks/{webhook} 204. Unsent events for it are dropped. errors: 404 webhook_not_found ## Webhook events On new mail in any inbox (spam too), POST to each webhook that existed when the mail arrived: headers: Content-Type: application/json, AgentInbox-Event-Id: , AgentInbox-Signature: t=,v1= body: {"id", "type": "message.received", "created_at", "data": {inbox_id, message_id, thread_id, from, subject, spam, received_at}}. data.message_id is the API message id; fetch it with GET .../messages/{message}. Verify: v1 = hex HMAC-SHA256(key = secret, data = t + "." + raw body). Compare in constant time; reject t over 5 min old. Answer 2xx within 10 s; do the work after. Non-2xx, redirect (not followed), error or timeout = retry. Retries after 1, 2, 4, 8, 16, 32, 64, 128, 256 min, then 6 h twice (+ up to 10%): 12 attempts, ~21 h, then dropped. At least once: the same id can arrive twice; skip ids you have handled. Not ordered. Sent only to public addresses, never through a proxy. A host resolving to loopback, private, link-local, 100.64/10, multicast, reserved, benchmarking, documentation, NAT64, 6to4, Teredo or IPv4-compatible addresses fails the event at once, no retry. ## Message object id, inbox_id, thread_id, direction ("inbound"|"outbound"), message_id (Message-ID header), in_reply_to (omitted if none), references[], from, to[], cc[], subject, text, html (not in lists), attachments[] {id, filename, content_type, size}, created_at. Inbound only: authentication {spf, dkim, dmarc}, spam (boolean, the verdict), spam_score (number, Rspamd's score, higher is spammier); both are 0/false when no spam filter is configured. Outbound only, single message: deliveries[] {id, recipient, status, attempts, last_error?, next_attempt_at?, created_at, updated_at}. Bcc recipients appear in deliveries, not in to/cc. ## Inbox names 1-64 chars of a-z 0-9 . _ - ; trimmed and lowercased; starts and ends with a letter or digit; no two dots in a row. Reserved (422 reserved_name): abuse, admin, administrator, billing, hostmaster, mailer-daemon, no-reply, noreply, postmaster, root, security, support, webmaster. Other rule breaks: 422 invalid_name. ## Statuses Inbox: pending_payment = invoice not paid, cannot send or receive. active = can send and receive. suspended = invoice overdue or subscription ended; cannot send or receive, reading still works. If payment_url is set, give it to your owner; active again once paid. Otherwise owner contacts AgentInbox support. Delivery (per recipient): queued = waiting for first attempt. sending = being attempted now. deferred = temporary failure, retry scheduled. delivered = recipient server accepted (final). bounced = recipient server rejected for good (final). failed = stopped without a bounce, see last_error (final). Authentication on received mail: spf = sending server allowed for the sender's domain; dkim = valid signature from the sender's domain; dmarc = passed the domain's policy. Values: pass, fail, softfail, neutral, none (nothing to check or no result), temperror (temporary lookup problem), permerror (broken domain record). Be careful with non-pass. ## Error codes and what to do 400 invalid_json: fix body, one JSON object only 400 unknown_field: remove the named field 400 invalid_limit: whole number 1-100 400 invalid_cursor: pass next_cursor unchanged, or omit 401 missing_api_key: send Authorization: Bearer 401 invalid_api_key: use the key from sign-up; lost keys cannot be recovered 402 payment_required: give payment_url to owner, poll inbox until active 403 inbox_suspended: stop sending; give payment_url to owner if set, else owner contacts support 403 inbox_not_active: check inbox status, retry when active 403 domain_not_available: the inbox domain was removed; reading works; create an inbox on a domain from GET /v1/domains to send 404 not_found: wrong method or path 404 inbox_not_found / message_not_found / thread_not_found / attachment_not_found / webhook_not_found: check the ID by listing 409 address_taken: choose another name or domain 409 webhook_limit: 5 webhooks already; delete one first 413 body_too_large: smaller body (64 KB; 40 MB for sending) 422 invalid_name: agent name must be 1-200; inbox name must follow the rules above 422 reserved_name: choose another name 422 invalid_domain: use a domain from GET /v1/domains, or omit domain 422 invalid_billing_period: "month" or "year", or omit for "month" 422 invalid_owner_email: bare address like owner@example.com 422 no_recipients / invalid_recipient / invalid_attachment / reply_not_found: fix the send request 422 invalid_url: absolute https URL, public host, no user:pass, max 2048 bytes 422 invalid_idempotency_key: send the header once, 1-255 printable ASCII chars (a UUID), or omit it 500 internal_error: retry later; for sends, retry with the same Idempotency-Key 502 billing_failed: repeat the same POST /v1/inboxes (same name and domain) 503 billing_not_configured: billing is not configured on this service; try later ## Not available yet - No change of billing period and no cancelling through the API. - Webhooks: only message.received; no update, secret rotation or event log. - No rate limits documented; none enforced in the API code. Back off on errors. - Idempotent sending needs the Idempotency-Key header. Without it, a retried send sends twice. - No delete, no API key rotation or recovery, no search or filters on the message list.