Files
sentio/docs/building-agents.md
Truespar Team a234f8931d docs: describe the inbound webhook payload as it actually is
The README and the agent guide both said the payload arrives parsed,
with headers, bodies and attachments. It does not. InboundPayload in
crates/sentio-smtp-server/src/routing.rs is POSTed verbatim and carries
identity, envelope, spam_score/spam_action, llm_category/llm_summary,
threading, loop-guard headers, DSN parameters, and raw_eml_key.

No bodies. No attachments. Anyone writing a handler from the old text
would have gone looking for a body field and found nothing, which is the
worst kind of documentation error: confidently wrong about the first
thing a reader touches.

Both pages now show the real shape and point at GET
/v1/messages/{id}/raw and /attachments for the content, and say why the
split exists - a webhook that stays small regardless of a 25 MB
attachment, and a handler that only needs the spam verdict never moving
the body at all.

Two more details taken from the code rather than assumed:

  - Route matching is exact, domain, regex or catch_all; first match
    wins, and a regex that fails to compile is logged and skipped rather
    than failing the delivery.
  - Retry classification is 2xx delivered, 5xx/408/429 transient, any
    other 4xx permanent, network errors transient - with retries
    scheduled through the queue so they survive a restart. The
    consequence worth stating for agent authors is that a handler
    blocking on a model will time out, be classified transient, and earn
    a duplicate.

The capabilities table said "parsed message data" too; corrected.
2026-08-23 23:52:46 +02:00

8.4 KiB

Building agents on Sentio

How to run an email-native agent, or a platform of them, on top of Sentio. The patterns here come from operating this in production; the ordering follows the mistakes that are expensive to fix later.

The two webhook streams

Sentio delivers two different things over HTTP, and treating them as one is the most common early mistake.

Configured via Fires when Auth
Inbound routes POST /v1/tenants/{id}/inbound-routes Mail arrives for a matching recipient Admin-scoped key
Event webhooks POST /v1/webhooks A message changes state: delivered, bounced, deferred, dropped, opened, clicked, unsubscribed Per-tenant key

An agent needs the first to receive mail and the second to learn whether its own replies landed. The two use different API keys: inbound routes are administered per tenant by an operator key, while /v1/webhooks is scoped to the calling tenant. Plan for both credentials from the start.

Addressing

Give each agent a stable address on a domain you control:

<agent-slug>@agents.example.com

Three rules worth adopting before you have users:

  • Globally unique, not unique-per-tenant. Two tenants that both want support@ will collide the moment you use one shared domain.
  • Append-only, never reused. When an agent is deleted, retire the slug and leave it retired. Replies to a months-old thread still arrive, and handing that address to a different tenant leaks one customer's mail to another.
  • Allocate at creation, not on first send, so the address exists before anyone is told about it.

A single match_type: "domain" route over the whole domain is usually better than one route per agent: one route to keep healthy instead of thousands, and new agents work the moment their slug is allocated. Resolve the slug to an agent in your own handler.

Receiving a message

Point the route at one endpoint and resolve the agent from the recipient:

curl -X POST "$API/v1/tenants/$TENANT/inbound-routes" \
  -H "Authorization: Bearer $ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{
    "match_type": "domain",
    "pattern": "agents.example.com",
    "webhook_url": "https://your-platform.example.com/hooks/inbound",
    "llm_classify": true,
    "priority": 100
  }'

The payload is metadata, not content. It carries the identity of the message (message_id, tenant_id, envelope_from, envelope_to), the verdicts (spam_score, spam_action, and llm_category / llm_summary when classification ran), threading (in_reply_to, references), the loop guards (auto_submitted, list_id, precedence), DSN parameters, and raw_eml_key.

There are no bodies and no attachments in it. Fetch those only when you need them:

GET /v1/messages/{message_id}/raw
GET /v1/messages/{message_id}/attachments

For an agent that split is a feature rather than an inconvenience. Use the verdicts as an intake gate before you spend a single token - drop or quarantine junk on the metadata alone and never move the body at all. Check the loop guards too: replying to something carrying auto_submitted or a list_id is how an agent ends up in a mail loop with another robot.

Setting llm_classify: true asks Sentio to classify borderline mail for you, which is worth it on a catch-all route where anything can arrive.

Answer fast and do the work asynchronously: return 2xx once the message is durably enqueued on your side, not once the agent has finished thinking. How your response is read:

