# AgentInbox HTTP API

AgentInbox gives an AI agent its own email address. The agent signs itself up over HTTP, creates an inbox, and hands a payment link to its human owner. When the owner pays, the inbox becomes active and the agent can send and receive mail.

Base URL in all examples: `https://api.agentinbox.im`. The final URL is not fixed yet.

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

## How it works

1. Sign up with `POST /v1/agents`. You give a name and the email address of your owner (the human who pays).
2. Keep the `api_key` from the response. It is shown once and cannot be recovered. Send it on every other request.
3. Optionally call `GET /v1/domains` to see which domains your address can use. Create an inbox with `POST /v1/inboxes`. The inbox starts as `pending_payment`.
4. Give the `payment_url` from the response to your owner. Do not pay it yourself.
5. Poll `GET /v1/inboxes/{inbox}` until `status` is `active`.
6. Send mail with `POST /v1/inboxes/{inbox}/messages`. Read mail with `GET /v1/inboxes/{inbox}/messages`.

## Conventions

- Requests and responses are JSON, except the two download endpoints (raw message and attachment). Send bodies as JSON; the server does not require a `Content-Type` header.
- Unknown fields in a request body are rejected with `unknown_field`. Trailing data after the JSON object is rejected with `invalid_json`.
- Request bodies are limited to 64 KB (65,536 bytes). The send endpoint allows 40 MB (41,943,040 bytes), counted on the JSON body, so base64 attachments count at their encoded size. A larger body gets 413 `body_too_large`.
- Times are RFC 3339 in UTC, for example `2026-01-15T09:30:00Z`.
- IDs are opaque strings. Use them as returned.
- Another agent's inbox, message or thread answers 404, the same as one that does not exist.
- A request to a path or method that does not exist answers 404 `not_found`.
- `GET /healthz` needs no key and answers `{"status": "ok"}`.

## Authentication

Every endpoint except `POST /v1/agents` and `GET /healthz` needs the header:

```
Authorization: Bearer aik_...
```

- No header, or an empty key: 401 `missing_api_key`.
- A key the server does not know: 401 `invalid_api_key`.

Both responses carry `WWW-Authenticate: Bearer`. If you lose the key, there is no way to recover it through the API.

## Errors

Every error has this shape:

```json
{
  "error": {
    "code": "invalid_name",
    "message": "Give the agent a name of 1 to 200 characters in the field \"name\"."
  }
}
```

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.

## Agents

### Sign up

`POST /v1/agents` (no key needed)

| Field | Type | Required | Limits |
| --- | --- | --- | --- |
| `name` | string | yes | Trimmed. 1 to 200 bytes. |
| `owner_email` | string | yes | A bare address such as `owner@example.com`. No display name. The domain needs a dot. |

Response 201:

| Field | Type | Meaning |
| --- | --- | --- |
| `agent.id` | string | Agent ID. |
| `agent.name` | string | The trimmed name. |
| `agent.owner_email` | string | The owner address, with the domain in lowercase. |
| `agent.created_at` | string | Time of sign-up. |
| `api_key` | string | Your API key. Shown only once. |
| `next_step` | string | What to do next. |

Errors: 422 `invalid_name`, 422 `invalid_owner_email`, 400 `invalid_json`, 400 `unknown_field`, 413 `body_too_large`.

```sh
curl -s -X POST https://api.agentinbox.im/v1/agents \
  -d '{"name": "Scout", "owner_email": "owner@example.com"}'
```

```json
{
  "agent": {
    "id": "k3q9x0example",
    "name": "Scout",
    "owner_email": "owner@example.com",
    "created_at": "2026-01-15T09:30:00Z"
  },
  "api_key": "aik_9f2c...",
  "next_step": "Store api_key now: it is shown only this once and cannot be recovered. Send it as \"Authorization: Bearer <api_key>\" on every other request, then create an inbox with POST /v1/inboxes."
}
```

Each call creates a new agent. Calling it again does not return the old key.

### Get the calling agent

`GET /v1/agent`

No parameters. Response 200: the same object as `agent` above (`id`, `name`, `owner_email`, `created_at`). Errors: 401 `missing_api_key`, 401 `invalid_api_key`.

```sh
curl -s https://api.agentinbox.im/v1/agent -H "Authorization: Bearer aik_9f2c..."
```

```json
{"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. Call `GET /v1/domains` to see your choices. Without a `domain`, `POST /v1/inboxes` uses the default one.

### 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`.

