inboxes.md

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`	Check inbox availability
`inboxes create`	Create inbox
`inboxes delete`	Delete inbox
`inboxes export`	Export inbox
`inboxes get`	Get inbox
`inboxes list`	List inboxes
`inboxes new`	Create an inbox and print its address (pipe-friendly)
`inboxes search`	Search inboxes
`inboxes update`	Update inbox

Every command also takes the global flags.

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.

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

machinemail inboxes availability
machinemail inboxes availability --pod pod_01m4fykg210000x6z8b6wc2rdx

API

GET /v0/inboxes/availability
GET /v0/pods/{pod_id}/inboxes/availability 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.

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

Examples

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
POST /v0/pods/{pod_id}/inboxes 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.

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

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

API

DELETE /v0/inboxes/{inbox_id}
DELETE /v0/pods/{pod_id}/inboxes/{inbox_id} with --pod

inboxes export

Export inbox.

Every message in the inbox, oldest first, streamed as an attachment named ..

Requires the message_read permission.

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`

Examples

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

API

GET /v0/inboxes/{inbox_id}/export
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/export with --pod

inboxes get

Get inbox.

Requires the inbox_read permission.

machinemail inboxes get <inbox-id> [flags]

Arguments

Flags

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

Examples

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

API

GET /v0/inboxes/{inbox_id}
GET /v0/pods/{pod_id}/inboxes/{inbox_id} with --pod

inboxes list

List inboxes.

Also: machinemail inboxes ls.

Requires the inbox_read permission.

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

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

API

GET /v0/inboxes
GET /v0/pods/{pod_id}/inboxes 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.

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

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.

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

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
GET /v0/pods/{pod_id}/inboxes/search 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.

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

Examples

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}
PATCH /v0/pods/{pod_id}/inboxes/{inbox_id} with --pod