AgentInbox HTTP API

AgentInbox gives an AI agent its own email address. Your human owner creates the address and its API key in the dashboard at https://app.agentinbox.im and pays the invoice. The owner gives the key to you. With it you send and read mail.

Base URL: https://api.agentinbox.im.

Using an MCP client? The same key works at https://api.agentinbox.im/mcp, and a client that supports OAuth needs only that URL. See docs/mcp.md.

Example values are fake. Keys look like aik_... here; real keys are aik_ followed by 64 hex characters.

How it works

  1. Your owner signs in at https://app.agentinbox.im, creates your address, pays the invoice and gives you the API key. If you have no key, ask your owner to create an address there. You cannot sign up or create an address through the API.
  2. Send the key as Authorization: Bearer <api_key> on every request. One key gives access to exactly one address.
  3. Find your address with GET /v1/inboxes (a list with your one inbox) or GET /v1/agent.
  4. If status is pending_payment, give the payment_url to your owner, then poll GET /v1/inboxes/{inbox} until status is active. Do not pay it yourself.
  5. Send mail with POST /v1/inboxes/{inbox}/messages. Read mail with GET /v1/inboxes/{inbox}/messages.

If your key is lost or leaked, ask your owner to make a new one in the dashboard. The old key stops working at once.

Conventions

Authentication

Every endpoint except GET /v1/domains and GET /healthz needs the header:

Authorization: Bearer aik_...

Both responses carry WWW-Authenticate: Bearer. If you lose the key, or it stops working, ask your owner for a new one in the dashboard. There is no way to recover or replace it through the API.

Errors

Every error has this shape:

{
  "error": {
    "code": "inbox_not_found",
    "message": "No inbox with this ID."
  }
}

Branch on code. The message is written for you to read and says what to do next. The one extra field is payment_url on 402 payment_required and 403 inbox_suspended responses (see Send a message). The full table of codes is at the end of this document.

Limits

The service is for conversations, not bulk mail. These limits apply to every agent and inbox:

Limit Value Over the limit
Requests per agent per minute, to the API and to the MCP endpoint together 120 429 rate_limited
Unique recipients per message, to, cc and bcc together 20 422 too_many_recipients
Recipients per inbox per day, counted over all messages sent 200 429 daily_limit_reached
Messages sent per inbox per minute 10 429 send_rate_limited

Agents

Sign-up and address creation moved

POST /v1/agents answers 410 signup_moved. Agents cannot sign up through the API: your owner registers at https://app.agentinbox.im.

POST /v1/inboxes answers 410 inbox_creation_moved. Addresses are created only in the dashboard.

Get the calling agent

GET /v1/agent

No parameters. Response 200: the agent object: id, name (a label your owner chose), owner_email, created_at. Errors: 401 missing_api_key, 401 invalid_api_key.

curl -s https://api.agentinbox.im/v1/agent -H "Authorization: Bearer aik_9f2c..."
{"id": "k3q9x0example", "name": "Scout", "owner_email": "owner@example.com", "created_at": "2026-01-15T09:30:00Z"}

Domains

An inbox address is <name>@<domain>. The service has one or more mail domains. Your owner chooses one when creating the address.

List domains

GET /v1/domains

No API key needed. Response 200: {"domains": [{"domain": "agentinbox.im", "default": true}]}, in the order configured. The default domain is the first and has "default": true.

curl -s https://api.agentinbox.im/v1/domains

Inboxes

An inbox object has these fields:

Field Type Meaning
id string Inbox ID. Use it in paths.
address string The full email address, for example scout@agentinbox.im.
status string pending_payment, active or suspended. See Statuses.
billing_period string month or year: how often the inbox is invoiced.
payment_url string Only while pending_payment or suspended and an invoice is open or overdue. Give it to your owner.
next_step string Only while pending_payment or suspended. Says what to do next.
created_at string Creation time.

List inboxes

GET /v1/inboxes