```sh
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. |

### Create an inbox

`POST /v1/inboxes`

| Field | Type | Required | Limits |
| --- | --- | --- | --- |
| `name` | string | yes | The part before the `@`. Trimmed and lowercased. 1 to 64 characters. See Inbox names. |
| `domain` | string | no | One of the domains from `GET /v1/domains`. Trimmed and lowercased. Default: the default domain. |
| `billing_period` | string | no | `month` or `year`. Default: `month`. The inbox is a subscription invoiced once per period; a year costs 11 times a month. |

The address is `<name>@<domain>`. `alice@agentinbox.im` and `alice@other.example` are two different inboxes.

Response 201 with the inbox object for a new inbox. Response 200 with the same object if you already own that address (a retry). If the earlier try left the inbox without an invoice, a repeat call tries to create the invoice again. A repeat keeps the inbox's `billing_period`: if you ask for another one, it is not applied and `next_step` says so.

The first invoice is due 7 days after it is made. 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.

Errors:

- 422 `invalid_name`: the name breaks the rules.
- 422 `reserved_name`: the name is reserved.
- 422 `invalid_domain`: the domain is not one of the service's domains. The message lists them.
- 422 `invalid_billing_period`: `billing_period` is not `month` or `year`.
- 409 `address_taken`: another agent owns the address (the full address, name and domain). Choose another name or domain.
- 502 `billing_failed`: the inbox is reserved for you but the invoice could not be created. Repeat the same request, with the same `name` and `domain`.
- 503 `billing_not_configured`: billing is not configured on this service. Try again later.
- 400 `invalid_json`, 400 `unknown_field`, 413 `body_too_large`.

```sh
curl -s -X POST https://api.agentinbox.im/v1/inboxes \
  -H "Authorization: Bearer aik_9f2c..." \
  -d '{"name": "scout"}'
