# inboxes

> Inboxes (an inbox id is its email address). The `machinemail inboxes` commands: arguments, flags, examples and the API routes they call.

Inboxes (an inbox id is its email address). Also spelled `inbox`.

| Command                                         | Summary                                               |
| ----------------------------------------------- | ----------------------------------------------------- |
| [`inboxes availability`](#inboxes-availability) | Check inbox availability                              |
| [`inboxes create`](#inboxes-create)             | Create inbox                                          |
| [`inboxes delete`](#inboxes-delete)             | Delete inbox                                          |
| [`inboxes export`](#inboxes-export)             | Export inbox                                          |
| [`inboxes get`](#inboxes-get)                   | Get inbox                                             |
| [`inboxes list`](#inboxes-list)                 | List inboxes                                          |
| [`inboxes new`](#inboxes-new)                   | Create an inbox and print its address (pipe-friendly) |
| [`inboxes search`](#inboxes-search)             | Search inboxes                                        |
| [`inboxes update`](#inboxes-update)             | Update inbox                                          |

Every command also takes the [global flags](/content/docs/cli/commands#global-flags/index.html).

## inboxes availability

Check inbox availability.

Whether username@domain can be created by this organization now. Never a 4xx for a bad name: reason says why it is not available.

Requires the inbox_read permission.

```bash
machinemail inboxes availability [flags]
```

#### Flags

| Field                     | Type           |   | Description   |
| ------------------------- | -------------- |---| ------------- |
| `--pod <pod-id>`         | `string`       |   | Only this pod. |
| `--username <value>`     | `string`       |   | Local part to check. |
| `--domain <domain>`      | `string`       |   | Domain to check. Defaults to the shared domain. |

#### Examples

```bash
machinemail inboxes availability
machinemail inboxes availability --pod pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`GET /v0/inboxes/availability`](/content/docs/reference/api/inboxes#check-inbox-availability/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/availability`](/content/docs/reference/api/inboxes#check-inbox-availability-in-pod/index.html) with `--pod`

## inboxes create

Create inbox.

--ephemeral without --ttl-seconds creates an inbox with a one hour TTL (3600 seconds).

An organization can have at most 1,000 inboxes on the shared domain; past that the API returns 403. Add your own domain for more. Inbox-scoped credentials cannot create inboxes (403).

A taken address returns 409, and so does a reserved one: role and brand names on the shared domain, and {slug}@ on the shared domain, which only the organization with that slug can create (agent- followed by 16 or more hex digits is reserved the same way).

Requires the inbox_create permission.

```bash
machinemail inboxes create [flags]
```

#### Flags

| Field                     | Type           |   | Description   |
| ------------------------- | -------------- |---| ------------- |
| `--pod <pod-id>`         | `string`       |   | Create it in this pod. |
| `--username <value>`     | `string`       |   | Local part of the address: a-z, 0-9 and . _ + -, 1 to 64 characters. Randomly generated if omitted. On the shared domain, a username equal to another organization's slug is reserved for that organization (409). |
| `--domain <domain>`      | `string`       |   | Domain of the address: a domain verified by this organization. Defaults to the shared domain. |
| `--display-name <value>` | `string`       |   | Display name: Display Name <username@domain.com>. |
| `--client-id <id>`      | `string`       |   | Idempotency key: a create with a --client-id already used in the organization returns that inbox with 200, or 409 when that inbox is outside the pod of the API key or route. |
| `--status`               | `active \| paused` |   | Whether the inbox sends and receives mail. paused stops both: sends return 403 (Inbox <inbox_id> is paused), and incoming mail is not stored; a message.rejected event with reason inbox_paused is emitted instead. Mail already in the inbox, its drafts and its API keys are kept. Set active to resume. |
| `--metadata <json>`      | `JSON`         |   | Custom key-value pairs attached to the inbox. |
| `--ephemeral`            | `boolean`      |   | true without --ttl-seconds creates an ephemeral inbox with a one hour TTL (3600 seconds). |
| `--ttl-seconds <n>`      | `integer \| null` |   | Creates an ephemeral inbox that expires --ttl-seconds after creation, extended by each inbound message. |
| `--import-source`        | `agentmail`    |   | Marks an inbox copied from another provider by an importer (machinemail import agentmail sets agentmail). The only effect: its inbox.created event is not delivered to webhooks or MCP subscribers, so they are not notified about an inbox that already existed elsewhere. The event is still recorded (GET /v0/events, the event stream), marked as an import in its payload, so the event log shows every import. Everything else about the create is unchanged. |
| `-d, --data <json|@file|->` | `string`   |   | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail inboxes create --username support-agent --display-name "Support agent"
machinemail inboxes create --ttl-seconds 3600   # ephemeral, expires in an hour
machinemail inboxes create --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail inboxes create --data @body.json
```

#### API

- [`POST /v0/inboxes`](/content/docs/reference/api/inboxes#create-inbox/index.html)
- [`POST /v0/pods/{pod_id}/inboxes`](/content/docs/reference/api/inboxes#create-inbox-in-pod/index.html) with `--pod`

## inboxes delete

Delete inbox.

Also: `machinemail inboxes rm`.

Deletes the inbox with its messages, attachments, threads and drafts. Inbox-scoped credentials cannot delete their own inbox (403).

Requires the inbox_delete permission.

```bash
machinemail inboxes delete <inbox-id> [flags]
```

#### Arguments

| Field         | Type     |   | Description                                     |
| ------------- | -------- |---| ----------------------------------------------- |
| `<inbox-id>`  | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). |

#### Flags

| Field             | Type           |   | Description    |
| ----------------- | -------------- |---| -------------- |
| `--pod <pod-id>` | `string`       |   | Use this pod's scoped route. |

#### Examples

```bash
machinemail inboxes delete agent@machinemail.dev
machinemail inboxes delete agent@machinemail.dev --pod pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`DELETE /v0/inboxes/{inbox_id}`](/content/docs/reference/api/inboxes#delete-inbox/index.html)
- [`DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}`](/content/docs/reference/api/inboxes#delete-inbox-in-pod/index.html) with `--pod`

## inboxes export

Export inbox.

Every message in the inbox, oldest first, streamed as an attachment named <inbox_id>.<format>.

Requires the message_read permission.

```bash
machinemail inboxes export <inbox-id> [flags]
```

#### Arguments

#### Flags

| Field                     | Type           |   | Description   |
| ------------------------- | -------------- |---| ------------- |
| `--pod <pod-id>`         | `string`       |   | Only this pod. |
| `--format`               | `mbox \| jsonl` |   | mbox: every message as raw MIME in one mbox file. jsonl: one Message JSON object per line. |
| `-o, --output <file|dir|->` | `string`   |   | Write the body to this file (a directory keeps the server's filename; - is stdout) and report the path. |

#### Examples

```bash
machinemail inboxes export agent@machinemail.dev
machinemail inboxes export agent@machinemail.dev --pod pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`GET /v0/inboxes/{inbox_id}/export`](/content/docs/reference/api/export#export-inbox/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}/export`](/content/docs/reference/api/export#export-inbox-in-pod/index.html) with `--pod`

## inboxes get

Get inbox.

Requires the inbox_read permission.

```bash
machinemail inboxes get <inbox-id> [flags]
```

#### Arguments

#### Flags

| Field             | Type           |   | Description    |
| ----------------- | -------------- |---| -------------- |
| `--pod <pod-id>` | `string`       |   | Only this pod. |

#### Examples

```bash
machinemail inboxes get agent@machinemail.dev
machinemail inboxes get agent@machinemail.dev --pod pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`GET /v0/inboxes/{inbox_id}`](/content/docs/reference/api/inboxes#get-inbox/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/{inbox_id}`](/content/docs/reference/api/inboxes#get-inbox-in-pod/index.html) with `--pod`

## inboxes list

List inboxes.

Also: `machinemail inboxes ls`.

Requires the inbox_read permission.

```bash
machinemail inboxes list [flags]
```

#### Flags

| Field                     | Type           |   | Description   |
| ------------------------- | -------------- |---| ------------- |
| `--pod <pod-id>`         | `string`       |   | Only this pod. |
| `--limit <n>`            | `integer`      |   | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>`   | `string`       |   | next_page_token from the previous page. |
| `--ascending`            | `boolean`      |   | Sort oldest first. |
| `--ephemeral`            | `boolean`      |   | Only ephemeral (true) or only permanent (false) inboxes. |
| `--all`                  | `boolean`      |   | Follow next_page_token and return every page. |

#### Examples

```bash
machinemail inboxes list
machinemail inboxes list --all --json | jq -r '.inboxes[].inbox_id'
machinemail inboxes list --pod pod_01m4fykg210000x6z8b6wc2rdx
```

#### API

- [`GET /v0/inboxes`](/content/docs/reference/api/inboxes#list-inboxes/index.html)
- [`GET /v0/pods/{pod_id}/inboxes`](/content/docs/reference/api/inboxes#list-inboxes-in-pod/index.html) with `--pod`

## inboxes new

Create an inbox and print its address (pipe-friendly).

Creates an inbox through POST /v0/inboxes. Without --username the address gets a random, hard-to-guess local part. --ephemeral or --ttl makes the inbox delete itself (with its mail) after the TTL, which each inbound message extends; --ephemeral alone means one hour. On a terminal it shows the inbox; piped it prints only the address, or the whole inbox with --json.

```bash
machinemail inboxes new [flags]
```

#### Flags

| Field                     | Type           |   | Description   |
| ------------------------- | -------------- |---| ------------- |
| `--username <name>`      | `string`       |   | Local part of the address (random when omitted). |
| `--domain <domain>`      | `string`       |   | Domain (default: the shared domain); must be a verified domain of yours. Default: `the shared domain`. |
| `--display-name <name>`  | `string`       |   | Display name for outgoing mail. |
| `--ephemeral`            | `boolean`      |   | Delete the inbox after a TTL (one hour unless --ttl). |
| `--ttl <duration>`       | `string`       |   | Lifetime after creation and after each inbound message: 600, 10m, 2h, 1d. |
| `--pod <pod-id>`         | `string`       |   | Pod to create the inbox in. |
| `--client-id <id>`       | `string`       |   | Idempotency key: the same client id returns the same inbox. |
| `--metadata <json>`      | `JSON`         |   | JSON object stored with the inbox. |

#### Examples

```bash
machinemail inbox new --ephemeral
ADDR=$(machinemail inbox new --ttl 30m)
machinemail inbox new --username support --display-name "Support Agent" --json
```

## inboxes search

Search inboxes.

Inboxes whose address or display name contains --q (case-insensitive), newest first. Searches the newest 500 inboxes in scope; the response has truncated: true when there were more. Not ranked by relevance.

Requires the inbox_read permission.

```bash
machinemail inboxes search [flags]
```

#### Flags

| Field                     | Type           |   | Description   |
| ------------------------- | -------------- |---| ------------- |
| `--pod <pod-id>`         | `string`       |   | Only this pod. |
| `--q <value>`            | `string`       | required | Text to find in the address or display name (case-insensitive substring). |
| `--limit <n>`            | `integer`      |   | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>`   | `string`       |   | next_page_token from the previous page. |
| `--all`                  | `boolean`      |   | Follow next_page_token and return every page. |

#### Examples

```bash
machinemail inboxes search --q invoice
machinemail inboxes search --q invoice --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail inboxes search --q invoice --all --json | jq '.inboxes | length'
```

#### API

- [`GET /v0/inboxes/search`](/content/docs/reference/api/inboxes#search-inboxes/index.html)
- [`GET /v0/pods/{pod_id}/inboxes/search`](/content/docs/reference/api/inboxes#search-inboxes-in-pod/index.html) with `--pod`

## inboxes update

Update inbox.

Fields you omit are unchanged. To pause an inbox, set --status to paused; set it back to active to resume.

Requires the inbox_update permission.

```bash
machinemail inboxes update <inbox-id> [flags]
```

#### Arguments

#### Flags

| Field                     | Type           |   | Description   |
| ------------------------- | -------------- |---| ------------- |
| `--pod <pod-id>`         | `string`       |   | Use this pod's scoped route. |
| `--display-name <value>` | `string`       |   | Display name: Display Name <username@domain.com>. |
| `--status`               | `active \| paused` |   | Whether the inbox sends and receives mail. paused stops both: sends return 403 (Inbox <inbox_id> is paused), and incoming mail is not stored; a message.rejected event with reason inbox_paused is emitted instead. Mail already in the inbox, its drafts and its API keys are kept. Set active to resume. |
| `--metadata <json>`      | `JSON \| null` |   | Merged into the existing metadata: keys you send are added or overwritten, keys set to null are removed, other keys are kept. null clears all metadata. null clears the value. |
| `--ttl-seconds <n>`      | `integer \| null` |   | Make the inbox ephemeral with this TTL (expires_at restarts from now), or null to make it permanent. null clears the value. |
| `--ephemeral`            | `boolean`      |   | false makes the inbox permanent (same as --ttl-seconds null). true alone has no effect; send --ttl-seconds. |
| `-d, --data <json|@file|->` | `string`   |   | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
machinemail inboxes update agent@machinemail.dev
machinemail inboxes update agent@machinemail.dev --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail inboxes update agent@machinemail.dev --data @body.json
machinemail inboxes update agent@machinemail.dev --metadata null   # clears metadata
```

#### API

- [`PATCH /v0/inboxes/{inbox_id}`](/content/docs/reference/api/inboxes#update-inbox/index.html)
- [`PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}`](/content/docs/reference/api/inboxes#update-inbox-in-pod/index.html) with `--pod`