inboxes · MachineMail Docs

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.

shell

machinemail inboxes availability [flags]

Flags

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

shell

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 1000 inboxes on the shared domain (deployment setting); past that the API returns 403. Inbox-scoped credentials cannot create inboxes (403).

Requires the inbox_create permission.

shell

machinemail inboxes create [flags]

Flags

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

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

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

--ephemeralboolean

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. null clears the value.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

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

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.

shell

machinemail inboxes delete <inbox-id> [flags]

Arguments

<inbox-id>stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Flags

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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.

shell

machinemail inboxes export <inbox-id> [flags]

Arguments

<inbox-id>stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Flags

--pod <pod-id>string

Only this pod.

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

shell

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.

shell

machinemail inboxes get <inbox-id> [flags]

Arguments

<inbox-id>stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Flags

--pod <pod-id>string

Only this pod.

Examples

shell

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.

shell

machinemail inboxes list [flags]

Flags

--pod <pod-id>string

Only this pod.

--limit <n>integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

Default50

--page-token <value>string

next_page_token from the previous page.

--ascendingboolean

Sort oldest first.

--ephemeralboolean

Only ephemeral (true) or only permanent (false) inboxes.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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.

shell

machinemail inboxes new [flags]

Flags

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

Defaultthe shared domain

--display-name <name>string

Display name for outgoing mail.

--ephemeralboolean

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

shell

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.

shell

machinemail inboxes search [flags]

Flags

--pod <pod-id>string

Only this pod.

--q <value>stringRequired

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.

Default50

--page-token <value>string

next_page_token from the previous page.

--allboolean

Follow next_page_token and return every page.

Examples

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

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.

shell

machinemail inboxes update <inbox-id> [flags]

Arguments

<inbox-id>stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Flags

--pod <pod-id>string

Use this pod's scoped route.

--display-name <value>string

Display name: Display Name <username@domain.com>.

--statusactive | paused

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

--ephemeralboolean

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

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

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