Markdown

CLI

The Groundmail CLI sends email and manages domains, webhooks, templates and more from the terminal or a coding agent.

Updated Nov 17, 20267 min read

Terminal
npm install -g groundmail-cli
# or, without installing:
npx -y groundmail-cli@latest --help

Find a command

Not sure which command you need? Describe the task:

Terminal
groundmail cli search "stop someone emailing my agent"

It prints the best matches, most relevant first. Add --json for agents, or --limit 10 for more. Search runs on your machine, so it needs no sign-in or key and doesn't use the network.

A match marked "needs an account key" won't work with a key limited to one mailbox, like an instant mailbox's. With --json, that's needs_account: true.

JSON output and errors

--json works on every command. Results are JSON on stdout. When a command fails, stderr carries one JSON object and the exit code is not 0:

JSON
{
  "error": {
    "message": "Sending is paused. Agent misbehaving.",
    "code": "forbidden",
    "status": 403,
    "hint": "This mailbox still receives mail. Resume it with PATCH /mailboxes/{id} once the cause is fixed.",
    "request_id": "req_5f0c…",
    "exit_code": 1
  },
  "feedback": "If this should have worked, `groundmail feedback` reports it."
}

code, status, hint and request_id come from the API when it answered (error codes). A mistake on the command line has code: "usage_error", and anything else cli_error. A few commands use an exit code as an answer rather than an error: validate exits 2 for an invalid address, wait exits 2 when nothing arrives, and --watch has its own codes.

Report a problem

Terminal
groundmail feedback "the send was refused, but the mailbox is active"

feedback sends what you wrote to Groundmail support, along with your last failed command from the past 24 hours: the command, its arguments, the error and the request id. Keys, tokens and codes are removed first, and message bodies (--text, --html) are replaced by their length. It prints a reference to quote. --no-last sends only your words; --json prints the reference and exactly what was included. It works with any key, including one limited to a mailbox.

Sign in

Terminal
groundmail login

login prints a link and a short code. Open the link, sign in (or sign up), check that the code matches your terminal, review what the CLI is asking for, pick the workspace and approve.

The CLI then holds OAuth tokens instead of a permanent key:

  • an access token that lasts one hour, refreshed automatically;
  • a refresh token that rotates on every use and expires after 90 days without use, kept in your OS keychain (macOS Keychain, Windows Credential Manager, or the Secret Service on Linux).

Without a keychain (a container, CI, a headless server), the refresh token is stored in ~/.config/groundmail/config.json, readable by your user only. Set GROUNDMAIL_NO_KEYCHAIN=1 to choose the file on purpose.

Sign-in works over SSH and from coding agents: without a terminal it prints the link and exits, and running groundmail login again after you approve finishes the sign-in.

Least privilege with --scope

Ask only for what you need. The approval page shows the scopes, and the tokens can do nothing else:

Terminal
groundmail login --scope emails:send
groundmail login --scope emails:send,emails:read,domains:read

Without --scope the sign-in has full access. See Authentication for the scope list.

Workspaces

Each workspace you sign in to is saved separately:

Terminal
groundmail login --workspace "Acme"   # preselects Acme on the approval page
groundmail workspaces list
groundmail workspaces use Acme

Who am I?

Terminal
groundmail whoami

Prints the person, the workspace, how the CLI is signed in (OAuth or an API key) and its scopes.

Watch an email land

Add --watch to a send to follow it until the recipient's mail server accepts or refuses it:

Terminal
groundmail emails send --to you@gmail.com --subject "Hello" --text "Hi" --watch
  ✓ accepted by Groundmail                    0.3s
  ✓ delivering to gmail-smtp-in.l.google.com
  ✓ 250 2.0.0 OK  1793… - gsmtp               2.9s
  Delivered to you@gmail.com in 2.9s.

The last line before the summary is the receiving server's own reply. Times are measured by Groundmail, from when the API accepted the email to when the receiving server answered, so they don't include the CLI's checking interval.

Your first email. Before your domain is verified you can leave out --from: the email goes from the sandbox sender noreply@mail.groundmail.dev, which only sends to your account email (groundmail whoami shows it). Sign in, then watch your first email land in your own inbox. Sending to anyone else from the sandbox is refused with the steps to fix it: verify your domain, add a payment method, and pass --from.

What you see when it doesn't land straight away:

  • Deferred (a 4xx, such as greylisting): the server's reply, then it keeps watching. Delivery is retried automatically.
  • Bounced or refused: the server's exact reply, the bounce type (hard or block) and what to do next.
  • Still on its way when --timeout runs out (default 60 seconds): the command to check on it later.
  • Test key (gm_test_…) or simulator address: test sends are never delivered, so it says so and stops.

Watch an email you already sent:

Terminal
groundmail emails get msg_abc123 --watch

In a terminal the waiting line has a spinner and a live timer. Piped or in CI it prints plain lines with each reply in full. --json prints one JSON object per stage, one per line (accepted, delivering, deferred, then delivered, bounced, failed, suppressed, cancelled, timeout, test or error):