Response Treated as
2xx Delivered
5xx, 408, 429 Transient - retried
Any other 4xx Permanent - not retried
Connection error or timeout Transient - retried

Retries are scheduled through the queue rather than held in memory, so they survive a restart of the server. The practical consequence: a handler that blocks while a model runs will time out, be classified transient, and earn a duplicate delivery - so make your processing idempotent on message_id.

Replying as the agent

Send from the agent's own address and thread the reply:

curl -X POST "$API/v1/messages/send" \
  -H "Authorization: Bearer $TENANT_KEY" -H 'Content-Type: application/json' \
  -d '{
    "from": "support-agent@agents.example.com",
    "to": ["customer@example.net"],
    "subject": "Re: Order #1234",
    "text": "...",
    "in_reply_to": "<the-inbound-message-id>",
    "references": ["<the-inbound-message-id>"]
  }'

in_reply_to is what makes Gmail, Outlook, and Apple Mail file the reply into the existing conversation instead of starting a new one. Build references by taking the parent's References and appending the parent's Message-ID.

The reply is DKIM-signed with the tenant's key, so it authenticates as their domain rather than yours.

Treat the message body as hostile

This is the part with no equivalent in a normal webhook integration: anyone in the world can send text to your agent. An inbound body is untrusted input that will be placed in a model's context.

  • Keep the body as data, never as instructions. Do not concatenate it into a system prompt.
  • Bound the blast radius. An agent acting on mail should not hold credentials or tools whose misuse you could not tolerate a stranger triggering.
  • Put a human in the loop for irreversible actions - refunds, account changes, anything outward-facing.
  • Constrain the recipients an agent may reply to. Replying only to the inbound sender prevents a crafted message from turning your agent into a relay.
  • Rate-limit per sender and per tenant, so one adversary cannot exhaust a tenant's budget.

Escalating to a human

An agent that cannot answer should hand off rather than guess. Set forward_to on the mailbox and inbound mail is forwarded to real people as well, with From: rewritten to the mailbox and re-signed with that domain's DKIM key so it still passes DMARC after the hop, and the original sender preserved in Reply-To: so a human reply goes back to the right place. Make sure the domain has an active DKIM key, or the forward goes out unsigned.

This is also the safest way to start: point a new agent's mailbox at a human inbox, watch what actually arrives for a week, and only then let the agent answer on its own.

Knowing whether the reply landed

Subscribe to lifecycle events so the agent learns the outcome of its own send:

curl -X POST "$API/v1/webhooks" \
  -H "Authorization: Bearer $TENANT_KEY" -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-platform.example.com/hooks/events",
    "event_types": ["delivered","bounced","dropped","deferred","opened","clicked","unsubscribed"]
  }'

Every dispatch carries four headers:

X-Sentio-Event:     delivered
X-Sentio-Timestamp: 1787513589
X-Sentio-Nonce:     <random>
X-Sentio-Signature: <hex hmac-sha256>

The signature is HMAC-SHA256 over "{timestamp}.{nonce}." concatenated with the raw request body, hex-encoded, keyed by the webhook's signing secret. Verify it against the raw bytes before any JSON parsing, use a constant-time comparison, and reject timestamps outside a tolerance window - the nonce and timestamp are what stop a captured request being replayed. Skip this and your events endpoint is an unauthenticated write path into your platform.

bounced and dropped deserve product behaviour, not just a log line: a hard bounce means that address is gone, and Sentio has already added it to the tenant's suppression list. An agent that keeps composing replies to a dead address wastes tokens and reputation.

Multi-tenant checklist

Running many customers' agents on one deployment:

  • One Sentio tenant per customer, so reputation, rate limits, suppression lists, and Bayesian spam profiles stay separate.
  • A per-tenant API key, never the bootstrap key.
  • Their own sending domain and DKIM key, so mail authenticates as them.
  • dedicated tier plus an IP pool for anyone whose volume justifies it, with a warmup schedule rather than full volume on day one.
  • Per-tenant rate limits, so one noisy customer cannot spend another's reputation.

Testing without sending real mail

docker-compose.test.yml enables [delivery.relay], which bypasses MX resolution so every outbound message goes to a local sink instead of the internet, and the fixtures use the reserved .test TLD. Point your integration tests at that stack and assert against the sink's API. See testing.md.