The mails CLI

Every command below comes from the CLI’s own command table (mails commands --json, version 0.1.0), so this page and mails --help list the same commands and flags. The examples act on hello, the agent a new workspace starts with; the ones that create an agent, archive one or test a forward act on a second agent, which needs a paid plan.

Installation

The CLI needs Node.js 20 or newer and installs no other packages.

npm install -g @mailsai/cli

npx @mailsai/cli --help

Then run mails doctor: it checks Node, your sign-in, the connection, your clock and what your key is allowed to do.

Authentication

The CLI picks its credential in this order: --api-key, then MAILS_API_KEY, then a saved profile (--profile, MAILS_PROFILE, or the active one). On a server or in CI, use an API key in MAILS_API_KEY.

# Sign in through your browser, saved as the profile "default"
mails login

# A second workspace: choose it in the browser
mails login --profile acme

# Paste an API key instead; it is never echoed
mails login --api-key

# Which key, workspace and scopes are in use
mails whoami

The browser sign-in can do no more than your role in the workspace allows: as an owner or admin it can do everything, as a member it can send and read but cannot create API keys, agents or domains, and as a billing member it can only read.

Every command in this section works without signing in, except mails whoami and mails workspaces current.

mails login

Sign in through your browser, or with an API key.

Opens your browser to approve the CLI, then saves the sign-in as a profile (in the OS keychain when there is one, otherwise in a file only you can read). With --api-key it saves a key instead: paste it at the prompt, or pipe it in. Nothing is ever echoed, and only the first 12 characters of a key are ever shown.

mails login
mails login --api-key
mails login --api-key < key.txt
mails login --profile staging --api-url https://staging.example.com

mails logout

Sign out: forget a saved profile (and end its browser sign-in).

mails logout
mails logout --profile staging
mails logout --all

Profiles

mails whoami
mails whoami --json | jq -r .workspace.slug
mails auth list
mails auth list --json
mails auth switch staging
mails auth rename default work
mails auth remove staging

Workspaces

Every key and every browser sign-in belongs to one workspace. To add another workspace, run mails login --profile <name> and choose it in the browser.

mails workspaces list
mails workspaces current
mails workspaces switch acme

Scripts and AI agents

People get tables and everything else gets JSON. When stdout is not a terminal (a pipe, a file, an agent), a command prints JSON only, except mails emails raw, which prints text, mails receiving attachment, which writes the file itself, mails completion, which prints a shell script, and --help, which is always text. --json forces JSON in a terminal, and --no-json keeps the table in a pipe.

Errors are JSON on stderr, with exit code 1:

{ "error": { "code": "invalid_api_key", "message": "API key not recognized.", "request_id": "req_…", "status": 401, "hint": "…" } }

• mails commands --json lists every command with its arguments, flags, types, allowed values, examples, the API route behind it and the key scope it needs.
• Bodies can come from files or stdin: --text-file, --html-file, --body-file, or --data - to pipe a JSON body in. Flags given alongside override its fields.
• Sends carry an idempotency key, so a retry after a dropped connection never sends twice. Network failures, 429s and 5xx answers on reads are retried with backoff.
• --dry-run prints the request a command would make, without the credential and with file contents shortened, instead of sending it. Only the commands that call one API route do this; the others, such as mails login, mails logout or mails events tail, ignore it and run for real. --all follows pagination to the end.

mails receiving list --json | jq -r '.data[0].subject'

# Wait for one inbound email, then exit
mails events tail --type message.received --count 1 --json

cat batch.json | mails emails batch --data -

Emails

Send email and look up what was sent. Also available as mails messages.

mails emails list

List sent emails. Also: mails emails ls, mails messages list.

mails emails list --limit 10
mails emails list --agent-id hello --all --json

Needs a key with the read scope. API: GET /v1/messages. --all follows every page.

mails emails send

Send an email. Also: mails messages send.

Sends an email from one of your agents. With a mk_test_ key the message is stored and its message.sent event reaches your webhooks (marked test_mode: true), but no email is sent and nothing is billed. Quota, suppression and rate-limit refusals are skipped, and a message the cold-email firewall would refuse comes back 201 with classifier_warning instead.

mails emails send --to jordan@example.com --subject "Your order shipped" --text "It is on its way."
mails emails send --from hello --to a@example.com,b@example.com --subject "Hello" --html-file ./hello.html --attach ./invoice.pdf
cat message.json | mails emails send --data -