Response 200: {"inboxes": [ ...inbox objects... ]}. Your key gives access to one address, so the list holds one inbox. Pending and suspended inboxes include next_step, and payment_url when there is an invoice to pay.

curl -s https://api.agentinbox.im/v1/inboxes -H "Authorization: Bearer aik_9f2c..."
{
  "inboxes": [
    {"id": "p7m2a1example", "address": "scout@agentinbox.im", "status": "active", "billing_period": "month", "created_at": "2026-01-15T09:31:00Z"}
  ]
}

Get an inbox

GET /v1/inboxes/{inbox}

Response 200: one inbox object. Poll this endpoint after you hand over the payment link, until status is active. Errors: 404 inbox_not_found.

The first invoice is due 7 days after it is made, but an address that is not paid within 2 days of its creation is deleted, with its API key, and its name is free again. At the start of each later period a new invoice is made, also due in 7 days. While it is open the inbox stays active; once it is overdue the inbox is suspended until it is paid.

For a pending_payment inbox, next_step is one of three texts:

For a suspended inbox, next_step is one of two texts:

curl -s https://api.agentinbox.im/v1/inboxes/p7m2a1example -H "Authorization: Bearer aik_9f2c..."
{"id": "p7m2a1example", "address": "scout@agentinbox.im", "status": "active", "billing_period": "month", "created_at": "2026-01-15T09:31:00Z"}

Inbox names

Your owner chooses the name in the dashboard. A name is valid if all of this is true after trimming and lowercasing:

Reserved names: abuse, admin, administrator, billing, hostmaster, mailer-daemon, no-reply, noreply, postmaster, root, security, support, webmaster.

Messages

Send a message

POST /v1/inboxes/{inbox}/messages

The inbox must be active. The mail is sent from the inbox address. You cannot set the sender.

Field Type Required Notes
to array of strings one of to, cc, bcc Addresses like bob@example.com or "Bob <bob@example.com>".
cc array of strings see to Same format.
bcc array of strings see to Same format. Receives the mail but is not in the message headers.
subject string no Any text.
text string no Plain text body.
html string no HTML body. You may send text, html or both.
attachments array of objects no See below.
in_reply_to string no The id of a message in this same inbox. Threads the reply.

At least one recipient is needed across to, cc and bcc. Duplicate addresses (compared ignoring case) get one delivery.

Each recipient address must have an ASCII local part of at most 64 characters, made of letters, digits and !#$%&'*+-/=?^_`{|}~, with dots only between parts. The domain must be a dotted hostname (at most 253 characters, labels of at most 63 characters, letters, digits and hyphens).

Each attachment:

Field Type Required Notes
filename string yes Not empty.
content_type string no A MIME type such as application/pdf. Empty means application/octet-stream.
content_base64 string yes Standard base64 (with padding) of the file.

The only size limit in the code is the 15 MB request body.

Header Idempotency-Key (optional, but always send one): 1 to 255 printable ASCII characters (space to ~), given once. Use a UUID. See Idempotent sending below.

Response 202: the message object (see below) with deliveries, one per unique recipient. 202 means the message is accepted and queued, not that it has arrived. Read the delivery statuses later with GET /v1/inboxes/{inbox}/messages/{message}.

Response 200: sent only when you used an Idempotency-Key that this inbox already used. The body is the message sent the first time, with its deliveries as they are now. The header Idempotent-Replay: true is set. Nothing is sent again.

Errors:

The status of the inbox is checked before the body is read, so a pending inbox answers 402, and a suspended one 403, whatever the body holds. The Idempotency-Key header is checked right after the inbox status and before the body is read.

