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. Releasing or discarding held mail, and publishing or installing 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 or more addresses.
samva mailboxes create --slug support --name Support --address support@acme.samva.email

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

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 --slug, --name, and --address (repeat for more), plus an optional --namespace. It prints the mailbox ID, name, address, and status.

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.

read prints the message's addresses, headers, and what the sender wrote. 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 so a retried command sends once. The output shows status (sent or pending_approval), the message, the thread, and the action; --json also carries skippedRecipients. See Approve sends.

Review quarantine

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

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

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

Next steps