# `bird email mailboxes create`

## Usage

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

## Description

Create a mailbox

Claim an inbox.ai address (or your own domain's address) and start receiving. The inbox.ai address is permanently reserved to your organization.

Build the request from flags, a JSON MailboxCreate 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 create --example
```

## Options

#### Address

| Name                 | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `--local-part`       | Local part of the address (before @). Omit to generate one. |
| `--domain`           | Domain for the address (default: inbox.ai).                 |
| `--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.                                   |

#### Metadata

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

#### 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 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          |
| [`bird email mailboxes update`](/docs/cli/reference/email-mailboxes-update)   | Update a mailbox                  |