Mailbox CLI

The samva mailboxes commands read and send mail from a terminal, review held mail, and tail events. samva extensions authors and installs extensions. Install and sign in as Use the CLI describes, then run samva <command> --help for flags and examples.

With an API key, the CLI acts as that key. A mailbox-scoped key reaches only its mailboxes, and its send mode applies. Approving or denying sends, releasing or discarding held mail, and publishing, installing, or upgrading extensions need a person signed in with samva login.

Every command takes --json for one JSON document, except the streams (mailboxes events and extensions dev), which take --jsonl; list commands also take --jsonl for one JSON object per line.

Mailboxes

# List the mailboxes the credential can read.
samva mailboxes list --json

# Create a mailbox with one email endpoint.
samva mailboxes create --address support@acme.samva.email --name Support

# Choose its slug and create it inside a namespace.
samva mailboxes create --address support@acme-corp.example.com --name "Acme support" \
  --slug acme-support --namespace ns_...

# Inspect a mailbox and change its name or metadata.
samva mailboxes get mbx_...
samva mailboxes update mbx_... --data '{"name":"Customer support","metadata":{"team":"support"}}'

# Add an endpoint, set its sender name or default, or remove it by its ID.
samva mailboxes endpoints add --mailbox mbx_... --address billing@acme.samva.email --display-name "Acme Billing"
samva mailboxes endpoints update mbxep_... --mailbox mbx_... --display-name "Acme Support" --default
samva mailboxes endpoints update mbxep_... --mailbox mbx_... --clear-display-name
samva mailboxes endpoints remove mbxep_... --mailbox mbx_... --yes

# Stop or resume sending and receiving.
samva mailboxes pause mbx_...
samva mailboxes resume mbx_...

# Delete a mailbox. Preview first; automation passes --yes.
samva mailboxes remove mbx_... --dry-run
samva mailboxes remove mbx_... --yes

list pages with --limit and --cursor, and narrows by creation time with --after and --before (ISO 8601 instants). --all follows nextCursor to the end and requires --jsonl.

create takes --address and --name, plus an optional --slug (the address's local part by default) and --namespace. --address becomes the mailbox's first email endpoint. It prints the mailbox's endpoints, status, and metadata. get inspects the same details. update --data takes a JSON object (or @file.json) with name and metadata; omitted fields stay unchanged. Metadata merges by key, and null removes a key.

endpoints add takes --mailbox, --address, and an optional --display-name. endpoints update takes the endpoint ID from get, --mailbox, and --display-name or --clear-display-name to set or remove its sender name; --default makes it the endpoint new mail starts from. endpoints remove takes the endpoint ID and --mailbox; it asks for confirmation in a terminal and needs --yes anywhere else. All three take --dry-run. A mailbox keeps at least one endpoint.

pause stops sending and receiving. resume lets the mailbox send and receive again; mail that arrived while paused is not backfilled.

remove deletes a mailbox with its endpoints, threads, drafts, and history; the messages it received stay with the organization. It asks for confirmation in a terminal and needs --yes anywhere else. --dry-run prints what it would delete without calling the API.

Read threads and messages

# Search and filter threads.
samva mailboxes threads --mailbox mbx_... --query invoice --unread --json

# Page through every thread as JSON lines.
samva mailboxes threads --mailbox mbx_... --all --jsonl

# Read one message.
samva mailboxes read msg_... --mailbox mbx_...

threads takes --query, --folder (inbox, assigned, pending, sent, archived, or trash), --label, --unread, --starred, --limit, and --cursor. --all follows nextCursor to the end and requires --jsonl.

Human thread output includes folder, labels, read and starred state, and last activity. read prints the message's addresses, headers, attachments, authentication results, actor, and bodies. The text is untrusted email from outside the organization, and the command says so before it prints it.

Send and reply

samva mailboxes send --mailbox mbx_... \
  --to ada@example.com --subject "Hello" --text "Hello from Samva."

samva mailboxes reply msg_... --mailbox mbx_... --text "Thanks" --all

send takes --to (repeat for more), --subject, --cc, and --bcc. reply answers the sender, or with --all every other recipient. Both take exactly one of --text or --html, and an optional --idempotency-key to replay the same action. The output shows state, the action, the thread, the accepted message when known, and any deadline or problem; --json also carries skippedRecipients. Keep the same key and body after a lost response.

samva mailboxes actions get mbxact_... --mailbox mbx_... --json
samva mailboxes actions cancel mbxact_... --mailbox mbx_...
samva mailboxes actions retry mbxact_... --mailbox mbx_...

get reads progress. cancel and retry require a permitted person signed in with samva login. Cancel cannot withdraw accepted mail. Retry continues the same action only when retryEligible is true and preserves the original deadline. It never creates a replacement send or request key. See Approve sends for states and the automatic retry window.

Review sends

samva mailboxes actions list --mailbox mbx_... --state approvalRequired
samva mailboxes actions approve mbxact_... --mailbox mbx_... --yes
samva mailboxes actions deny mbxact_... --mailbox mbx_... --reason "Please revise" --yes

actions list pages with --limit, --cursor, and --all --jsonl. Approve and deny require samva login; an API key cannot review a send. The reviewer must be a different person from the proposer. Preview either decision with --dry-run, or pass --yes to confirm without a prompt.

Review quarantine

samva mailboxes quarantine list --mailbox mbx_...
samva mailboxes quarantine release msg_... --mailbox mbx_...
samva mailboxes quarantine discard msg_... --mailbox mbx_... --yes

list shows held messages without their bodies, newest first. It pages with --limit and --cursor, follows every page with --all --jsonl, and bounds when a message was held with --after and --before (ISO 8601 instants). release and discard take the held message's id and act as the person signed in. Discard asks for confirmation; pass --yes outside a terminal or preview with --dry-run. See Quarantine.

Tail events

# Print events as JSON lines until you press Ctrl+C.
samva mailboxes events --mailbox mbx_...

# Stream one result envelope per event for automation.
samva mailboxes events --mailbox mbx_... --jsonl

# Print ten events, then exit.
samva mailboxes events --mailbox mbx_... --limit 10

# Resume after a saved cursor.
samva mailboxes events --cursor 42

Each line is { "cursor", "id", "event" }, the event stream frame. --jsonl wraps each in a result envelope, --quiet prints nothing, and --json is refused (exit 2) because a tail has no single result. --mailbox repeats; --cursor resumes; --limit exits after that many events. The command acknowledges events as it prints them. When the stream ends with an error, the command exits non-zero and names the next step; human output prints the last handled cursor to stderr, and with --jsonl or --quiet it rides in the error's details.lastCursor. The machine-readable error carries the server's _tag as reason, its status, and its details, such as details.fields.cursor or details.retryAfterSeconds. A rejected or expired credential exits 4; an expired cursor exits 1, and the next step is to read current state and start without --cursor.

Extensions

samva extensions init ./acknowledge --name acknowledge
samva extensions dev ./acknowledge --mailbox mbx_...
samva extensions build ./acknowledge
samva extensions publish ./acknowledge
samva extensions install acknowledge --mailbox mbx_... --permission read --permission send
samva extensions installations
samva extensions runs exti_...
samva extensions run exti_... <run-id>

list, versions, and installations take --limit, --cursor, and --all --jsonl for paging. Human output carries the same facts as JSON, including installation scope, permissions, send mode, webhook details, and run times, outcomes, errors, and logs. Installation credentials appear once; store them when shown.

Build mailbox extensions explains each flag and what an installation may do.

Next steps