# `bird email mailboxes update`

## Usage

```bash
bird email mailboxes update <mailbox-id> [flags]
```

## Description

Update a mailbox

Update the display name, reply-to, receive policy, retention, or metadata on a mailbox. Omitted
fields are left unchanged. To clear a nullable field (display-name, default-reply-to),
use curl or the API directly: PATCH /v1/email/mailboxes/{id} with {"field":null}. The CLI cannot
send an explicit null — flags omit the field rather than nulling it.

Build the request from flags, a JSON MailboxUpdate body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Examples

```bash
# print the body shape (no credentials needed)
bird email mailboxes update --example
```

## Options

#### Address

| Name                 | Description                                |
| -------------------- | ------------------------------------------ |
| `--display-name`     | Sender display name on outgoing mail.      |
| `--default-reply-to` | Default Reply-To address on outgoing mail. |

#### Behaviour

| Name               | Description                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `--receive-policy` | Which inbound mail to accept: open, replies_only, allowlist, or drop.                     |
| `--retention-tier` | How long to remember messages: 30d.                                                       |
| `--confirm`        | Required when lowering retention-tier, acknowledging that older messages will be deleted. |

#### Metadata

| Name         | Description                                                                       |
| ------------ | --------------------------------------------------------------------------------- |
| `--metadata` | Arbitrary JSON metadata object (up to 2 KB); replaces existing metadata entirely. |

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--response-schema` | Print the fields this command returns, then exit |

## 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 list`](/docs/cli/reference/email-mailboxes-list)       | List mailboxes                    |
| [`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          |