Needs a key with the send scope. API: POST /v1/messages.

mails emails batch

Send up to 100 emails in one request. Also: mails messages batch.

Sends up to 100 messages in one request. Per-message failures are returned inline in data[] and do not fail the batch; the HTTP status is still 201. Each failure is the error a single send would answer: a message a send limit refused carries resets_at and retry_after_seconds, one the email service would not take for now (503 upstream_unavailable) retry_after_seconds, and a plan refusal upgrade_url.

The body is a JSON array of up to 100 messages, each with the fields of mails emails send except attachments: an item with attachments refuses the whole batch with 422.

mails emails batch --body-file ./batch.json
cat batch.json | mails emails batch --data -

Needs a key with the send scope. API: POST /v1/messages/batch.

mails emails appeal

Ask for a second review of a send refused as cold outreach. Also: mails messages appeal.

Requests a second, independent review of content refused with cold_email_prohibited. Submit the SAME subject and body the refused send used.

mails emails appeal --subject "Your invoice" --body-text "Hi Jordan, your invoice is attached."

Needs a key with the send scope. API: POST /v1/messages/appeal.

mails emails get

Show one sent email. Also: mails messages get.

mails emails get msg_01JABC

Needs a key with the read scope. API: GET /v1/messages/{id}.

mails emails reschedule

Change when a scheduled email goes out. Also: mails emails update, mails messages reschedule.

Moves a scheduled send to a new future scheduled_at, and raises message.scheduled again with the new scheduled_at and the previous_scheduled_at it replaced. It needs the send scope as well as manage, and a live key for a live message (403 live_mode_required); the key that scheduled the send keeps answering for it.

mails emails reschedule msg_01JABC --scheduled-at 2026-12-01T09:00:00Z

Needs a key with the manage and send scope. API: PATCH /v1/messages/{id}.

mails emails reply

Reply in the same thread to a sent or received email. Also: mails messages reply.

Replies in-thread to a sent or received message. Sets In-Reply-To, References, and a Re: subject server-side. A reply cannot carry attachments (422 invalid_field, param attachments): to reply with files, send with POST /v1/messages and in_reply_to_message_id.

mails emails reply rcv_01JABC --text "Thanks, that works for us."
mails emails reply rcv_01JABC --text-file ./reply.txt --reply-all

Needs a key with the send scope. API: POST /v1/messages/{id}/reply.

mails emails forward

Forward a sent or received email to new recipients. Also: mails messages forward.

Forwards a sent or received message to new recipients with a quoted body and Fwd: subject. Always sends immediately. Both parts carry the forwarded message: the HTML part is the covering note (body_html, else body_text), the forwarded header and the original (its own HTML, or its text), sent whenever there is HTML to carry.

mails emails forward rcv_01JABC --to warehouse@example.com --text "For your records."

Needs a key with the send scope. API: POST /v1/messages/{id}/forward.

mails emails cancel

Cancel a scheduled email before it goes out. Also: mails messages cancel.

Cancels a send that is still scheduled, so it is never sent. Once the send starts going out it can no longer be canceled: the cancel changes nothing and answers 409 duplicate_resource, also when the send started while the cancel was running. A test key cannot cancel a send a live key scheduled (403 live_mode_required).

mails emails cancel msg_01JABC

Needs a key with the manage scope. API: POST /v1/messages/{id}/cancel.

mails emails raw

Download an email as a raw .eml file. Also: mails messages raw.

Returns the message as a downloadable .eml attachment: the exact bytes as received when the raw message was kept (received mail up to 25 MiB), otherwise an RFC822 message rebuilt from the stored fields, with the Message-ID, From, Reply-To, In-Reply-To and References it went out or came in with.

mails emails raw msg_01JABC --output message.eml
mails emails raw msg_01JABC | less

Needs a key with the read scope. API: GET /v1/messages/{id}/raw. Prints plain text, not JSON.

Receiving

Read received email, download attachments, listen for new mail.

mails receiving list

List received emails. Also: mails receiving ls.

mails receiving list
mails receiving list --agent-id hello --json | jq '.data[0].id'

Needs a key with the read scope. API: GET /v1/messages/received. --all follows every page.

mails receiving get

Show one received email.

mails receiving get rcv_01JABC
mails receiving get rcv_01JABC --json | jq -r .extracted_text

Needs a key with the read scope. API: GET /v1/messages/received/{id}.

mails receiving attachments