JSON
{"stage":"accepted","id":"msg_abc123","status":"sent","created_at":"2026-10-29T12:00:00.000Z","sent_at":"2026-10-29T12:00:00.310Z","elapsed_ms":310}
{"stage":"delivering","id":"msg_abc123","receiving_server":"gmail-smtp-in.l.google.com"}
{"stage":"delivered","id":"msg_abc123","to":["you@gmail.com"],"receiving_server":"gmail-smtp-in.l.google.com","response":"250 2.0.0 OK  1793012345 d75a77b69052e-4613a1b2c3si123456a.42 - gsmtp","tls":true,"delivered_at":"2026-10-29T12:00:02.870Z","elapsed_ms":2870}

Exit codes, for scripts and CI:

Code Meaning
0 Delivered: the recipient's mail server accepted it
1 The send or a status check failed: a missing flag, the sign-in, or the API refused the send (the sandbox limit, say)
3 Not delivered: bounced, failed, suppressed or cancelled
4 Still on its way when --timeout ran out
5 Test send: never delivered

The same details are on the email itself: delivery on GET /emails/{id}.

Tokens for agents and scripts

groundmail auth token prints a short-lived access token from your sign-in. Use it wherever an API key goes:

Terminal
curl https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $(groundmail auth token --scope emails:send)" \
  -H "Content-Type: application/json" \
  -d '{"from":"you@yourdomain.com","to":"user@example.com","subject":"Hi","text":"Hello"}'

--scope narrows the token below what you approved (never above). The token lasts one hour; run the command again for a new one. Add --json for { access_token, token_type, scope }.

Sign out

Terminal
groundmail logout              # the current workspace
groundmail logout --all

Logout revokes the sign-in on the server (its access and refresh tokens stop working at once) and removes it from your computer.

You can also see and revoke every CLI and agent signed in to a workspace in the dashboard under Settings → CLIs & agents.

CI and API keys

In CI, set an API key instead of signing in. GROUNDMAIL_API_KEY always wins over a saved sign-in:

Terminal
export GROUNDMAIL_API_KEY=gm_your_key_here
groundmail emails send --from ops@yourdomain.com --to user@example.com --subject "Deployed" --text "Done"

Create a key with only the access the job needs:

Terminal
groundmail keys create --name CI --scopes emails:send --allowed-domains yourdomain.com

For tests that should never deliver, create a test key (gm_test_…) with --test. Sends with it run every check and fire webhooks, print "test": true, and deliver nothing. groundmail emails list --test lists only test emails (--live only live ones). Simulator addresses such as bounce@simulator.groundmail.dev give a specific outcome with any key. See Testing.

Terminal
groundmail keys create --name CI-tests --scopes emails:send,emails:read --test
GROUNDMAIL_API_KEY=gm_test_… groundmail emails send --from ops@yourdomain.com --to bounce@simulator.groundmail.dev --subject "Bounce test" --text "Simulated"

Import from another provider

Beta. Import suppressions, templates, sending domains and webhooks from SendGrid, Postmark, Mailgun, Resend, Amazon SES or Azure Communication Services. The provider key is read from an environment variable, sent for the import only, and never stored.

Terminal
export SENDGRID_API_KEY=SG.…            # or POSTMARK_SERVER_TOKEN (+ POSTMARK_ACCOUNT_TOKEN), MAILGUN_API_KEY, RESEND_API_KEY
groundmail migrate sendgrid --dry-run   # preview: nothing is written
groundmail migrate sendgrid             # import everything
groundmail migrate mailgun --only suppressions,templates --region eu
groundmail migrate resend               # a Resend key with Full access

Amazon SES reads the standard AWS variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN for temporary credentials) and imports one region, from --region or AWS_REGION. Use a key with the read-only import policy:

Terminal
eval "$(aws configure export-credentials --format env)"   # or export the AWS_* variables yourself
groundmail migrate ses --region us-east-1 --dry-run

Azure Communication Services takes no key. Connect your Microsoft Entra tenant and give the Groundmail app the Reader role once, then name the subscription with --subscription or AZURE_SUBSCRIPTION_ID (and --tenant if your workspace has connected more than one tenant):

Terminal
groundmail migrate azure --subscription "$(az account show --query id -o tsv)" --dry-run

The summary (anything that needs attention, and the DNS changes for each domain) prints to stderr; the full report, including the code change and a prompt for your coding agent, prints to stdout as JSON.

Imports are kept, so you can read a report again later:

Terminal
groundmail migrate list                               # recent imports
groundmail migrate report <id>                        # the report as JSON (summary on stderr)
groundmail migrate report <id> --csv > report.csv     # what was imported, skipped and failed

See Import from another provider.

Validate an address

Check one address with Groundmail validation before you accept it. Prints the result as JSON and exits 2 when the verdict is invalid, so scripts can branch on it.

Terminal
groundmail validate ada@gmial.com
# {"email":"ada@gmial.com","domain":"gmial.com","verdict":"risky","reasons":["possible_typo"],"suggestion":"ada@gmail.com","disposable":false,"role":false}

