inboxes · MachineMail Docs

inboxes availability

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	Description
`--pod <pod-id>`	Only this pod.
`--username <value>`	Local part to check.
`--domain <domain>`	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	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`
`--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
`--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

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

Flags

Field	Description
`--pod <pod-id>`	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 <inbox_id>.<format>.

Requires the message_read permission.

machinemail inboxes export <inbox-id> [flags]

Arguments

Flags

Field	Description
`--pod <pod-id>`	Only this pod.
`--format`	mbox
`-o, --output <file	dir

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	Description
`--pod <pod-id>`	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	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

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

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

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	Description
`--pod <pod-id>`	Use this pod's scoped route.
`--display-name <value>`	Display name: Display Name username@domain.com.
`--status`	`active`
`--metadata <json>`	JSON
`--ttl-seconds <n>`	integer
`--ephemeral`	boolean - false makes the inbox permanent (same as --ttl-seconds null). true alone has no effect; send --ttl-seconds.
`-d, --data <json	@file

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