Create or return an inbox

Endpoint

POST https://api.dairo.app/v1/inboxes

Creates an inbox at username@domain and returns the created inbox object. username (the local part) and domain are both required; domain must be the included dairo.app or a domain on your account that is verified — a pending domain is refused with a 422 (invalid_domain), see verify a domain. The local part accepts up to 64 characters of lowercase letters, digits, dots, underscores, and hyphens, and may not start or end with ., _, or -. agent defaults to Inbox Agent, and mode defaults to receive_send (the alternatives are send_only and receive_only). The call is idempotent on the address: re-creating an inbox you already own returns the existing one unchanged, while an address held by another account is refused with a 409, so a retry is safe without an Idempotency-Key. An unknown mode is a 400, and a key restricted to specific inboxes cannot create inboxes (403). Creating an inbox requires the inboxes:write scope, counts against your plan's inbox limit (a 429 once reached), and is rate-limited to 50 create calls per hour.

Scope: inboxes:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

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

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Optional idempotency key for safe retries of side-effecting operations. (max length 128)

Body

Required, application/json: CreateInboxRequest.

Field	Type	Required	Description
`username`	string	yes
`localPart`	string	no
`domain`	string	yes
`agent`	string	no	(default `"Inbox Agent"`)
`mode`	`"receive_send"`, `"send_only"`, `"receive_only"`	no	(default `"receive_send"`)

Response

201 Created. Body: application/json, Inbox.

Field	Type	Required	Description
`object`	`"inbox"`	yes
`id`	string (uuid)	yes
`address`	string (email) or null	yes
`localPart`	string or null	yes
`domain`	string or null	yes
`domainStatus`	`"pending"`, `"verified"`, `"failed"`, `null`	no
`agent`	string	no
`mode`	`"receive_send"`, `"send_only"`, `"receive_only"`	yes
`status`	`"active"`, `"paused"`, `"deleted"`	yes
`createdAt`	string (date-time) or null	no
`lastMessageAt`	string (date-time) or null	no
`channel`	`"email"`, `"a2a"`	yes	The channel this message transited: "email" (external, over SES) or "a2a" (internal Dairo-to-Dairo, which skips SES). Reserved future values (sms, whatsapp, …) are not yet wired.

201

{
  "object": "inbox",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "address": "person@example.com",
  "localPart": "string",
  "domain": "yourapp.com",
  "domainStatus": "pending",
  "agent": "string",
  "mode": "receive_send",
  "status": "active",
  "createdAt": "2026-10-19T09:30:00Z",
  "lastMessageAt": "2026-10-19T09:30:00Z",
  "channel": "email"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).