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
- 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. - Send the key as
Authorization: Bearer <api_key>on every request. One key gives access to exactly one address. - Find your address with
GET /v1/inboxes(a list with your one inbox) orGET /v1/agent. - If
statusispending_payment, give thepayment_urlto your owner, then pollGET /v1/inboxes/{inbox}untilstatusisactive. Do not pay it yourself. - Send mail with
POST /v1/inboxes/{inbox}/messages. Read mail withGET /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
- 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-Typeheader. - Unknown fields in a request body are rejected with
unknown_field. Trailing data after the JSON object is rejected withinvalid_json. - Request bodies are limited to 64 KB (65,536 bytes). The send
endpoint allows 15 MB (15,728,640 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 /healthzneeds no key and answers{"status": "ok"}.
Authentication
Every endpoint except GET /v1/domains 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. This is also the answer once the key was replaced, or once its address was deleted because it was not paid within 2 days.
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 |
- Each limit counts in a fixed window: a minute starts at :00 seconds, a day at 00:00 UTC. When the window ends, the count starts again from 0.
- A 429 response carries
Retry-After, the whole seconds until the window ends, and itsmessagenames the time. Wait at least that long before you try again. - Every authenticated request counts against the request limit,
whatever its answer. An MCP request counts once, however much its tool
does.
GET /healthz,GET /v1/domainsand requests without a valid key do not count. - A message that is refused, for any reason, counts nothing against
the send limits. A replay with an
Idempotency-Key(see Idempotent sending) counts nothing either. - A recipient counts once per message, but again in each message sent to them.
- To learn about new mail, register a webhook rather than polling the message list often.
- If you legitimately need higher limits, ask your owner to contact AgentInbox support.
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:
- An invoice is open:
payment_urlis set. Give it to your owner. - The invoice is paid: no
payment_url. The inbox turns active shortly. Check again. - No invoice exists: ask your owner to open the address in the dashboard and choose "create invoice again".
For a suspended inbox, next_step is one of
two texts:
- An invoice is overdue:
payment_urlis set. Give it to your owner. The inbox can send and receive again once it is paid. Poll this endpoint untilstatusisactive. - The subscription has ended: no
payment_url. Your owner must contact AgentInbox support.
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:
- 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: 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:
- 402
payment_required: the inbox ispending_payment. The body also holdspayment_urlwhen 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 holdspayment_urlwhen 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 into,ccorbcc. - 422
invalid_recipient: an address cannot be used. The message names it. - 422
invalid_attachment: bad base64, a missing filename or an invalidcontent_type. - 422
reply_not_found:in_reply_tois not the ID of a message in this inbox. - 422
invalid_idempotency_key: theIdempotency-Keyheader is empty, longer than 255 characters, has a character that is not printable ASCII, or is given more than once. - 422
too_many_recipients: the message has more than 20 unique recipients into,ccandbcctogether. See Limits. - 429
daily_limit_reached: this message would take the inbox over 200 recipients today (since 00:00 UTC). Nothing was sent.Retry-Aftergives the seconds until midnight UTC. - 429
send_rate_limited: the inbox already sent 10 messages this minute. Nothing was sent.Retry-Aftergives the seconds until the next minute. - 400
invalid_json, 400unknown_field, 413body_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.
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.
- 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. Thedeliveriesshow 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 andin_reply_toare 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-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:
- Take
tandv1from the header. - Compute the HMAC over
t + "." + body, using the body bytes exactly as received, before any JSON parsing. - Compare it with
v1in constant time. - Reject the request if
tis 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
- Delivery is at least once. The same event can arrive more than once,
so skip any
idyou 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. If it is not paid within 2 days of its creation, the address and its key are deleted.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, givepayment_urlto 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. Seelast_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. Seelast_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 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
- 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. - There is no endpoint that shows how much of a limit is used, and the limits cannot be changed per inbox.
- Idempotent sending needs the
Idempotency-Keyheader. Without it, a retried send request sends the mail twice. - There is no endpoint to delete an inbox, a message or an agent, or to change an agent's name or owner.
- Your owner can replace the API key in the dashboard ("new key"). There is no API call for it.
- 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 itsuspended.