curl -s -X POST https://api.agentinbox.im/v1/inboxes/p7m2a1example/messages \
  -H "Authorization: Bearer aik_9f2c..." \
  -H "Idempotency-Key: 0b6f0c1e-3c1a-4f57-9d1e-5a2f8e7c4b10" \
  -d '{"to": ["bob@example.com"], "subject": "Hello", "text": "Hi Bob."}'
{
  "id": "m1d4e8example",
  "inbox_id": "p7m2a1example",
  "thread_id": "t5h2r0example",
  "direction": "outbound",
  "message_id": "n8c3v6example@agentinbox.im",
  "references": [],
  "from": "scout@agentinbox.im",
  "to": ["bob@example.com"],
  "cc": [],
  "subject": "Hello",
  "text": "Hi Bob.",
  "html": "",
  "attachments": [],
  "deliveries": [
    {
      "id": "d2w7y1example",
      "recipient": "bob@example.com",
      "status": "queued",
      "attempts": 0,
      "next_attempt_at": "2026-01-15T09:40:00Z",
      "created_at": "2026-01-15T09:40:00Z",
      "updated_at": "2026-01-15T09:40:00Z"
    }
  ],
  "created_at": "2026-01-15T09:40:00Z"
}

Idempotent sending

Without a key, a retried send request sends the mail twice. With an Idempotency-Key, the mail goes out at most once per key.

Always send a key, a UUID that you make once for each message. After a timeout or a 5xx, send the same request again with the same key. You get either the first message back or a normal send. Never send twice by mistake.

The message object

Field Type Meaning
id string Message ID. Use it in paths and as in_reply_to.
inbox_id string The inbox.
thread_id string Groups a message with its replies in this inbox.
direction string inbound (received) or outbound (sent).
message_id string The Message-ID header.
in_reply_to string The Message-ID replied to. Left out if none.
references array of strings Message-IDs of earlier messages in the thread. May be empty.
from string Sender address.
to, cc array of strings Recipient addresses. May be empty.
subject string Subject.
text string Plain text body.
html string HTML body. Left out of the message list. Present when you get one message or a thread.
attachments array Each has id, filename, content_type, size (bytes).
authentication object Inbound only: spf, dkim, dmarc. See Statuses.
spam boolean Inbound only. The spam filter's verdict: true if the message was judged spam but delivered. Messages it rejects are not stored. false when no spam filter is configured.
spam_score number Inbound only. Rspamd's score; higher means more likely spam. 0 when no spam filter is configured.
deliveries array Outbound only, and only when you send or get one message.
created_at string When the message was stored.

A delivery object has: id, recipient, status, attempts, last_error (only when set), next_attempt_at (only while queued or deferred), created_at, updated_at.

bcc recipients appear in deliveries but not in to or cc.

List messages

GET /v1/inboxes/{inbox}/messages?limit=&cursor=

Query Type Notes
limit integer 1 to 100. Default 50. Anything else gives 400 invalid_limit.
cursor string The next_cursor of the previous page. Leave out for the first page. A bad value gives 400 invalid_cursor.

Response 200: {"messages": [...], "next_cursor": "..."}. Messages are newest first, inbound and outbound together. They have no html field and no deliveries. To read new mail, list the first page and look for IDs you have not seen. This is how you poll for new mail.

Pagination: if next_cursor is not empty, pass it unchanged as cursor to get the next page. An empty next_cursor means the last page. Do not build or change cursors.

Errors: 404 inbox_not_found, 400 invalid_limit, 400 invalid_cursor.

curl -s "https://api.agentinbox.im/v1/inboxes/p7m2a1example/messages?limit=2" \
  -H "Authorization: Bearer aik_9f2c..."
{
  "messages": [
    {
      "id": "m9z3k2example",
      "inbox_id": "p7m2a1example",
      "thread_id": "t5h2r0example",
      "direction": "inbound",
      "message_id": "CAF1234example@mail.example.com",
      "in_reply_to": "n8c3v6example@agentinbox.im",
      "references": ["n8c3v6example@agentinbox.im"],
      "from": "bob@example.com",
      "to": ["scout@agentinbox.im"],
      "cc": [],
      "subject": "Re: Hello",
      "text": "Hi Scout, got it.",
      "attachments": [],
      "authentication": {"spf": "pass", "dkim": "pass", "dmarc": "pass"},
      "spam": false,
      "spam_score": 0.4,
      "created_at": "2026-01-15T09:45:00Z"
    }
  ],
  "next_cursor": "opaque-cursor-value"
}

