> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dairo.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/domains/domains) on your account. The response carries the full address and a stable `id` — pass that `id` as `inboxId` when you [send](/sending/sending-email) from the inbox. Creating an inbox needs the `inboxes:write` scope.

<CodeGroup>
  ```bash title="cURL" theme={null}
  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" }'
  ```

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

  ```python title="Python" theme={null}
  inbox = dairo.inboxes.create(username="support", domain="yourapp.com")
  print(inbox.id, inbox.address)
  ```

  ```bash title="CLI" theme={null}
  dairo inbox create support --domain yourapp.com
  ```

  ```text title="MCP" theme={null}
  Tool: manage_inboxes   (scope inboxes:write, confirm required)
  Args: { "action": "create", "username": "support", "domain": "yourapp.com", "confirm": true }
  ```
</CodeGroup>

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

### Inbox fields

| Field                         | What it is                                                                          |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| `id`                          | Stable identifier — pass it as `inboxId` on sends and list filters.                 |
| `channel`                     | The [channel](/concepts/channels) 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`.

<CodeGroup>
  ```bash title="cURL" theme={null}
  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"
  ```

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

  ```python title="Python" theme={null}
  inboxes = dairo.inboxes.list()
  dairo.inboxes.update("support@yourapp.com", mode="receive_only")
  dairo.inboxes.delete("support@yourapp.com")
  ```

  ```bash title="CLI" theme={null}
  dairo inbox list
  dairo inbox delete support@yourapp.com
  ```
</CodeGroup>

## 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](/agent-first/agent-patterns) page covers this in depth.
* **Beyond email.** Inboxes aren't email-only: connecting a bot creates a [Telegram](/channels/telegram) inbox that sends and receives through the same message model.

## Next steps

* [Messages & threads](/receiving/messages-and-threads) — read what arrives and reply in the conversation.
* [Extract structured data](/receiving/structured-inboxes) — turn incoming mail into typed fields instead of raw text.
* [Wait for one-time codes](/receiving/verification-waits) — catch a sign-up or login code the moment it lands.