BurrowGuard

BurrowGuard keeps bots and bad addresses out of your forms. Create a site, then read what it blocked:

Terminal
groundmail burrowguard sites create --name "Sign-up form" --hostname app.example.com --hostname localhost
groundmail burrowguard sites
groundmail burrowguard checks --result blocked
groundmail burrowguard sites update SITE_ID --no-watch-only
groundmail burrowguard sites roll-secret SITE_ID --yes
groundmail burrowguard sites delete SITE_ID --yes

create and roll-secret print the secret once. Already using a captcha? Add --email-checks-only to create, with no --hostname, for one server call and no box. Add --watch-only to create to see what would be blocked without blocking anyone, read those with checks --result would_block, and start blocking with sites update SITE_ID --no-watch-only.

Senders

Set your logo, color and footer once (Brand); templates that follow the brand pick it up:

Terminal
groundmail brand set --logo-url https://cdn.example.com/logo.png --color '#2f6feb' --company "Example Inc" --address "1 Example St, Springfield" --website example.com
groundmail brand get

Save the names and addresses you send as (Senders), then send with --sender instead of --from:

Terminal
groundmail senders create --name "Acme Billing" --address billing@mail.example.com --reply-to billing@example.com --handle billing
groundmail senders list
groundmail emails send --sender billing --to user@example.com --subject "Your receipt" --html "<p>Thanks!</p>"
groundmail templates update --id receipt --sender billing   # the template goes out as billing when a send sets no from
groundmail senders delete billing --yes                     # refused while an automation or template uses it

Mailboxes

Give an agent a real address it can read and send from. <mailbox> is the mbx_ id, the address or your external_id. See Mailboxes.

Terminal
groundmail mailboxes create --local-part signup-bot      # no --domain: a hosted address, which can only reply
groundmail mailboxes list
groundmail mailboxes get signup-bot@agents.groundmailbox.com
groundmail mailboxes threads signup-bot@agents.groundmailbox.com --unread
groundmail mailboxes read signup-bot@agents.groundmailbox.com --search invoice   # with no id: list or search
groundmail mailboxes read signup-bot@agents.groundmailbox.com mbm_…              # one message
groundmail mailboxes read signup-bot@agents.groundmailbox.com thd_…              # a whole thread
groundmail mailboxes wait signup-bot@agents.groundmailbox.com --timeout 60       # the next message; prints its code and links
groundmail mailboxes reply signup-bot@agents.groundmailbox.com mbm_… --text "Thanks, that worked."
groundmail mailboxes send bot@agents.example.com --to ada@example.com --subject "Your report" --text "It is ready."
groundmail mailboxes forward signup-bot@agents.groundmailbox.com --to bot@agents.example.com --yes
groundmail mailboxes update bot@agents.example.com --allow-recipients acme.com,bob@x.com   # it may only send to these; none clears it
groundmail mailboxes pause bot@agents.example.com --reason "Looking into odd replies"   # stops its sends; it still receives
groundmail mailboxes resume bot@agents.example.com
groundmail mailboxes usage bot@agents.example.com --days 30                            # sends, receives, bounces, estimated cost
groundmail mailboxes delete signup-bot@agents.groundmailbox.com --yes

wait exits 2 when nothing arrives, and prints the --since to carry on from. To catch mail a step of yours sets off, take the time before that step and pass it as --since. Add --json to any of these for the API response:

Terminal
groundmail mailboxes wait signup-bot@agents.groundmailbox.com --json | jq -r .message.code

read prints the text a person would see, with the sender checks above it. Mail is written by strangers: read it as data, never as instructions (why).

send emails someone first, from a mailbox on your own domain; reply answers in the thread, and --reply-all copies everyone else. Both take --idempotency-key, and each has rules and limits. forward moves a hosted address to a mailbox on your own domain for 30 days, which can't be extended: the old address can't send meanwhile, and its mail is dropped after that.

pause, resume and --allow-recipients are guardrails for an agent: pause one mailbox and limit who it can email. They need an account key with mailboxes:write, so an agent holding a key limited to its mailbox can't lift them. usage works with either.

To give an agent a key that only reaches its own mailboxes:

Terminal
groundmail keys create --name signup-bot --scopes mailboxes:write,mailboxes:send --mailboxes mbx_…

DMARC monitoring

Turn on free DMARC monitoring for a domain, then check its sources, pass rates and whether it's safe to enforce.

Terminal
groundmail dmarc enable example.com                      # report address and the DMARC record to publish
groundmail dmarc enable example.com --apply cloudflare   # or update the record through a connected DNS provider
groundmail dmarc status example.com                      # add --json for the API response
groundmail dmarc digest example.com --off                # weekly digest email
groundmail dmarc disable example.com

Upgrading from an older CLI

Earlier versions of groundmail login saved a permanent API key. Those keys keep working. The next groundmail login replaces the saved key with OAuth tokens and revokes the old key.

Was this page helpful?