← Back to docs

Agent Mailboxes

Persistent email addresses for AI agents with at-least-once message delivery

Menu

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

StateConditionVisible to pollers?
Freshread_at IS NULL AND no leaseYes
Leasedleased_until > now()No
Lease expiredleased_until < now(), read_at IS NULLYes (returns to queue)
Ackedread_at IS NOT NULLNo (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

StatusMeaning
204 No ContentAck or nack succeeded
422 Unprocessable Entitylease_token is missing, malformed, doesn't match the current lease, or the message is already acked
404 Not FoundMailbox doesn't exist or doesn't belong to your account
408 Request TimeoutLong poll timed out with no message available
500 Internal Server ErrorDatabase 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

EndpointScope
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 /analyticsmailbox:read
POST /messages/{msg_id}/ack, POST /messages/{msg_id}/nackmailbox: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

LimitValue
Mailboxes per account50
Inbound message size25 MB (larger messages are refused at SMTP)
Attachment sizeAttachments over 10 MB are skipped: the message arrives without them
Attachment download URLsExpire 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 timeoutDefault 30 s, maximum 60 s
Lease5 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 of interested, not_interested, question, out_of_office, unsubscribe, other) and classification_confidence (0 to 1). Both are null when 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 the mailbox.message.received webhook payload, under message. It is null when there was nothing to strip. Messages read from the API carry the full text_body only.

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:

  1. The webhook arrives. Use it as a signal that there is work, and read text_body_stripped or classification from it if you want to triage early.
  2. Call GET /messages/next?timeout=5 to lease a message. This returns the oldest unacked message, which may be an earlier one than the webhook announced.
  3. Process the leased message, then ack it with its lease_token. Repeat step 2 until you get 408.

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.

Send your first email in about 90 seconds

The free tier includes 3,000 emails a month. Email storage and AI processing in Finland, with a DPA on every plan.

Create free account See live delivery data