Overview
Agent mailboxes give AI agents their own email identity on inbound.euromail.dev (or your verified domain). Zero MIME parsing, zero OAuth, zero deliverability setup. The agent gets an address, long-polls for incoming messages, processes them, and acknowledges. If the agent crashes mid-processing, the message automatically returns to the queue.
This guide focuses on the lease / ack / nack delivery model. For the full feature set (threads, search, labels, auto-responder, reply, attachments, contacts, analytics), see the API reference.
Quick Start
1. Create a mailbox
curl -X POST https://api.euromail.dev/v1/agent-mailboxes \
-H "Authorization: Bearer em_live_..." \
-H "Content-Type: application/json" \
-d '{ "display_name": "Support Agent" }'
Response:
{
"data": {
"id": "1f4e...",
"address": "[email protected]",
"display_name": "Support Agent",
"created_at": "2026-04-14T10:00:00Z"
}
}
The agent can now receive email at [email protected]. Pass a custom local_part in the create request if you want a specific address like [email protected].
To use an address on your own domain, pass its domain_id when you create the mailbox, point the domain's MX records at EuroMail, as described in Inbound Email: Add MX Records, and turn on inbound for the domain in the dashboard first. Without those records, mail for that address never reaches the mailbox.
2. Wait for the next message
GET /messages/next blocks until a message arrives or the timeout expires (max 60 s). On success, it leases the message (hides it from other pollers for 5 minutes) and returns a lease_token you'll need to ack or nack.
curl -X GET "https://api.euromail.dev/v1/agent-mailboxes/{id}/messages/next?timeout=30" \
-H "Authorization: Bearer em_live_..."
Success response (200):
{
"data": {
"id": "msg_uuid",
"mail_from": "[email protected]",
"from_header": "Alice <[email protected]>",
"subject": "Help with my order",
"text_body": "Hi, I need to change...",
"html_body": "<p>Hi, I need to change...</p>",
"classification": "question",
"classification_confidence": 0.94,
"created_at": "2026-04-14T10:01:23Z"
},
"lease_token": "b9f2d1c0-...",
"lease_expires_at": "2026-04-14T10:06:23Z"
}
The response shown is trimmed. The full message also carries thread, label, attachment and sender-check fields.
Timeout response (408 Request Timeout): the standard error body with code NO_MESSAGE. No message arrived before the timeout, or another poller leased it first. Send the request again.
The key needs the mailbox:read scope to poll, and mailbox:write to ack or nack (see Required Scopes).
3. Ack when done
After processing the message successfully, acknowledge it so it won't be redelivered:
curl -X POST https://api.euromail.dev/v1/agent-mailboxes/{id}/messages/{msg_id}/ack \
-H "Authorization: Bearer em_live_..." \
-H "Content-Type: application/json" \
-d '{ "lease_token": "b9f2d1c0-..." }'
Response: 204 No Content. Ack is idempotent. Re-acking an already-acked message returns 204 too.
4. Nack to retry
If processing fails (AI rate limit, transient error, bug), return the message to the queue so another attempt can pick it up:
curl -X POST https://api.euromail.dev/v1/agent-mailboxes/{id}/messages/{msg_id}/nack \
-H "Authorization: Bearer em_live_..." \
-H "Content-Type: application/json" \
-d '{ "lease_token": "b9f2d1c0-..." }'
Response: 204 No Content. The message becomes immediately deliverable to the next GET /messages/next call.
The Lease Model
EuroMail agent mailboxes implement at-least-once delivery. Every message you process will be delivered at least once, and may be delivered more than once if your agent crashes before acking. Your handler should be idempotent.
Why not just auto-ack on delivery?
The obvious alternative (mark the message as read the moment GET /messages/next returns it) would lose messages if the agent crashed while processing. That's the classic "at-most-once" trap: a single network hiccup, OOM kill, or LLM API timeout silently drops the customer's email.
The lease model trades theoretical duplicates for zero silent loss. For agents that reply to humans, this is almost always the right trade.
Lease lifetime
| State | Condition | Visible to pollers? |
|---|---|---|
| Fresh | read_at IS NULL AND no lease | Yes |
| Leased | leased_until > now() | No |
| Lease expired | leased_until < now(), read_at IS NULL | Yes (returns to queue) |
| Acked | read_at IS NOT NULL | No (permanently) |
The lease is 5 minutes and cannot be extended or renewed. If your agent's processing can take longer than that, copy the message into your own durable queue, ack it, and do the slow work from there. Otherwise the lease expires mid-work and the message is handed to another poller.
Handling duplicates
Because leases can expire (e.g., long-running LLM call + slow recovery), the same message can be delivered twice. Defend against this with an idempotency key derived from the message ID:
processed_ids = set() # or Redis, or a DB table
def handle(msg, lease_token):
if msg["id"] in processed_ids:
ack(msg["id"], lease_token) # already did the work, just ack
return
reply = llm.generate_reply(msg["text_body"])
send_reply(reply)
processed_ids.add(msg["id"])
ack(msg["id"], lease_token)Multiple Workers
The lease query uses PostgreSQL SELECT FOR UPDATE SKIP LOCKED, so multiple worker processes can poll the same mailbox concurrently without stepping on each other. Each poller gets a different message (or times out if no more work is available).
This lets you horizontally scale by running N worker pods. Each pod runs the same long-poll loop and the database hands out one message at a time.
Listing and Browsing
GET /messages returns messages without acquiring a lease. Useful for dashboards, history, and debugging:
# All messages (most recent first)
curl "https://api.euromail.dev/v1/agent-mailboxes/{id}/messages?status=all"
# Only unread (same ordering as the queue)
curl "https://api.euromail.dev/v1/agent-mailboxes/{id}/messages?status=unread"
# Only already-acked
curl "https://api.euromail.dev/v1/agent-mailboxes/{id}/messages?status=read"
status=unread includes currently-leased messages (they still have read_at = NULL), so don't use this endpoint to decide what to process next. Always call GET /messages/next for that.
Error Responses
| Status | Meaning |
|---|---|
204 No Content | Ack or nack succeeded |
422 Unprocessable Entity | lease_token is missing, malformed, doesn't match the current lease, or the message is already acked |
404 Not Found | Mailbox doesn't exist or doesn't belong to your account |
408 Request Timeout | Long poll timed out with no message available |
500 Internal Server Error | Database or Redis failure; retry with exponential backoff |
A common bug is re-acking a message after the lease has expired and another agent has already re-leased it. In that case your lease_token no longer matches the current one. You'll get a 422. Treat this as "somebody else is processing it now, move on."
Required Scopes
| Endpoint | Scope |
|---|---|
GET /agent-mailboxes, GET /agent-mailboxes/{id}, GET /messages, GET /messages/next, GET /messages/search, GET /messages/{msg_id}/attachments, GET /threads, GET /threads/{thread_id}, GET /contacts, GET /analytics | mailbox:read |
POST /messages/{msg_id}/ack, POST /messages/{msg_id}/nack | mailbox:write |
POST /messages/{msg_id}/reply, POST /threads/{thread_id}/reply, POST /messages (send) | mailbox:write |
PUT /messages/{msg_id}/labels, DELETE /messages/{msg_id} | mailbox:write |
POST /agent-mailboxes (create) | mailbox:write |
PATCH /agent-mailboxes/{id}, PATCH /auto-responder, DELETE /agent-mailboxes/{id} | mailbox:admin |
An agent that works through the queue needs mailbox:read and mailbox:write: with mailbox:read alone it can lease messages but every ack fails with 403, so each message comes back after its lease runs out. Never give an agent mailbox:admin unless it has to change the auto-responder or a mailbox's settings, or delete mailboxes.
Limits
| Limit | Value |
|---|---|
| Mailboxes per account | 50 |
| Inbound message size | 25 MB (larger messages are refused at SMTP) |
| Attachment size | Attachments over 10 MB are skipped: the message arrives without them |
| Attachment download URLs | Expire after 1 hour; request new ones from GET /messages/{msg_id}/attachments |
| Outbound sends (replies and new messages) | 30 per minute per mailbox |
| Long-poll timeout | Default 30 s, maximum 60 s |
| Lease | 5 minutes, fixed |
Keeping spam out of your webhook
Every received message carries a spam verdict (see the spam object in the webhook payload above). To stop the mailbox.message.received webhook for messages judged spam, turn on skip_spam_webhooks:
curl -X PATCH https://api.euromail.dev/v1/agent-mailboxes/{id} \
-H "Authorization: Bearer em_live_..." \
-H "Content-Type: application/json" \
-d '{"skip_spam_webhooks": true}'
The messages still arrive in the mailbox and in the lease queue, so an agent reading the queue sees them, with spam_verdict set. Only the webhook is skipped. Messages that are only suspect, or that couldn't be checked, are still sent. In the dashboard the same switch is under Integration details on the mailbox page.
Quote stripping and classification
- Classification is on the message itself, wherever you read it:
classification(one ofinterested,not_interested,question,out_of_office,unsubscribe,other) andclassification_confidence(0 to 1). Both arenullwhen classification is not set up for the account or has not finished. text_body_stripped(the reply without the quoted earlier conversation) is only in themailbox.message.receivedwebhook payload, undermessage. It isnullwhen there was nothing to strip. Messages read from the API carry the fulltext_bodyonly.
The webhook payload also has classification as an object: { "label": ..., "confidence": ... }.
Common Patterns
Single-worker loop (Python)
import os, time, requests
API = "https://api.euromail.dev"
KEY = os.environ["EUROMAIL_API_KEY"]
MAILBOX_ID = os.environ["MAILBOX_ID"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
while True:
r = requests.get(f"{API}/v1/agent-mailboxes/{MAILBOX_ID}/messages/next?timeout=30",
headers=HEADERS, timeout=35)
if r.status_code == 408:
continue # no message, long-poll again
r.raise_for_status()
body = r.json()
msg = body["data"]
token = body["lease_token"]
try:
handle_message(msg)
except Exception as e:
# Return to queue for another attempt
requests.post(f"{API}/v1/agent-mailboxes/{MAILBOX_ID}/messages/{msg['id']}/nack",
headers=HEADERS, json={"lease_token": token})
raise
requests.post(f"{API}/v1/agent-mailboxes/{MAILBOX_ID}/messages/{msg['id']}/ack",
headers=HEADERS, json={"lease_token": token})Webhook-driven (no polling)
Register a webhook for the mailbox.message.received event type on the mailbox's account. The webhook fires in addition to the lease queue, not instead of it: the message still sits in the queue until something acks it. The webhook does not carry a lease token, so a webhook handler cannot ack directly. The pattern is:
- The webhook arrives. Use it as a signal that there is work, and read
text_body_strippedorclassificationfrom it if you want to triage early. - Call
GET /messages/next?timeout=5to lease a message. This returns the oldest unacked message, which may be an earlier one than the webhook announced. - Process the leased message, then ack it with its
lease_token. Repeat step 2 until you get408.
If you ignore the queue and only use webhooks, messages pile up there unacked; nothing breaks, but status=unread will never empty.
The payload includes an authentication object with the sender's SPF, DKIM and DMARC verdicts, e.g. "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" }. The values are the ones documented for the inbound-email webhook, and each is null if its check couldn't run. Use them to decide how much to trust a message before acting on it. The payload also carries a spam object, such as "spam": { "verdict": "suspect", "reasons": ["spf_softfail"] }, with the same values as on the inbound-email webhook. On a mailbox the content model that sets classification also judges spam, so reasons may also include content_spam. euromail's own auto-responder skips replies to SPF fail/softfail senders and to messages judged spam, to avoid backscatter.
Every message you read from the mailbox also shows how its sender checked out: spf_result, dkim_result and dmarc_result. It also names the server that delivered it, in sender_hostname, sender_hostname_status, sender_service, sender_helo, sender_country and sender_country_name. These mean the same as the authentication and sender fields of the inbound-email webhook. The spam verdict is there too, in spam_verdict and spam_reasons. Check them before an agent acts on a message. For example, you can hand anything with a dmarc_result of fail to a person instead. All of these fields are null on messages the mailbox sent and on messages received before these checks were recorded.
FAQ
Can I change or extend the lease? No. It is a fixed 5 minutes and there is no call to renew it. For longer work, move the message into your own queue and ack it first (see Lease lifetime).
What happens if I call /messages/next and never ack or nack?
The message becomes deliverable again once leased_until passes (5 minutes after the lease was acquired). The next poller will get it.
Can two agents process the same message at the same time?
No. Only one agent holds an active lease at a time, and SELECT FOR UPDATE SKIP LOCKED guarantees no race between concurrent pollers. Duplicates happen only when a lease expires and the message is redelivered.
Is the message ordering preserved?
Yes, GET /messages/next always returns the oldest deliverable message first (FIFO by created_at).
How do I delete a mailbox?
DELETE /v1/agent-mailboxes/{id}. Cascades to all messages and attachments. Requires mailbox:admin.