Get a message

GET /v1/inboxes/{inbox}/messages/{message}

Response 200: the message object with html, and with deliveries if outbound. Errors: 404 inbox_not_found, 404 message_not_found.

Get a thread

GET /v1/inboxes/{inbox}/threads/{thread}

Response 200: {"thread_id": "...", "messages": [...]}. Messages are oldest first and include html. They do not include deliveries. Use the thread_id of any message. Errors: 404 inbox_not_found, 404 thread_not_found.

Get the raw message

GET /v1/inboxes/{inbox}/messages/{message}/raw

Response 200: the full RFC 5322 message as message/rfc822, sent as a download named <message id>.eml. Errors: 404 inbox_not_found, 404 message_not_found, 500 internal_error.

curl -s https://api.agentinbox.im/v1/inboxes/p7m2a1example/messages/m9z3k2example/raw \
  -H "Authorization: Bearer aik_9f2c..." -o message.eml

Get an attachment

GET /v1/inboxes/{inbox}/messages/{message}/attachments/{attachment}

Response 200: the file bytes, with the attachment's content_type (or application/octet-stream) and a download filename. Take the attachment ID from the attachments list of the message. Errors: 404 inbox_not_found, 404 message_not_found, 404 attachment_not_found, 500 internal_error.

curl -s https://api.agentinbox.im/v1/inboxes/p7m2a1example/messages/m9z3k2example/attachments/a4b8c2example \
  -H "Authorization: Bearer aik_9f2c..." -o report.pdf

Webhooks

A webhook is an https URL of yours. When mail arrives in your inbox, AgentInbox sends a message.received event to each of your webhooks with a POST request. Spam is included, with spam true. An event is created for each webhook that exists when the mail arrives. You can have up to 5 webhooks for your address. Webhooks do not replace the message list: fetch the message with GET /v1/inboxes/{inbox}/messages/{message} and keep polling as a fallback.

A webhook object has: id, url, created_at, and secret (only in the response that creates it).

Create a webhook

POST /v1/webhooks

Field Type Required Limits
url string yes An absolute https URL with a host and no user name or password. At most 2048 bytes. An IP address as host must be public.

Response 201: the webhook object with secret, whsec_ followed by 64 hex characters. It is shown only once and cannot be recovered; to get a new one, delete the webhook and create another.

Errors: 422 invalid_url, 409 webhook_limit (you have 5 already), 400 invalid_json, 400 unknown_field, 413 body_too_large.

curl -s -X POST https://api.agentinbox.im/v1/webhooks \
  -H "Authorization: Bearer aik_9f2c..." \
  -d '{"url": "https://example.com/agentinbox"}'
{
  "id": "w4n7c1example",
  "url": "https://example.com/agentinbox",
  "created_at": "2026-01-15T09:50:00Z",
  "secret": "whsec_5b1e..."
}

List webhooks

GET /v1/webhooks

Response 200: {"webhooks": [...]}, oldest first, without secret.

Delete a webhook

DELETE /v1/webhooks/{webhook}

Response 204 with no body. Events for it that were not sent yet are dropped. Errors: 404 webhook_not_found.

The request

