# inboxes availability

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

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

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

## [inboxes availability](/content/docs/cli/commands/inboxes#inboxes-availability/index.html)

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.

```shell
machinemail inboxes availability [flags]
```

#### [Flags](/content/docs/cli/commands/inboxes#flags/index.html)

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

#### [Examples](/content/docs/cli/commands/inboxes#examples/index.html)

```shell
machinemail inboxes availability
machinemail inboxes availability --pod pod_01m4fykg210000x6z8b6wc2rdx
```

#### [API](/content/docs/cli/commands/inboxes#api/index.html)

- [`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](/content/docs/cli/commands/inboxes#inboxes-create/index.html)

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.

```shell
machinemail inboxes create [flags]
```

#### [Flags](/content/docs/cli/commands/inboxes#flags-1/index.html)

| Field            | Description     |
| ---------------- | ---------------- |
| `--pod <pod-id>`        | Create it in this pod. |
| `--username <value>`    | 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>`     | Domain of the address: a domain verified by this organization. Defaults to the shared domain. |
| `--display-name <value>` | Display name: Display Name <username@domain.com>. |
| `--client-id <id>`      | 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>`      | 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](/content/docs/cli/commands/inboxes#examples-1/index.html)

```shell
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](/content/docs/cli/commands/inboxes#api-1/index.html)

- [`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](/content/docs/cli/commands/inboxes#inboxes-delete/index.html)

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.

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

#### [Arguments](/content/docs/cli/commands/inboxes#arguments/index.html)

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

#### [Flags](/content/docs/cli/commands/inboxes#flags-2/index.html)

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

#### [Examples](/content/docs/cli/commands/inboxes#examples-2/index.html)

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

#### [API](/content/docs/cli/commands/inboxes#api-2/index.html)

- [`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](/content/docs/cli/commands/inboxes#inboxes-export/index.html)

Export inbox.

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

Requires the `message_read` permission.

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

#### [Arguments](/content/docs/cli/commands/inboxes#arguments-1/index.html)

#### [Flags](/content/docs/cli/commands/inboxes#flags-3/index.html)

| Field            | Description     |
| ---------------- | ---------------- |
| `--pod <pod-id>`        | 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](/content/docs/cli/commands/inboxes#examples-3/index.html)

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

#### [API](/content/docs/cli/commands/inboxes#api-3/index.html)

- [`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](/content/docs/cli/commands/inboxes#inboxes-get/index.html)

Get inbox.

Requires the `inbox_read` permission.

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

#### [Arguments](/content/docs/cli/commands/inboxes#arguments-2/index.html)

#### [Flags](/content/docs/cli/commands/inboxes#flags-4/index.html)

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

#### [Examples](/content/docs/cli/commands/inboxes#examples-4/index.html)

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

#### [API](/content/docs/cli/commands/inboxes#api-4/index.html)

- [`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](/content/docs/cli/commands/inboxes#inboxes-list/index.html)

List inboxes.

Also: `machinemail inboxes ls`.

Requires the `inbox_read` permission.

```shell
machinemail inboxes list [flags]
```

#### [Flags](/content/docs/cli/commands/inboxes#flags-5/index.html)

| Field            | Description     |
| ---------------- | ---------------- |
| `--pod <pod-id>`        | Only this pod. |
| `--limit <n>`          | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default`50` |
| `--page-token <value>`  | 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](/content/docs/cli/commands/inboxes#examples-5/index.html)

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

#### [API](/content/docs/cli/commands/inboxes#api-5/index.html)

- [`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](/content/docs/cli/commands/inboxes#inboxes-new/index.html)

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.

```shell
machinemail inboxes new [flags]
```

#### [Flags](/content/docs/cli/commands/inboxes#flags-6/index.html)

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

#### [Examples](/content/docs/cli/commands/inboxes#examples-6/index.html)

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

## [inboxes search](/content/docs/cli/commands/inboxes#inboxes-search/index.html)

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.

```shell
machinemail inboxes search [flags]
```

#### [Flags](/content/docs/cli/commands/inboxes#flags-7/index.html)

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

#### [Examples](/content/docs/cli/commands/inboxes#examples-7/index.html)

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

#### [API](/content/docs/cli/commands/inboxes#api-6/index.html)

- [`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](/content/docs/cli/commands/inboxes#inboxes-update/index.html)

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.

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

#### [Arguments](/content/docs/cli/commands/inboxes#arguments-3/index.html)

#### [Flags](/content/docs/cli/commands/inboxes#flags-8/index.html)

| Field            | Description     |
| ---------------- | ---------------- |
| `--pod <pod-id>`        | Use this pod's scoped route. |
| `--display-name <value>` | 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](/content/docs/cli/commands/inboxes#examples-8/index.html)

```shell
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](/content/docs/cli/commands/inboxes#api-7/index.html)

- [`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`