Mail workflow · MachineMail Docs
Top-level commands for the jobs agents and people do most
Send a message, read one with its trust verdict, wait for a message or a verification code, and follow events live.
| 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 |
Every command also takes the global flags.
send
Send an email from an inbox.
Sends through POST /v0/inboxes/{inbox_id}/messages/send. The body comes from —text, —html or —file (a .html/.htm file is sent as HTML, anything else as text); pass - to any of them to read stdin. Stdin is never read unless you ask. —from defaults to MACHINEMAIL_INBOX, the profile inbox from machinemail register, or the inbox of an inbox-scoped key.
machinemail send [flags]
Flags
| Field | Description |
|---|---|
--from <inbox-id> |
Inbox to send from. |
--to <address> |
Recipient (repeat or comma-separate). Repeat the flag for several values. |
--cc <address> |
CC recipient. Repeat the flag for several values. |
--bcc <address> |
BCC recipient. Repeat the flag for several values. |
-s, --subject <text> |
Subject. |
| `--text <text | ->` |
| `--html <html | ->` |
| `-f, --file <path | ->` |
--attach <path> |
Attach a file (10 MB of files per message in total). Repeat the flag for several values. |
--reply-to <address> |
Reply-To address. Repeat the flag for several values. |
--label <label> |
Label for the sent message. Repeat the flag for several values. |
--header <Name: value> |
Extra header. Repeat the flag for several values. |
Examples
machinemail send --from agent@machinemail.dev --to ada@acme.dev -s "Hello" --text "Hi Ada"
echo "Build passed" | machinemail send --to ops@acme.dev -s "CI" --text -
machinemail send --to ada@acme.dev -s "Report" --file report.html --attach report.pdf
read
Show a message: headers, trust verdict and agent-safe text.
Shows one message with its trust report summary (verdict, score, authentication, flags) and the agent-safe body (trust.content.text: hidden text, zero-width characters, quotes and signatures removed). —original shows the text as the sender wrote it, labelled untrusted; —raw prints the raw RFC 5322 source.
machinemail read <message-id> [flags]
Arguments
| Field | Description |
|---|---|
<message-id> |
Required message id (msg_...), optionally preceded by its inbox |
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Inbox the message is in (found automatically when omitted). |
--original |
Show the original text instead of the agent-safe text (untrusted). |
--full |
JSON output: the whole API message (original text and HTML included, untrusted) instead of the agent view. |
--raw |
Print the raw RFC 5322 message. |
Examples
machinemail read msg_01m4g46p1y0000bqmf6m6yv7h5
machinemail read agent@machinemail.dev msg_01m4...
machinemail read msg_01m4... --json | jq -r .body
machinemail read msg_01m4... --json --full | jq .trust
wait
Wait for a message to arrive (and extract a code or magic link with —otp).
Blocks until a new inbound message matching the filters arrives in the inbox, then prints it. Listens on the SSE event stream and polls as a fallback. Only mail received after the command starts counts; —since 5m also accepts mail from the last five minutes (use it when you triggered the email before calling wait).
Piped (or with —json) it prints the agent view of the message: headers, the trust verdict, untrusted: true unless the sender authenticated, and the agent-safe body (withheld for quarantined mail); —full prints the whole API object instead, original text included.
machinemail wait [flags]
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Inbox to watch (default: MACHINEMAIL_INBOX or the profile inbox). |
| `--from <address | domain>` |
--subject <text> |
Subject contains this, case-insensitive (any of several matches). Repeat the flag for several values. |
-t, --timeout <duration> |
Give up after this long: 90, 90s, 5m (default 5m; 0 waits forever). |
| `--since <duration | iso>` |
--otp |
Print only the verification code, or the magic link when there is none. |
--link |
With --otp: print the magic link even when there is a code. |
--pattern <regex> |
With --otp: extract with this regex (first group, else the match). |
--link-domain <domain> |
With --otp: the magic link must be on this domain or a subdomain of it (default: the sender domain). |
--allow-unauthenticated |
With --otp: also use mail whose sender did not authenticate, or that has no trust report (never suspicious or quarantined mail). |
--full |
JSON output: the whole API message (original text and HTML included, untrusted) instead of the agent view. |
--poll |
Poll only; do not use the event stream. |
Examples
machinemail wait --inbox signup-7f3k@machinemail.dev --otp
CODE=$(machinemail wait --inbox "$ADDR" --from github.com --otp --timeout 2m)
machinemail wait --inbox "$ADDR" --subject invoice --json | jq .trust.level
machinemail wait --inbox "$ADDR" --otp --allow-unauthenticated # e.g. a test sender without SPF/DKIM
tail
Follow live events (messages, deliveries, inboxes) as they happen.
Streams GET /v0/events/stream. On a terminal: one line per event with the trust badge of inbound mail, and a status line. Piped: NDJSON, one {id, event, data} per line. Reconnects on its own and resumes with Last-Event-ID; pass —last-event-id to resume from an earlier run. Ctrl-C stops it (exit 0).
machinemail tail [flags]
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Only these inboxes. Repeat the flag for several values. |
--pod <pod-id> |
Only these pods. Repeat the flag for several values. |
-e, --event-types |
Only these event types (comma-separated or repeated). Repeat the flag for several values. |
--last-event-id <evt_...> |
Replay events after this one first. |
--max <n> |
Stop after n events. |
Examples
machinemail tail
machinemail tail --inbox agent@machinemail.dev -e message.received
machinemail tail -e message.bounced,message.complained | jq -c .data.message.to