POST /agentinbox HTTP/1.1
Content-Type: application/json
User-Agent: AgentInbox-Webhooks/1.0 (+https://agentinbox.im)
AgentInbox-Event-Id: e2r8d5example
AgentInbox-Signature: t=1768470305,v1=6f1c...
{
  "id": "e2r8d5example",
  "type": "message.received",
  "created_at": "2026-01-15T09:45:05Z",
  "data": {
    "inbox_id": "p7m2a1example",
    "message_id": "m9z3k2example",
    "thread_id": "t5h2r0example",
    "from": "bob@example.com",
    "subject": "Re: Hello",
    "spam": false,
    "received_at": "2026-01-15T09:45:05Z"
  }
}

id is the event ID, the same as AgentInbox-Event-Id, and stays the same on every retry. data.message_id is the id of the message in the API, not its Message-ID header.

Answer with any 2xx status within 10 seconds. Do the work afterwards. The response body is ignored.

Verify the signature

AgentInbox-Signature is t=<unix time>,v1=<signature>. The signature is the hex HMAC-SHA256, keyed with your webhook secret, of the t value, a ., and the raw request body. To verify:

  1. Take t and v1 from the header.
  2. Compute the HMAC over t + "." + body, using the body bytes exactly as received, before any JSON parsing.
  3. Compare it with v1 in constant time.
  4. Reject the request if t is more than 5 minutes from your clock.
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts.get("t", ""), parts.get("v1", "")
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig) and t.isdigit() and abs(time.time() - int(t)) < 300

Delivery and retries

Statuses

Inbox statuses:

Delivery statuses (one per recipient of a sent message):

Authentication results on received mail (authentication). Each of spf, dkim and dmarc is one of the values below, using the names of RFC 8601:

Values: pass (check succeeded), fail (check failed), softfail (SPF failed, but the domain asked for only mild treatment), neutral (the domain made no claim), none (no record or no signature to check, or no result stored), temperror (a temporary lookup problem), permerror (the domain's record is broken). Treat anything other than pass with care, especially fail.

Error codes

Status Code What to do
400 invalid_json Fix the body. It must be one JSON object, with nothing after it.
400 unknown_field Remove the field the message names.
400 invalid_limit Use a whole number from 1 to 100.
400 invalid_cursor Pass next_cursor unchanged, or leave cursor out.
401 missing_api_key Send Authorization: Bearer <api_key>.
401 invalid_api_key Use the key your owner gave you. If it is lost or replaced, ask your owner for a new one in the dashboard.
402 payment_required Give payment_url to your owner, then poll the inbox until active.
403 inbox_suspended Stop sending. Give payment_url to your owner if there is one, otherwise ask your owner to contact AgentInbox support. Reading still works.
403 domain_not_available The inbox's domain was removed from the service. Reading still works. Ask your owner to create an address on a domain from GET /v1/domains to send.
403 inbox_not_active Check the inbox with GET /v1/inboxes/{inbox}, then retry when active.
404 not_found Check the method and path.
404 inbox_not_found Check the ID with GET /v1/inboxes.
404 message_not_found Check the ID with the message list.
404 thread_not_found Use the thread_id of a message in this inbox.
404 attachment_not_found Use an ID from the message's attachments.
404 webhook_not_found Check the ID with GET /v1/webhooks.
409 webhook_limit You have 5 webhooks. Delete one with DELETE /v1/webhooks/{webhook} first.
410 signup_moved Ask your owner to register at https://app.agentinbox.im. Agents cannot sign up through the API.
410 inbox_creation_moved Ask your owner to create the address in the dashboard.
413 body_too_large Send a smaller body (64 KB; 15 MB for sending).
422 no_recipients Add an address to to, cc or bcc.
422 invalid_recipient Fix the address the message names.
422 invalid_attachment Fix base64, add a filename, or fix content_type.
422 reply_not_found Use the id of a message in the same inbox.
422 invalid_url Give an absolute https URL with a public host, no user name or password, at most 2048 bytes.
422 invalid_idempotency_key Send Idempotency-Key once, with 1 to 255 printable ASCII characters, such as a UUID. Or leave it out.
422 too_many_recipients Send the message only to the people taking part in the conversation, at most 20.
429 rate_limited Wait the seconds in Retry-After, then spread your requests out. See Limits.
429 daily_limit_reached Nothing was sent. Wait until 00:00 UTC (Retry-After). If you legitimately need more, ask your owner to contact AgentInbox support.
429 send_rate_limited Nothing was sent. Wait the seconds in Retry-After, then send it again.
500 internal_error A fault on our side. Retry later. For a send request, retry with the same Idempotency-Key, so you do not send twice.

Not available yet