# molted mailboxes

Source: https://molted.email/docs/cli/mailboxes

Manage mailboxes

| Command | Description |
| - | - |
| [`molted mailboxes create`](#molted-mailboxes-create) | Create a new mailbox |
| [`molted mailboxes list`](#molted-mailboxes-list) | List all mailboxes |
| [`molted mailboxes get`](#molted-mailboxes-get) | Get a mailbox by ID |
| [`molted mailboxes set-default`](#molted-mailboxes-set-default) | Make a mailbox the default (used when a send names no mailbox) |
| [`molted mailboxes verify`](#molted-mailboxes-verify) | Verify and activate a provisioning mailbox |
| [`molted mailboxes update`](#molted-mailboxes-update) | Update a mailbox |
| [`molted mailboxes delete`](#molted-mailboxes-delete) | Delete a mailbox: archived for 14 days (a person can restore it from the dashboard), then deleted for good |
| [`molted mailboxes restore`](#molted-mailboxes-restore) | Restore a deleted mailbox inside its 14-day window, with its threads and the mail that arrived meanwhile (an agent key can restore only a mailbox an agent deleted) |
| [`molted mailboxes clone`](#molted-mailboxes-clone) | Clone a mailbox with its settings |
| [`molted mailboxes stats`](#molted-mailboxes-stats) | View usage stats for a mailbox |
| [`molted mailboxes reputation`](#molted-mailboxes-reputation) | View reputation stats for a mailbox |
| [`molted mailboxes reputation recalculate`](#molted-mailboxes-reputation-recalculate) | Force recalculation of mailbox reputation |
| [`molted mailboxes unpause`](#molted-mailboxes-unpause) | Unpause a paused mailbox |
| [`molted mailboxes autonomy`](#molted-mailboxes-autonomy) | View current autonomy level for a mailbox |
| [`molted mailboxes autonomy set`](#molted-mailboxes-autonomy-set) | Set the autonomy level for a mailbox |

## Agent context

Mailboxes are the sending identities for your tenant. Each email is sent from a mailbox address. A default mailbox is auto-created when you sign up.

### List your mailboxes

```bash
molted mailboxes list
# → [{ "id": "<uuid>", "address": "agent@yourdomain.com", "status": "active", "isDefault": true, ... }]
# isDefault marks the default mailbox: sends without --mailbox go out from it.
```

### Choose the default mailbox (needs a key with access to every mailbox)

```bash
molted mailboxes set-default <id>
# → the mailbox, with "isDefault": true. Only an active mailbox can be the default.
# If the default is paused or deleted, the oldest active mailbox is used instead.
```

### Create a mailbox on a verified domain

```bash
molted domains add yourdomain.com        # add the domain first
molted domains verify <domainId>         # verify DNS records
molted mailboxes create --address agent@yourdomain.com --display-name "My Agent"
```

### Verify and activate a provisioning mailbox

```bash
molted mailboxes verify <id>             # activate a provisioning mailbox
```

### Update mailbox settings

```bash
molted mailboxes update <id> --status paused          # pause sending from this mailbox
molted mailboxes update <id> --status active           # resume
molted mailboxes update <id> --catch-all               # receive mail for any unmatched address on this domain
molted mailboxes update <id> --no-catch-all            # disable catch-all
```

### Delete a mailbox (recoverable for 14 days)

```bash
molted mailboxes delete <id>
# → { "deleted": true, "archived": true, "purgeAfter": "<date>", ... }
# It stops sending and stops reaching agents at once. A person can restore it
# from the dashboard until purgeAfter; after that it is deleted for good.

molted mailboxes restore <id>             # undo a delete inside the 14 days
# An agent key can restore only a mailbox an agent deleted (a person's delete
# is 403 human_archive: a person restores it from the dashboard).
```

### Clone a mailbox with its settings

```bash
molted mailboxes clone <sourceId> --address clone@yourdomain.com
molted mailboxes clone <sourceId> --address clone@yourdomain.com --display-name "Clone"
# → copies autonomy level, config, folders and rules; catch-all is always off on
#   the clone, and a clone of a paused mailbox starts paused
```

### Usage stats

```bash
molted mailboxes stats <mailboxId>
molted mailboxes stats <mailboxId> --period 30d
# → {
#     "mailboxId": "<uuid>", "period": "7d",
#     "sends": { "total": 142, "period": 140 },
#     "inbound": { "period": 18 },
#     "deliverability": {
#       "delivered": 138, "bounced": 2, "complained": 0,
#       "openRate": 0.41, "clickRate": 0.09, ...
#     },
#     "suppressionCount": 1, "lastSendAt": "...", "dailySends": [...]
#   }
# Periods: 24h, 7d (default), 30d
# Note: sends.total is lifetime, sends.period is scoped to --period.
```

### Reputation

```bash
molted mailboxes reputation <mailboxId>
# → { "score": 100, "status": "healthy", "bounceRate": 0, "complaintRate": 0,
#     "totalSends": 0, "totalBounces": 0, "totalComplaints": 0,
#     "lastCalculatedAt": "2026-04-16T20:51:44.434Z", ... }
# score: 0-100 (100 is perfect), derived from bounce rate and complaints.
# status: healthy, warning or paused. The score itself never pauses anything:
# by default a mailbox is auto-paused at a 15% bounce rate (once it has 20+ sends
# in the last 30 days) or on complaints (1, or 0.3% of sends at higher volume).

molted mailboxes reputation recalculate <mailboxId>
# → force recalculation (5-minute cooldown between recalculations)
```

### Unpause

```bash
molted mailboxes unpause <mailboxId>
# → unpause a mailbox the reputation monitor paused, resetting its reputation
#   counters (400 if it is not reputation-paused)
```

### Autonomy level

```bash
molted mailboxes autonomy <mailboxId>
# → { "autonomyLevel": 3, "description": "Full auto - sends are executed without approval" }

molted mailboxes autonomy set <mailboxId> --level 2
# → set to first-contact approval
```

Levels:\
1 = Full approval (every send requires human approval) 2 = First-contact approval (first message to new recipient needs approval) 3 = Full auto (no approval needed)

### Key behaviors

- Default mailbox is used when `--mailbox` is omitted from send commands (the one you chose with set-default while it is active, else the oldest active one)
- Mailboxes on verified domains are auto-activated on creation
- Mailboxes on unverified domains start as "provisioning" — verify the domain first
- Pausing a mailbox blocks all sends from that address
- Catch-all routes any unmatched address on the domain to this mailbox (the domain must be verified with receiving enabled; not on the shared domain)
- Agents may tighten, never loosen: resuming a paused mailbox (`--status` active, unpause), raising autonomy, changing config.humanizer.style and turning a mailbox's humanizer on (config.humanizer.enabled) are human decisions; turning it off (\{"humanizer":\{"enabled":false}}) is not. So is turning catch-all on or off (`--catch-all`, `--no-catch-all`), any change to a mailbox's address, deleting a catch-all mailbox, and creating or cloning onto an address another mailbox's catch-all receives: each changes which email reaches a mailbox. A person makes them on the mailbox's page in the dashboard. Addresses ignore case: a mailbox onto a live one's case variant is 409 mailbox\_address\_taken. Depending on the account's human-gate mode the call goes through (with a notice in the warning period) or is refused (403 human\_decision\_required).

Related: [`molted domains`](https://molted.email/docs/cli/domains.md), [`molted send`](https://molted.email/docs/cli/send.md), [`molted threads`](https://molted.email/docs/cli/threads.md)

## Commands

### molted mailboxes create

Create a new mailbox

```bash
molted mailboxes create [options]
```

| Option | Description | Default |
| - | - | - |
| `--address <email>` | Email address for the mailbox (required) (required) | |
| `--display-name <name>` | Display name | |

### molted mailboxes list

List all mailboxes

```bash
molted mailboxes list
```

### molted mailboxes get

Get a mailbox by ID

```bash
molted mailboxes get <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Mailbox ID | yes |

### molted mailboxes set-default

Make a mailbox the default (used when a send names no mailbox)

```bash
molted mailboxes set-default <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Mailbox ID | yes |

### molted mailboxes verify

Verify and activate a provisioning mailbox

```bash
molted mailboxes verify <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Mailbox ID | yes |

### molted mailboxes update

Update a mailbox

```bash
molted mailboxes update [options] <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Mailbox ID | yes |

| Option | Description | Default |
| - | - | - |
| `--display-name <name>` | Display name | |
| `--status <status>` | Status (one of: active, paused) | |
| `--catch-all` | Enable catch-all | |
| `--no-catch-all` | Disable catch-all | |
| `--config <json>` | Configuration as JSON (a partial update: keys you leave out keep their stored value, nested objects merge, null clears a key) | |

### molted mailboxes delete

Delete a mailbox: archived for 14 days (a person can restore it from the dashboard), then deleted for good

```bash
molted mailboxes delete <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Mailbox ID | yes |

### molted mailboxes restore

Restore a deleted mailbox inside its 14-day window, with its threads and the mail that arrived meanwhile (an agent key can restore only a mailbox an agent deleted)

```bash
molted mailboxes restore <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Mailbox ID | yes |

### molted mailboxes clone

Clone a mailbox with its settings

```bash
molted mailboxes clone [options] <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Source mailbox ID to clone | yes |

| Option | Description | Default |
| - | - | - |
| `--address <email>` | Email address for the new mailbox (required) (required) | |
| `--display-name <name>` | Display name for the new mailbox | |

### molted mailboxes stats

View usage stats for a mailbox

```bash
molted mailboxes stats [options] <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | Mailbox ID | yes |

| Option | Description | Default |
| - | - | - |
| `--period <period>` | Time period: 24h, 7d, or 30d (default: 7d) | |

### molted mailboxes reputation

View reputation stats for a mailbox

```bash
molted mailboxes reputation <mailboxId>
```

| Argument | Description | Required |
| - | - | - |
| `<mailboxId>` | | yes |

### molted mailboxes reputation recalculate

Force recalculation of mailbox reputation

```bash
molted mailboxes reputation recalculate <mailboxId>
```

| Argument | Description | Required |
| - | - | - |
| `<mailboxId>` | | yes |

### molted mailboxes unpause

Unpause a paused mailbox

```bash
molted mailboxes unpause <mailboxId>
```

| Argument | Description | Required |
| - | - | - |
| `<mailboxId>` | | yes |

### molted mailboxes autonomy

View current autonomy level for a mailbox

```bash
molted mailboxes autonomy <mailboxId>
```

| Argument | Description | Required |
| - | - | - |
| `<mailboxId>` | | yes |

### molted mailboxes autonomy set

Set the autonomy level for a mailbox

```bash
molted mailboxes autonomy set [options] <mailboxId>
```

| Argument | Description | Required |
| - | - | - |
| `<mailboxId>` | | yes |

| Option | Description | Default |
| - | - | - |
| `--level <level>` | Autonomy level (1 = full approval, 2 = first-contact, 3 = full auto) (required; one of: 1, 2, 3) | |

See [CLI overview](https://molted.email/docs/cli.md) for global options, credentials and output format.
