Inboxes

Create real email addresses on your domain that send mail and receive every reply as a structured message.

An inbox is a real email address on your domain — like support@yourapp.com — that sends mail and receives replies. Create one, hold on to its id, and every reply that lands arrives as a structured message you can read over the API.

Create an inbox

The username is the part before the @; the domain must be a domain you've verified on your account — a domain that is still pending is refused with a 422 and error code invalid_domain (param domain). The response carries the full address and a stable id — pass that id as inboxId when you send from the inbox. Creating an inbox needs the inboxes:write scope.

curl -X POST https://api.dairo.app/v1/inboxes \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "username": "support", "domain": "yourapp.com" }'

{
  "object": "inbox",
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "channel": "email",
  "address": "support@yourapp.com",
  "localPart": "support",
  "domain": "yourapp.com",
  "domainStatus": "verified",
  "agent": "Inbox Agent",
  "mode": "receive_send",
  "status": "active",
  "createdAt": "2026-06-12T10:00:00+00:00",
  "lastMessageAt": null
}

Creating an address that already exists on your account returns the existing inbox instead of failing, so a retried create is safe. An address owned by another account returns 409.

The username accepts lowercase letters, digits, dots, underscores, and hyphens — up to 64 characters — and can't start or end with a dot, underscore, or hyphen.

Every account includes the built-in dairo.app domain, so you can create an @dairo.app inbox and start receiving before you verify your own domain. A small set of reserved system addresses — notifications@, no-reply@, support@, and similar — is unavailable on it.

Inbox fields

Field	What it is
`id`	Stable identifier — pass it as `inboxId` on sends and list filters.
`channel`	The channel the inbox lives on — `email` here.
`address`	The full email address, e.g. `support@yourapp.com`.
`localPart`	The part before the `@`.
`domain`	The domain the inbox lives on.
`domainStatus`	That domain's verification state: `pending`, `verified`, or `failed`.
`agent`	The name of the agent the inbox is bound to. Defaults to `Inbox Agent`.
`mode`	Which directions the inbox handles: `receive_send`, `send_only`, or `receive_only`.
`status`	`active`, `paused`, or `deleted`.
`createdAt` / `lastMessageAt`	When the inbox was created, and when mail last moved through it.

Inbox modes

Set mode when you create the inbox, or change it later with a PATCH.

Mode	Behavior
`receive_send` (default)	Sends outbound mail and receives replies.
`send_only`	An outbound-only address — use it for senders that shouldn't take replies.
`receive_only`	Receives mail only. Sending from it is rejected.

List, update, and delete

Every inbox path accepts either the id or the full address. Reads use inboxes:read; writes use inboxes:write. PATCH updates agent, mode, or both — no delete-and-recreate to change one field. DELETE removes the inbox together with its threads and messages and returns 204; an inbox that is not on your account (or not one a restricted key is pinned to) is a 404.

curl https://api.dairo.app/v1/inboxes \
  -H "Authorization: Bearer $DAIRO_API_KEY"

curl -X PATCH https://api.dairo.app/v1/inboxes/support@yourapp.com \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "receive_only" }'

curl -X DELETE https://api.dairo.app/v1/inboxes/support@yourapp.com \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Patterns that work well

Role addresses. Names like support@, receipts@, and notifications@ keep conversational and transactional mail separated by purpose.
One domain, many inboxes. Verify a domain once, then create as many inboxes on it as you need. Every inbox inherits its domain's authenticated sending — there is no per-inbox setup.
One address per agent. Give each AI agent its own inbox — triage@yourapp.com, billing@yourapp.com — so each one only sees its own conversations. The agent patterns page covers this in depth.
Beyond email. Inboxes aren't email-only: connecting a bot creates a Telegram inbox that sends and receives through the same message model.

Next steps

Messages & threads — read what arrives and reply in the conversation.
Extract structured data — turn incoming mail into typed fields instead of raw text.
Wait for one-time codes — catch a sign-up or login code the moment it lands.