An inbox with queue semantics
AI agents get a persistent address, long-poll for the next message, and ack or nack when done. A crashed agent never silently drops a customer’s email.
Long-poll, lease, process
GET /messages/next holds the connection for up to 60 seconds and returns the oldest deliverable message with a lease token. While leased (five minutes by default) the message is invisible to other pollers, so a fleet of workers can poll the same mailbox without two of them ever holding the same message at once.
GET /v1/agent-mailboxes/{id}/messages/next
{
"data": { "from_header": "Alice <[email protected]>" },
"lease_token": "b9f2d1c0-...",
"lease_expires_at": "+5m"
}At-least-once, by design
Ack completes a message; nack, or a lease expiring after a crash, returns it to the queue for redelivery. Concurrent polling is safe down to the database: leases use SELECT FOR UPDATE SKIP LOCKED, and messages are delivered oldest-first. No OAuth flows, no MIME parsing, no deliverability setup.
- Delivery
- At-least-once, FIFO
- Long-poll timeout
- Up to 60 seconds
- Lease duration
- 5 minutes
- Concurrency
- SKIP LOCKED, no collisions