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

# Mailboxes

> Create and manage project mailboxes that route email into rooms and queues.

Mailboxes are project-level email addresses that route inbound mail into rooms. They belong at the project level because the address belongs to the project, even though the work is delivered to a queue in a specific room.

Use mailboxes when an agent listens on a `mail:` channel, or when you want inbound email to land in a queue that something in the room already consumes.

## Create a mailbox

```bash theme={null}
meshagent mailbox create \
  --address support@mail.meshagent.com \
  --room customer-support \
  --queue support-inbox
```

This creates a project mailbox and routes messages sent to `support@mail.meshagent.com` into the `support-inbox` queue in the `customer-support` room.

## Inspect and manage mailboxes

```bash theme={null}
meshagent mailbox list
meshagent mailbox get support@mail.meshagent.com
meshagent mailbox update support@mail.meshagent.com --queue escalations
meshagent mailbox delete support@mail.meshagent.com
```

## Inspect outbound delivery status

When Mailgun delivery tracking is enabled for the deployment, inspect each
recipient's current status and provider event timeline:

```bash theme={null}
meshagent mailbox deliveries support@mail.meshagent.com
meshagent mailbox delivery support@mail.meshagent.com DELIVERY_ID
meshagent mailbox delivery-events support@mail.meshagent.com DELIVERY_ID
```

The delivery list is newest submission first. A submission with multiple
recipients has one delivery row per recipient because their outcomes and retry
timelines can differ. Use `--status`, `--recipient`, or `--message-id` to narrow
the list, and use `--output json` when calling the commands from a script:

```bash theme={null}
meshagent mailbox deliveries support@mail.meshagent.com \
  --status deferred \
  --recipient example.com \
  --output json

meshagent mailbox delivery-events support@mail.meshagent.com DELIVERY_ID \
  --count 100 \
  --offset 0 \
  --output json
```

### Delivery statuses and events

A delivery is the current rollup for one recipient. Its `status` is one of:

| Status      | Meaning                                                   |
| ----------- | --------------------------------------------------------- |
| `accepted`  | The provider accepted the message for delivery.           |
| `deferred`  | A delivery attempt failed temporarily and may be retried. |
| `delivered` | The provider reported successful delivery.                |
| `failed`    | The provider reported a permanent delivery failure.       |

The delivery also contains the latest provider details, including
`attempt_count`, SMTP response codes, failure reason and description, MX host,
and TLS and certificate-verification results when the provider supplies them.

Delivery events are the chronological history behind that current status. The
API normalizes provider notifications into these event types:

| Event type         | Resulting delivery status |
| ------------------ | ------------------------- |
| `accepted`         | `accepted`                |
| `temporary_failed` | `deferred`                |
| `delivered`        | `delivered`               |
| `permanent_failed` | `failed`                  |

Each event includes `occurred_at` and `received_at`, its resulting `status`, and
the provider and provider event ID. When available, it also includes the
attempt number, SMTP and enhanced SMTP codes, reason, description, MX host,
TLS use, and certificate-verification result. Events are returned oldest first,
ordered by `occurred_at` and then event ID.

In Studio, open the mailbox options menu and select **Deliveries...**. Select a
delivery row to open its event timeline.

## Permissions

* To create, update, or delete a mailbox for a room, you need permission to administer that room.
* To list mailboxes across the whole project, you need developer access.
* To read delivery status as a user, you need the OAuth scope `mailboxes:read`
  and the project `mailbox_inventory` relation. Room membership and room read
  access do not grant delivery visibility. Project API keys retain project-wide
  access.

## Where to manage mailboxes

* Use [MeshAgent Studio](../interfaces/meshagent_studio) for the main UI flow.
* Use the CLI when you want quick setup or scripting.
* Use the [REST API](../rest_api/overview) when you need programmatic mailbox management.

## Related pages

* [Feeds](./feeds)
* [Process Agents Overview](../agents/process/overview)
* [Queue API](../room_api/queue)
* [Quickstart](../introduction/cli_quickstart)
* [REST API](../rest_api/overview)