List the attachments of a received email.

Every file in the message, embedded images included (inline: true). Files that could not be kept are listed under omitted.

mails receiving attachments rcv_01JABC

Needs a key with the read scope. API: GET /v1/messages/received/{id}/attachments.

mails receiving attachment

Download one attachment of a received email.

The file's bytes, always as a download (Content-Disposition: attachment) with X-Content-Type-Options: nosniff. Content-Type is the declared type when it is on a safe list, else application/octet-stream; HTML and SVG are never served as themselves. ?inline=1 asks for inline display, granted only for PNG, JPEG, GIF, WebP, AVIF and BMP images.

mails receiving attachment rcv_01JABC att_01JABC --output invoice.pdf

Needs a key with the read scope. API: GET /v1/messages/received/{id}/attachments/{attachment_id}.

mails receiving simulate

Deliver a made-up inbound email to an agent (test key only).

Drives the receive/classify half of the product with a hand-supplied envelope: runs the real classifier, threads the message, persists a received row, and emits the same typed event + webhook a real inbound would. Set in_reply_to_message_id to a prior test-send id to simulate a reply.received.

mails receiving simulate --agent hello --from jordan@example.com --subject "Where is my order?" --body-text "Order 10473 has not arrived."

Needs a key with the send scope. Works only with a test key (mk_test_…). API: POST /v1/test/inbound.

mails receiving listen

Print new mail as it arrives. Also: mails receiving tail, mails receiving watch.

