# `bird email mailboxes list`

## Usage

```bash
bird email mailboxes list [flags]
```

## Description

List the workspace's mailboxes as a cursor page, newest first. Search addresses and display names with q, or filter by exact address, state, or domain.

Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.

## Examples

```bash
bird email mailboxes list
bird email mailboxes list | jq -r '.data[].id'
bird email mailboxes list --limit 50 --starting-after <cursor>
```

## Options

#### Filters

| Name                | Description                                                                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--address`         | Filter to the mailbox with exactly this address.                                                                                                                                     |
| `--domain`          | Filter to mailboxes whose address is on this domain.                                                                                                                                 |
| `--include-deleted` | Include mailboxes deleted within their 30-day restore window. Defaults to false, so only active and suspended mailboxes are returned. Deleted mailboxes carry a non-null deleted_at. |
| `--q`               | Case-insensitive search matching the mailbox's address or display name (substring).                                                                                                  |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                                     |
| `--state`           | Filter by lifecycle state.                                                                                                                                                           |

#### Pagination

| Name               | Description                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ending-before`  | Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. |
| `--limit <n>`      | Maximum number of items to return per page.                                                                                                    |
| `--starting-after` | Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.  |

## Related

| Name                                                                          | Description                       |
| ----------------------------------------------------------------------------- | --------------------------------- |
| [`bird email mailboxes compose`](/docs/cli/reference/email-mailboxes-compose) | Send a new message from a mailbox |
| [`bird email mailboxes create`](/docs/cli/reference/email-mailboxes-create)   | Create a mailbox                  |
| [`bird email mailboxes delete`](/docs/cli/reference/email-mailboxes-delete)   | Delete a mailbox                  |
| [`bird email mailboxes get`](/docs/cli/reference/email-mailboxes-get)         | Get a mailbox                     |
| [`bird email mailboxes labels`](/docs/cli/reference/email-mailboxes-labels)   | List a mailbox's labels           |
| [`bird email mailboxes restore`](/docs/cli/reference/email-mailboxes-restore) | Restore a deleted mailbox         |
| [`bird email mailboxes resume`](/docs/cli/reference/email-mailboxes-resume)   | Resume a suspended mailbox        |
| [`bird email mailboxes stats`](/docs/cli/reference/email-mailboxes-stats)     | Mailbox email statistics          |
| [`bird email mailboxes update`](/docs/cli/reference/email-mailboxes-update)   | Update a mailbox                  |