Inboxes

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. 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" }'

const inbox = await dairo.inboxes.create({ username: "support", domain: "yourapp.com" });
console.log(inbox.id, inbox.address); // …  support@yourapp.com

inbox = dairo.inboxes.create(username="support", domain="yourapp.com")
print(inbox.id, inbox.address)

dairo inbox create support --domain yourapp.com

Tool: manage_inboxes   (scope inboxes:write, confirm required)
Args: { "action": "create", "username": "support", "domain": "yourapp.com", "confirm": true }

{
  "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 and returns 204.

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"

const { data: inboxes } = await dairo.inboxes.list();
await dairo.inboxes.update("support@yourapp.com", { mode: "receive_only" });
await dairo.inboxes.delete("support@yourapp.com");

inboxes = dairo.inboxes.list()
dairo.inboxes.update("support@yourapp.com", mode="receive_only")
dairo.inboxes.delete("support@yourapp.com")

dairo inbox list
dairo inbox delete support@yourapp.com

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.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Create an inbox

Inbox fields

Inbox modes

List, update, and delete

Patterns that work well

Next steps

​Create an inbox

​Inbox fields

​Inbox modes

​List, update, and delete

​Patterns that work well

​Next steps

Create an inbox

Inbox fields

Inbox modes

List, update, and delete

Patterns that work well

Next steps