```

```json
{
  "id": "p7m2a1example",
  "address": "scout@agentinbox.im",
  "status": "pending_payment",
  "billing_period": "month",
  "payment_url": "https://invoice.stripe.com/i/acct_example/abc123",
  "next_step": "Give payment_url to your owner. The inbox becomes active, and can send and receive mail, once the invoice is paid.",
  "created_at": "2026-01-15T09:31:00Z"
}
```

Give `payment_url` to your owner now.

### List inboxes

`GET /v1/inboxes`

Response 200: `{"inboxes": [ ...inbox objects... ]}`. The list is empty (`[]`) if you have none. Pending and suspended inboxes include `next_step`, and `payment_url` when there is an invoice to pay.

```sh
curl -s https://api.agentinbox.im/v1/inboxes -H "Authorization: Bearer aik_9f2c..."
```

```json
{
  "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`.

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

- An invoice is open: `payment_url` is set. Give it to your owner.
- The invoice is paid: no `payment_url`. The inbox turns active shortly. Check again.
- No invoice exists: repeat `POST /v1/inboxes` with the same name and domain.

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

- An invoice is overdue: `payment_url` is set. Give it to your owner. The inbox can send and receive again once it is paid. Poll this endpoint until `status` is `active`.
- The subscription has ended: no `payment_url`. Your owner must contact AgentInbox support.

```sh
curl -s https://api.agentinbox.im/v1/inboxes/p7m2a1example -H "Authorization: Bearer aik_9f2c..."
```

```json
{"id": "p7m2a1example", "address": "scout@agentinbox.im", "status": "active", "billing_period": "month", "created_at": "2026-01-15T09:31:00Z"}
```

### Inbox names

A name is valid if all of this is true after trimming and lowercasing:

- It is 1 to 64 characters long.
- It uses only `a-z`, `0-9`, `.`, `_` and `-`.
- It starts and ends with a letter or digit.
- It has no two dots in a row.
- It is not reserved.

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

A name that breaks the other rules gives 422 `invalid_name`.

## 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 40 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:

- 402 `payment_required`: the inbox is `pending_payment`. The body also holds `payment_url` when an invoice is open. Give it to your owner.
- 403 `inbox_suspended`: the inbox is suspended. You can still read its mail. The body also holds `payment_url` when an invoice is overdue. Give it to your owner.
- 403 `domain_not_available`: the inbox's domain was removed from the service. You can still read its mail.
- 403 `inbox_not_active`: the inbox stopped being active while the request ran. Check its status.
- 404 `inbox_not_found`.
- 422 `no_recipients`: no address in `to`, `cc` or `bcc`.
- 422 `invalid_recipient`: an address cannot be used. The message names it.
- 422 `invalid_attachment`: bad base64, a missing filename or an invalid `content_type`.
- 422 `reply_not_found`: `in_reply_to` is not the ID of a message in this inbox.
- 422 `invalid_idempotency_key`: the `Idempotency-Key` header is empty, longer than 255 characters, has a character that is not printable ASCII, or is given more than once.
- 400 `invalid_json`, 400 `unknown_field`, 413 `body_too_large`.

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.

```sh
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."}'
```

```json
{
  "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.

- The first request with a key answers 202, as above.
- A later request with the same key in the same inbox answers 200 with the message sent the first time and `Idempotent-Replay: true`. Nothing is sent again. The `deliveries` show their current statuses.
- Keys are per inbox. The same key in another inbox is a new key.
- The new request body is not compared with the first one. If you reuse a key with a different body, you get the first message back and the new body is ignored. Use a new key for each new message.
- The response never shows the key.
- On a replay the inbox must still be `active`, and the body must still be valid JSON with valid base64 attachments. Recipients and `in_reply_to` are not checked again.

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-ID`s 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`.

```sh
curl -s "https://api.agentinbox.im/v1/inboxes/p7m2a1example/messages?limit=2" \
  -H "Authorization: Bearer aik_9f2c..."
```

```json
{
  "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`.

```sh
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`.

```sh
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 any of your inboxes, 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. 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`.

```sh
curl -s -X POST https://api.agentinbox.im/v1/webhooks \
  -H "Authorization: Bearer aik_9f2c..." \
  -d '{"url": "https://example.com/agentinbox"}'
```

```json
{
  "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...
```

```json
{
  "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.

```python
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

- Delivery is at least once. The same event can arrive more than once, so skip any `id` you have handled already.
- Events are not ordered. Use `received_at`, or the message list, for order.
- Any 2xx answer is success. Anything else is a failure: another status, a redirect (redirects are not followed), a connection error, or no answer within 10 seconds.
- A failed event is retried after 1, 2, 4, 8, 16, 32, 64, 128 and 256 minutes, then twice more after 6 hours, each wait plus up to 10%. That is 12 attempts over about 21 hours. After the 12th failure the event is dropped. The webhook stays registered and later events are still sent.
- Requests go only to public addresses. If the host of your URL resolves to a loopback, private, link-local, shared (100.64.0.0/10), multicast, reserved, benchmarking or documentation address, or to a NAT64, 6to4, Teredo or IPv4-compatible IPv6 address, the event fails at once and is not retried. Requests do not go through a proxy.

## Statuses

Inbox statuses:

- `pending_payment`: the first invoice is not paid yet; the inbox cannot send or receive mail.
- `active`: the inbox is paid and can send and receive mail.
- `suspended`: an invoice is overdue, or the subscription has ended. The inbox cannot send or receive mail; you can still read its mail. If an invoice is overdue, give `payment_url` to your owner; the inbox is active again once it is paid. Otherwise your owner must contact AgentInbox support.

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

- `queued`: waiting for the first attempt.
- `sending`: a delivery worker is trying now.
- `deferred`: an attempt failed for a temporary reason; a new attempt is scheduled (`next_attempt_at`).
- `delivered`: the recipient's server accepted the mail. This is final.
- `bounced`: the recipient's server rejected the mail for good. This is final. See `last_error`.
- `failed`: delivery stopped without a bounce from the recipient's server, for example a permanent local error, too many attempts, or a recipient on the suppression list. This is final. See `last_error`.

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

- `spf`: whether the sending server was allowed to send for the sender's domain.
- `dkim`: whether the message carried a valid signature from the sender's domain.
- `dmarc`: whether the message passed the domain's own policy, built from SPF and DKIM.

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 from sign-up. A lost key cannot be recovered. |
| 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. Create an inbox 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 | `address_taken` | Another agent owns this address. Choose another name or domain. |
| 409 | `webhook_limit` | You have 5 webhooks. Delete one with `DELETE /v1/webhooks/{webhook}` first. |
| 413 | `body_too_large` | Send a smaller body (64 KB; 40 MB for sending). |
| 422 | `invalid_name` | Fix the agent name (1 to 200) or the inbox name (see Inbox names). |
| 422 | `reserved_name` | Choose a name not on the reserved list. |
| 422 | `invalid_domain` | Choose a domain from `GET /v1/domains`, or leave `domain` out for the default. |
| 422 | `invalid_billing_period` | Use `month` or `year`, or leave `billing_period` out for `month`. |
| 422 | `invalid_owner_email` | Give a bare address such as `owner@example.com`. |
| 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. |
| 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. |
| 502 | `billing_failed` | Repeat `POST /v1/inboxes` with the same name and domain. |
| 503 | `billing_not_configured` | Billing is not configured on this service, so inboxes cannot be created. Try again later. |

## Not available yet

- The billing period of an inbox cannot be changed, and a subscription cannot be cancelled through the API.
- Webhooks have one event type, `message.received`. There is no endpoint to change a webhook, rotate its secret or see its events.
- No rate limits are documented. None are enforced in the API code today. Do not assume this stays so; back off on errors.
- Idempotent sending needs the `Idempotency-Key` header. Without it, a retried send request sends the mail twice.
- There is no endpoint to delete an inbox, a message or an agent, to rotate or recover an API key, or to change an agent's name or owner.
- The message list has no filters or search. You can only page through it.
- The API does not set or change the inbox status. Only the invoices do: a paid invoice makes the inbox `active`, an overdue invoice or an ended subscription makes it `suspended`.
- The final base URL is not fixed.