Waits for inbound email and prints who it is from, the subject and the start of the body (one JSON object per line when piped or with --json; add --full for the whole message). Mail from a forged sender (no DKIM signature aligned with the From domain verifies, and that domain's DMARC policy is quarantine or reject) is left out unless you add --include-unauthenticated. Stop it with Ctrl-C, --count or --timeout.

mails receiving listen
mails receiving listen --agent hello --json
mails receiving listen --count 1 --json | jq -r ".data.subject"

Agents

The addresses that send and receive.

mails agents list

List agents. Also: mails agents ls.

Lists the workspace's agents, newest first. A key tied to one agent lists that agent and no other.

mails agents list
mails agents list --status all --json

Needs a key with the read scope. API: GET /v1/agents. --all follows every page.

mails agents create

Create an agent: an address that sends and receives.

Creates an agent (a send/receive identity) at name@<workspace>.mails.ai, or at an address on a domain your workspace has verified for sending. Add forwarding: true when the mail service that already hosts that address will forward its mail to the agent's forwarding_address (no MX change), then test it with POST /v1/agents/{id}/forwarding/verify.

A new workspace starts with one agent, hello. The Free plan allows one agent, so another needs a paid plan: mails billing portal prints the link to upgrade.

mails agents create support
mails agents create billing --domain mail.acme.com --daily-send-limit 5000
mails agents create --address support@acme.com --forwarding

Needs a key with the manage scope. API: POST /v1/agents.

mails agents get

Show one agent.

Returns an agent by its id or its name. A key tied to one agent gets any other agent as 404 agent_not_found, as if it did not exist, and a name other agents share is not reported to it as a 409.

mails agents get hello

Needs a key with the read scope. API: GET /v1/agents/{id}.

mails agents update

Change an agent's settings, or pause it.

Changes an agent's status, recipient lists, send limits, or whether its new mail is read for intent. A pause by our abuse-prevention system or for the agent's own bounce or complaint rate cannot be lifted here (403 agent_suspended), and pausing such an agent again keeps that reason.

mails agents update hello --status paused
mails agents update hello --daily-send-limit null

Needs a key with the manage scope. API: PATCH /v1/agents/{id}.

mails agents archive

Archive an agent (its address is kept and cannot be reused). Also: mails agents delete, mails agents rm.

Soft-deletes the agent (sets status to archived). The address is retained and cannot be reused, and archiving cannot be undone. The agent sends nothing more; mail that reaches it is still received, stored and sent to your webhooks as before, so none is lost.

mails agents archive support --yes

Needs a key with the manage scope. API: DELETE /v1/agents/{id}. Asks first in a terminal, and needs --yes anywhere else.

mails agents verify-forwarding

Send a test through an agent's forward, to mark it verified.

For an agent in forwarding mode: sends one test email from mails.ai to the agent's own address. When your mail service forwards it to the agent's forwarding_address, it is dropped there (the agent never sees it) and forwarding_status becomes verified; if it has not arrived 15 minutes after it was sent, failing. Answers the agent at once: poll GET /v1/agents/{id}.

mails agents verify-forwarding support

Needs a key with the manage scope. API: POST /v1/agents/{id}/forwarding/verify.

mails agents inbox

Show an agent's inbox summary and unread count.

Unread count, thread and unread counts per folder and per label, and the time of the latest message.

mails agents inbox hello

Needs a key with the read scope. API: GET /v1/agents/{id}/inbox.

Threads

Conversations: status, labels, read state, folders.

mails threads list

List conversation threads. Also: mails threads ls.

mails threads list --agent-id hello
mails threads list --status open --json

Needs a key with the read scope. API: GET /v1/threads. --all follows every page.

mails threads get

Show a thread with its messages.

mails threads get thrd_01JABC

Needs a key with the read scope. API: GET /v1/threads/{id}.

mails threads update

Change a thread's status, labels, read state or folder.

Changes read, folder, status, labels and label_ids; emits thread.updated when something changed. folder: "archive" and status: "archived" move together, and moving an archived thread anywhere else reopens it. folder: "sent" is a 422: a thread is filed there while every message in it is one the agent sent. So is status: "archived" with any folder but archive.

mails threads update thrd_01JABC --status closed --labels resolved,shipping

Needs a key with the manage scope. API: PATCH /v1/threads/{id}.

mails threads mark-read

Mark a thread as read.

mails threads mark-read thrd_01JABC

Needs a key with the manage scope. API: PATCH /v1/threads/{id}.

mails threads mark-unread

Mark a thread as unread.

mails threads mark-unread thrd_01JABC

Needs a key with the manage scope. API: PATCH /v1/threads/{id}.

mails threads restore

Move a thread back to the inbox.

mails threads restore thrd_01JABC

Needs a key with the manage scope. API: PATCH /v1/threads/{id}.

mails threads spam

Move a thread to spam.

mails threads spam thrd_01JABC

Needs a key with the manage scope. API: PATCH /v1/threads/{id}.

mails threads delete

Move a thread to trash, or delete it for good with --permanent. Also: mails threads rm, mails threads trash.

Moves the thread to trash (deleted: false, the thread returned). Sent again for a thread already in trash it changes nothing, so a retried request never destroys mail. With permanent=true it deletes the thread for good, from any folder: its messages' content, raw email and attachments are removed, and thread.deleted is emitted. Trash is also emptied automatically 30 days after a thread was moved there.

mails threads delete thrd_01JABC
mails threads delete thrd_01JABC --permanent --yes

Needs a key with the manage scope. API: DELETE /v1/threads/{id}. With --permanent it asks first in a terminal, and needs --yes anywhere else.

Drafts

Compose, edit, schedule and send drafts.

mails drafts list

List drafts. Also: mails drafts ls.

mails drafts list

Needs a key with the read or draft scope. API: GET /v1/drafts. --all follows every page.

mails drafts create

Save a draft, or schedule it with --send-at.

Creates a draft, or a scheduled draft if send_at is in the future. Scheduling sends the draft at that time, so a send_at needs the send scope: a key with only draft gets 403 insufficient_scope. A draft cannot carry attachments (422 invalid_field, param attachments); send files with POST /v1/messages.

mails drafts create --to jordan@example.com --subject "Following up" --text "Just checking in."

Needs a key with the send or draft scope. API: POST /v1/drafts.

mails drafts get

Show one draft.

mails drafts get dft_01JABC

Needs a key with the read or draft scope. API: GET /v1/drafts/{id}.

mails drafts update

Edit a draft.

Edits a draft or scheduled draft. Setting a future send_at schedules it; clearing it returns to draft. A draft that starts sending while it is being changed answers 409 duplicate_resource. Without the send scope a key can neither schedule a draft nor change a scheduled one, except to unschedule it with send_at: null (403 insufficient_scope).

mails drafts update dft_01JABC --subject "Quick follow-up"

Needs a key with the manage or draft scope. API: PATCH /v1/drafts/{id}.

mails drafts delete

Delete a draft. Also: mails drafts rm.

Deletes a draft. A draft that is being sent cannot be deleted (409 duplicate_resource), and a test key cannot delete one a live key made (403 live_mode_required).

mails drafts delete dft_01JABC --yes

Needs a key with the manage or draft scope. API: DELETE /v1/drafts/{id}. Asks first in a terminal, and needs --yes anywhere else.

mails drafts send

Send a draft now, or schedule it with --send-at.

Sends a draft immediately, or schedules it when the request body supplies a future send_at. A test key cannot send or schedule a draft a live key made (403 live_mode_required).

mails drafts send dft_01JABC
mails drafts send dft_01JABC --send-at 2026-12-01T09:00:00Z

Needs a key with the send scope. API: POST /v1/drafts/{id}/send.

Labels

Labels for threads.

mails labels list

List labels. Also: mails labels ls.

Every label in the workspace (at most 200), by name.

mails labels list

Needs a key with the read scope. API: GET /v1/labels.

mails labels create

Create a label.

A name (unique in the workspace, ignoring case) and a colour from a fixed palette of 12.

mails labels create billing --color blue

Needs a key with the manage scope. API: POST /v1/labels.

mails labels get

Show one label.

mails labels get lbl_01JABC

Needs a key with the read scope. API: GET /v1/labels/{id}.

mails labels update

Rename or recolor a label.

Renaming a label renames it on every thread that carries it.

mails labels update lbl_01JABC --name invoices

Needs a key with the manage scope. API: PATCH /v1/labels/{id}.

mails labels delete

Delete a label. Also: mails labels rm.

Deletes the label and takes it off every thread that carries it.

mails labels delete lbl_01JABC --yes

Needs a key with the manage scope. API: DELETE /v1/labels/{id}. Asks first in a terminal, and needs --yes anywhere else.

Search

Search received and sent email.

mails search

Search received and sent email.

Full-text search over received and sent mail (subject, body text and addresses), newest first. Each hit says whether it was received or sent and carries a snippet around the match. Never leaves the workspace; a key tied to one agent searches that agent's mail; a test key searches test mail only and a live key live mail only.

mails search "refund"
mails search invoice --from billing@acme.com --has-attachment --json

Needs a key with the read scope. API: GET /v1/search. --all follows every page.

Events

Every event, and a live tail.

mails events list

List events. Also: mails events ls.

mails events list --event-type message.received --limit 5

Needs a key with the read scope. API: GET /v1/events. --all follows every page.

mails events get

Show one event.

mails events get evt_01JABC

Needs a key with the read scope. API: GET /v1/events/{id}.

mails events redeliver

Send an event to your webhooks again.

Re-dispatches a stored event to all matching webhook endpoints. Needs a key that is not tied to an agent, since an endpoint can receive every agent's mail (403 insufficient_scope).

mails events redeliver evt_01JABC

Needs a key with the manage scope. API: POST /v1/events/{id}/redeliver.

mails events tail

Print events as they happen. Also: mails events listen, mails events stream.

Follows the workspace's live event stream and prints one line per event (one JSON object per line when piped or with --json). It reconnects by itself and never misses or repeats an event. Stop it with Ctrl-C, --count or --timeout.

mails events tail
mails events tail --type message.received,reply.received
mails events tail --json --count 1 --timeout 60 | jq .type

Webhooks

Endpoints, deliveries, and forwarding events to localhost.

mails webhooks list

List webhook endpoints. Also: mails webhooks ls.

mails webhooks list

Needs a key with the read scope. API: GET /v1/webhooks. --all follows every page.

mails webhooks create

Register an HTTPS endpoint to receive events.

Registers an HTTPS endpoint to receive events. The signing_secret is returned ONCE — use it to verify signatures. An empty event_types list is refused with 422 invalid_param_value: an endpoint with no event types would never be sent anything. Closed to apps connected by sign-in (403 connected_app_not_allowed): use the dashboard, an API key or the mails CLI.

The signing secret is shown once, in this result. Keep it: it is how your handler verifies deliveries.

mails webhooks create https://api.acme.com/hooks/mails --event-types message.received,reply.received

Needs a key with the manage scope. API: POST /v1/webhooks.

mails webhooks get

Show one webhook endpoint.

mails webhooks get whe_01JABC

Needs a key with the read scope. API: GET /v1/webhooks/{id}.

mails webhooks update

Change a webhook endpoint, or switch it off.

Changes an endpoint's URL, event types, description or active state. An empty event_types list is refused with 422 invalid_param_value, as on create. An app connected by sign-in may change everything except url (403 connected_app_not_allowed).

mails webhooks update whe_01JABC --active false

Needs a key with the manage scope. API: PATCH /v1/webhooks/{id}.

mails webhooks delete

Delete a webhook endpoint and its delivery history. Also: mails webhooks rm.

Deletes the endpoint and its delivery history.

mails webhooks delete whe_01JABC --yes

Needs a key with the manage scope. API: DELETE /v1/webhooks/{id}. Asks first in a terminal, and needs --yes anywhere else.

mails webhooks rotate-secret

Issue a new signing secret (the old one keeps working for 24 hours).

Issues a new signing secret, returned once. For the next 24 hours every delivery's X-Mails-Signature carries a v1 signature from the new secret and one from the previous secret, so a receiver can switch over without failing a delivery. Verify by accepting the header when any v1 matches. Rotating again within the 24 hours retires the oldest secret.

mails webhooks rotate-secret whe_01JABC

Needs a key with the manage scope. API: POST /v1/webhooks/{id}/rotate-secret.

mails webhooks deliveries

List delivery attempts for a webhook endpoint.

mails webhooks deliveries whe_01JABC --limit 20

Needs a key with the read scope. API: GET /v1/webhooks/{id}/deliveries. --all follows every page.

mails webhooks test

Send a test event to a webhook endpoint.

Fires a synthetic webhook.test event at the endpoint and reports the delivery result.

mails webhooks test whe_01JABC

Needs a key with the manage scope. API: POST /v1/webhooks/{id}/test.

mails webhooks replay

Send the event behind a past delivery again.

Re-sends the event behind a previous delivery attempt to that delivery's endpoint only. Other endpoints subscribed to the event are not sent it again; to re-send an event to every subscribed endpoint, use POST /v1/events/{id}/redeliver.

mails webhooks replay whd_01JABC

Needs a key with the manage scope. API: POST /v1/webhook-deliveries/{id}/replay.

mails webhooks listen

Forward live events to a local address, signed like real deliveries. Also: mails webhooks forward.

Posts every event to the address you give (for example your handler on localhost), with the same body and the same X-Mails-Signature, X-Mails-Event-Id and X-Mails-Event-Type headers a real webhook delivery carries. No tunnel and no public address needed. Sign with your endpoint's real secret via --secret-env, or let the CLI make one for this session and print it for your handler to use.

mails webhooks listen --forward-to http://localhost:3000/webhooks/mails
mails webhooks listen --forward-to http://localhost:3000/hook --events message.received,reply.received
MAILS_WEBHOOK_SECRET=… mails webhooks listen --forward-to http://localhost:3000/hook   # reuse your endpoint's secret

Domains

Your own sending domains and their DNS records.

mails domains list

List your domains. Also: mails domains ls.

mails domains list

Needs a key with the read scope. API: GET /v1/domains.

mails domains create

Add your own sending domain and get the DNS records to create. Also: mails domains add.

Registers a bring-your-own sending domain (paid plans). Returns the DNS records to create at your registrar — records-only verification, no nameserver changes. Agents whose address is on a VERIFIED custom domain send under their own identity instead of the shared workspace subdomain. A domain that is already added, to this workspace or to another, is refused with 400 duplicate_resource.

mails domains create mail.acme.com

Needs a key with the manage scope. API: POST /v1/domains.

mails domains get

Show a domain and its DNS records.

mails domains get dom_01JABC

Needs a key with the read scope. API: GET /v1/domains/{id}.

mails domains delete

Remove a domain. Also: mails domains rm.

Agents with addresses on this domain stop sending: every send from them is refused with 422 domain_not_verified until the domain is added and verified again, or the agent is recreated on your workspace's mails.ai subdomain. It is never sent from another domain instead.

mails domains delete dom_01JABC --yes

Needs a key with the manage scope. API: DELETE /v1/domains/{id}. Asks first in a terminal, and needs --yes anywhere else.

mails domains verify

Check a domain's DNS records now.

Re-checks every DNS record and updates per-record + overall status. Each call is an attempt: one that does not pass counts toward failed, 20 in a row mark the domain failed, and the count starts over on success or after a day without a call. Polling is rarely needed.

mails domains verify dom_01JABC

Needs a key with the manage scope. API: POST /v1/domains/{id}/verify.

API keys

Create, list and revoke API keys.

mails api-keys list

List API keys (prefixes only). Also: mails api-keys ls.

Lists the workspace's API keys, newest first, without their plaintext. A key tied to one agent lists only the keys tied to that same agent.

mails api-keys list

Needs a key with the read scope. API: GET /v1/api-keys. --all follows every page.

mails api-keys create

Create an API key.

Creates a new API key. The plaintext key is returned ONCE in this response and never again. Closed to apps connected by sign-in (403 connected_app_not_allowed): use the dashboard, an API key or the mails CLI.

The API shows a new key only once, so say where it goes: --save-as <profile> stores it as a profile, --key-file <path> writes it to a private file, --show-key prints it. Without one of them nothing is created.

mails api-keys create --mode test --save-as test
mails api-keys create --name "Production server" --scopes send,read --key-file ./mails.key
mails api-keys create --name "CI" --show-key

Needs a key with the manage scope. API: POST /v1/api-keys.

mails api-keys revoke

Revoke an API key at once. Also: mails api-keys delete, mails api-keys rm.

Revokes a key immediately. Idempotent — revoking an already-revoked key returns its existing revoked_at. A test key cannot revoke a live key (403 live_mode_required): revoke it with a live key or in the dashboard.

mails api-keys revoke key_01JABC --yes

Needs a key with the manage scope. API: DELETE /v1/api-keys/{id}. Asks first in a terminal, and needs --yes anywhere else.

Connected apps

List and revoke the apps connected by signing in.

mails connected-apps list

List the apps connected by signing in, this CLI among them. Also: mails connected-apps ls.

The apps connected to this workspace by signing in, whoever in it connected them: the mails CLI and apps such as Claude, ChatGPT or Cursor. Only those that can still act are listed, newest first: one revoked, or whose tokens have all expired or been signed out, is not. Settings › Connected apps in the dashboard shows the same apps to everyone in the workspace.

mails connected-apps list

Needs a key with the manage scope. API: GET /v1/oauth/grants. --all follows every page.

mails connected-apps revoke

Revoke a connected app at once. Also: mails connected-apps delete, mails connected-apps rm.

Ends the sign-in, as Revoke in Settings › Connected apps does: every access and refresh token it was issued stops working at once, and the app has to be approved again to get back in. The API keys and webhook endpoints it created, and the webhook signing secrets it was shown, stay; the response counts them, so revoke and rotate those yourself.

API keys and webhooks the app created, and webhook signing secrets it was shown, stay: the result counts them, so revoke and rotate those too.

mails connected-apps revoke oag_01JABC --yes

Needs a key with the manage scope. API: DELETE /v1/oauth/grants/{id}. Asks first in a terminal, and needs --yes anywhere else.

Suppressions

Addresses that must not be mailed, and the allow list.

mails suppressions list

List allow entries, or check one address with --address. Also: mails suppressions ls.

Three answers from one route. With ?address=, the suppression status of that address. With ?view=suppressed, which of your own recent recipients are suppressed for you, and why (up to 500, in one page; addresses are stored hashed, so the list itself cannot be browsed). Without either, the workspace allowlist (paginated).

mails suppressions list
mails suppressions list --address jordan@example.com

Needs a key with the read scope. API: GET /v1/suppression. --all follows every page.

mails suppressions allow

Record that a suppressed recipient has agreed to receive mail again.

Attests that a recipient consents, overriding non-hard-bounce suppression for that address.

mails suppressions allow jordan@example.com --attestation "Reconfirmed opt-in in account settings on 2026-06-20."

Needs a key with the manage scope. API: POST /v1/suppression/allow.

mails suppressions revoke

Remove an allow entry. Also: mails suppressions delete, mails suppressions rm.

mails suppressions revoke sup_01JABC --yes

Needs a key with the manage scope. API: DELETE /v1/suppression/allow/{id}. Asks first in a terminal, and needs --yes anywhere else.

Metrics

Counts over time.

mails metrics

Sent, delivered, bounced, complained, received and reply counts over time.

Counts of sent, delivered, bounced, complained, received and reply messages per day or hour (UTC). Defaults to the last 30 days by day, or the last 48 hours by hour; at most 366 days or 744 hours per call. A test key counts test mail only and a live key live mail only.

mails metrics --from 2026-10-01 --to 2026-10-08 --interval day

Needs a key with the read scope. API: GET /v1/metrics.

Logs

Audit log.

mails logs

Show the audit log of changes made in the workspace.

Read-only audit trail of state-changing operations, and of requests the API refused with a 4xx once it knew the workspace (category api, action request.refused). A refusal before that, such as a missing or unknown key, is not recorded. The same refusal again (the same key, method, path and code) is recorded at most once a minute, a 429 once a minute per code, and a workspace records at most 30 refusals a minute.

mails logs --limit 20
mails logs --category api_key --json

Needs a key with the read scope. API: GET /v1/logs. --all follows every page.

Usage

Usage this billing period.

mails usage

Show this billing period's usage against the plan's limits.

Returns metered usage for the current billing period plus the workspace's tier caps. A key tied to one agent cannot read it (403 insufficient_scope): usage and costs are counted for the whole workspace, and GET /v1/metrics counts that agent's mail.

mails usage

Needs a key with the read scope. API: GET /v1/billing/usage.

Reputation

Sender reputation.

mails reputation

Show sender reputation for the workspace or one agent.

Workspace-wide reputation when called without agent_id, or per-agent stats when an agent id/name is supplied.

mails reputation
mails reputation --agent-id hello

Needs a key with the read scope. API: GET /v1/reputation.

Billing

Subscription.

mails billing portal

Get a link to manage or start the subscription.

Returns a Stripe Billing Portal URL when already subscribed, otherwise a Checkout URL to subscribe. A workspace on an active paid plan with no Stripe subscription on file gets 409 billing_state_inconsistent instead of a Checkout URL, since subscribing again would bill it twice: contact support@mails.ai.

mails billing portal

Needs a key with the manage scope. API: POST /v1/billing/portal.

Health

API status.

mails health

Check that the API is up.

Liveness probe. Without authentication it returns status (healthy when the database answers and accepts writes, else degraded) and timestamp. The dependency detail (database, sender, classifier) is returned only to internal callers.

mails health

Works without signing in. API: GET /api/health.

Utility

Checks, shortcuts, and setting up AI clients.

mails send

Send an email.

Sends an email from one of your agents. With a mk_test_ key the message is stored and its message.sent event reaches your webhooks (marked test_mode: true), but no email is sent and nothing is billed. Quota, suppression and rate-limit refusals are skipped, and a message the cold-email firewall would refuse comes back 201 with classifier_warning instead.

mails send --to jordan@example.com --subject "Your order shipped" --text "It is on its way."
mails send --from hello --to a@example.com,b@example.com --subject "Hello" --html-file ./hello.html --attach ./invoice.pdf
cat message.json | mails send --data -

Needs a key with the send scope. API: POST /v1/messages.

mails doctor

Check the CLI, your sign-in and the connection, and say how to fix what is wrong.

Checks the Node version, the CLI version, where your credential comes from, whether the API answers, your clock, what your key is allowed to do, and whether your custom domains are verified. Exits 1 when something is broken.

mails doctor
mails doctor --json

mails mcp install

Add the mails.ai MCP server to Claude, Claude Code, Cursor, Codex or VS Code. Also: mails mcp add.

Connects an AI client to the hosted mails.ai MCP server, so it can send and read email with your workspace. By default the client signs in through your browser; with --auth key the config names the MAILS_API_KEY environment variable instead. A key is never written into a config file. Any file this changes is copied to a .bak-<time> file first. --print shows what would be done and changes nothing.

mails mcp install --client claude-code
mails mcp install --client cursor --scope project
mails mcp install --client codex --auth key
mails mcp install --client vscode --print

Works without signing in.

mails open

Open the dashboard (or one of its pages) in your browser.

mails open
mails open api-keys
mails open webhooks --no-browser

Works without signing in.

mails docs

Open the documentation, or the API reference.

mails docs
mails docs api
mails docs openapi --no-browser

Works without signing in.

mails update

Check for a newer CLI and print the command that installs it. Also: mails upgrade.

Asks npm for the newest version. It only prints the command to run: the CLI never changes its own files.

mails update

Works without signing in.

mails completion

Print a shell completion script (bash, zsh or fish).

The script asks the CLI itself for the words that fit, so it always matches the installed version: commands, flags, allowed values and your profile names.

source <(mails completion zsh)
mails completion bash >> ~/.bashrc
mails completion fish > ~/.config/fish/completions/mails.fish

Works without signing in.

mails commands

Print every command (--json: the whole tree with flags and examples, for agents).

With --json (or when piped) this is the machine-readable map of the CLI: every command with its arguments, flags, types, allowed values, examples, the API route behind it and the key scope it needs. Give a few words to see only that part, e.g. mails commands emails.

mails commands
mails commands --json
mails commands webhooks --json | jq '.commands[].command'

Works without signing in.

Global options

Every command accepts these. --dry-run acts only on the commands that call one API route.

Environment variables