commands.md

Command reference

Every machinemail command, generated from the CLI's own command tree: usage, arguments, flags with types and defaults, examples and the API routes they call.

Every command the CLI has, generated from the same data as machinemail --help, grouped as --help groups them. mm is the same binary, so every example also works with mm in place of machinemail.

machinemail <command> [args] [flags]
machinemail <resource> <action> [args] [flags]

Resource commands are generated from the API reference: path parameters are arguments, query parameters and body fields are flags. A route that also exists under a pod or an inbox is one command with a --pod or --inbox flag. Flag values are typed: integers are checked, booleans take --flag, --flag=false or --no-flag, arrays repeat the flag, objects take JSON, and -d/--data takes the whole body as JSON, @file or - for stdin. See Output and scripting for output formats and exit codes.

Global flags

Every command accepts these. Command flags go after <resource> <action>.

Field	Type		Description
`--json`	`boolean`		Print raw JSON, even on a terminal.
`--fields <a,b.c>`	`string`		Only these fields (dot paths), in JSON and tables.
`--profile <name>`	`string`		Config profile (MACHINEMAIL_PROFILE).
`--api-key <key	->`	`string`
`--base-url <url>`	`string`		API origin (MACHINEMAIL_BASE_URL).
`-v, --verbose`	`boolean`		Log requests and responses to stderr (keys redacted).
`-q, --quiet`	`boolean`		No spinners or success lines; errors still print.
`-y, --yes`	`boolean`		Confirm deletes without asking (needed when there is no terminal to ask on).
`--color`	`boolean`		Color on or off (default: on for a terminal; NO_COLOR also turns it off). Default: `on for a terminal`.
`-h, --help`	`boolean`		Show help.

Getting started

Command	Summary
`login`	Sign in with the browser (or an API key) and save the key to a profile
`whoami`	Show the key, profile and API in use, and check the key
`doctor`	Check the config, connectivity, key, clock and CLI version
`register`	Register this agent (auth.md): a sandbox inbox and credentials, no human needed
`claim`	Get a new claim code for a registered agent, and wait for a human to claim it
`logout`	Remove the stored key from a profile, and optionally revoke it

Mail

Command	Summary
`send`	Send an email from an inbox
`read`	Show a message: headers, trust verdict and agent-safe text
`wait`	Wait for a message to arrive (and extract a code or magic link with --otp)
`tail`	Follow live events (messages, deliveries, inboxes) as they happen
`messages attachment`	Get attachment
`messages batch-get`	Batch get messages
`messages batch-update`	Batch update messages
`messages delete`	Delete message
`messages download`	Download attachment
`messages forward`	Forward message
`messages get`	Get message
`messages list`	List messages
`messages raw`	Get raw message
`messages reply`	Reply to a message
`messages reply-all`	Reply to all recipients of a message
`messages search`	Search messages
`messages send`	Send message
`messages trust`	Get message trust report
`messages update`	Update message
`threads delete`	Delete thread
`threads get`	Get thread
`threads list`	List threads
`threads search`	Search threads
`threads update`	Update thread
`drafts create`	Create draft
`drafts delete`	Delete draft
`drafts download-attachment`	Download draft attachment
`drafts get`	Get draft
`drafts list`	List drafts
`drafts send`	Send draft
`drafts update`	Update draft
`inbound raw`	Inject raw message

Inboxes

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
`pods create`	Create pod
`pods delete`	Delete pod
`pods get`	Get pod
`pods list`	List pods
`pods update`	Update pod
`lists create`	Create list entry
`lists delete`	Delete list entry
`lists get`	Get list entry
`lists list`	List the entries of an allow or block list
`suppressions create`	Add suppression
`suppressions delete`	Remove suppression
`suppressions get`	Get suppression
`suppressions list`	List suppressions

Domains

Command	Summary
`domains connect`	Get Domain Connect setup
`domains create`	Create domain
`domains delete`	Delete domain
`domains get`	Get domain
`domains list`	List domains
`domains update`	Update domain
`domains verify`	Verify domain
`domains zone-file`	Get zone file

Webhooks

Command	Summary
`webhooks create`	Create webhook
`webhooks delete`	Delete webhook
`webhooks deliveries`	List deliveries
`webhooks get`	Get webhook
`webhooks headers`	Get webhook headers
`webhooks list`	List webhooks
`webhooks replay`	Replay delivery
`webhooks test`	Send test event
`webhooks update`	Update webhook
`webhooks update-headers`	Update webhook headers
`events get`	Get event
`events list`	List events
`events stream`	Stream events as they happen (server-sent events)

Admin

Command	Summary
`org get`	Get organization
`org members`	List members
`org update`	Update organization
`org usage`	Get plan usage
`api-keys create`	Create API key
`api-keys delete`	Delete API key
`api-keys get`	Get API key
`api-keys list`	List API keys
`api-keys update`	Update API key
`agent-registrations delete`	Revoke agent registration
`agent-registrations get`	Get agent registration
`agent-registrations list`	List agent registrations
`metrics events`	Query events
`metrics rates`	Query rates
`metrics usage`	Query usage
`health check`	Check that the API is up (liveness)
`health ready`	Check that the API can serve requests (readiness)
`import agentmail`	Copy AgentMail settings (pods, domains, inboxes, webhooks, lists) into MachineMail

CLI

Command	Summary
`open`	Open the dashboard in a browser
`completion`	Print a shell completion script (bash, zsh, fish)
`version`	Print the CLI version
`auth login`	Sign in with the browser (or an API key) and save the key to a profile
`auth logout`	Remove the stored key from a profile, and optionally revoke it
`auth me`	The credential as the API reports it (GET /v0/auth/me; whoami says more)
`auth status`	Show the key, profile and API in use, and check the key
`auth whoami`	Show the key, profile and API in use, and check the key
`config get`	Print the value of a config key in effect
`config list`	Print the config file, keys masked
`config path`	Print the config file path
`config set`	Set a config key
`config unset`	Remove a config key (back to its default)
`profiles delete`	Delete a profile and its stored key
`profiles list`	List profiles (keys masked)
`profiles use`	Make a profile the current one