Command Reference

Authentication

envloped login

Authenticate with your Envloped API key.

envloped login --api-key en_xxxxx       # Direct flag
envloped login                          # Interactive prompt

envloped logout

Clear stored credentials for the current profile.

envloped logout
envloped logout --profile staging

envloped whoami

Show the authenticated user and organization info.

envloped whoami
envloped whoami --json

Sending Emails

envloped send

Send an email from the terminal.

# Inline text (with sender name)
envloped send --from "Your Name <hello@mydomain.com>" --to user@example.com \
  --subject "Welcome!" --text "Hello world"

# HTML body
envloped send --from "Your Name <hello@mydomain.com>" --to user@example.com \
  --subject "Welcome!" --html "<h1>Hello</h1>"

# From file
envloped send --from "Your Name <hello@mydomain.com>" --to user@example.com \
  --subject "Newsletter" --html-file template.html

# JSON stdin (best for CI/CD and agents)
echo '{"from":"Your Name <a@b.com>","to":"c@d.com","subject":"Hi","text":"Hello"}' | envloped send --stdin

# Multiple recipients
envloped send --from a@b.com --to user1@example.com --to user2@example.com \
  --subject "Broadcast" --text "Hello all"

# Dry run (validate without sending)
envloped send --from a@b.com --to user@example.com --subject "Test" --text "Hi" --dry-run

Email Management

envloped emails list

List sent emails with optional filtering.

envloped emails list
envloped emails list --status sent
envloped emails list --status failed --limit 10
envloped emails list --search "welcome"
envloped emails list --json

envloped emails get [id]

Get details for a specific email.

envloped emails get abc123
envloped emails get abc123 --json

Domain Management

envloped domains list

List all domains for your account.

envloped domains list
envloped domains list --json

envloped domains add [domain]

Add a new domain and display DNS records for verification.

envloped domains add mydomain.com

envloped domains verify [domain]

Check the verification status of a domain.

envloped domains verify mydomain.com

envloped domains records [domain]

Re-display DNS records needed to verify a domain.

envloped domains records mydomain.com

Contacts

Manage marketing contacts (subscribers). See the Contacts API for the underlying endpoints.

envloped contacts list

List contacts with optional filtering.

envloped contacts list
envloped contacts list --status subscribed
envloped contacts list --list ls_newsletter --search "acme"
envloped contacts list --limit 50 --page 2 --json

envloped contacts get [id]

Show a contact's details and its list memberships.

envloped contacts get ct_abc123
envloped contacts get ct_abc123 --json

envloped contacts create [email]

Create a contact, optionally adding it to lists.

envloped contacts create jane@example.com
envloped contacts create jane@example.com --first-name Jane --last-name Doe
envloped contacts create jane@example.com --list ls_newsletter --list ls_beta

envloped contacts update [id]

Update a contact's name or status.

envloped contacts update ct_abc123 --first-name Jane
envloped contacts update ct_abc123 --status unsubscribed

envloped contacts delete [id]

Permanently delete a contact (irreversible GDPR hard delete). Requires confirmation unless --force is used.

envloped contacts delete ct_abc123
envloped contacts delete ct_abc123 --force

envloped contacts export

Export all contacts as CSV to stdout or a file.

envloped contacts export
envloped contacts export --output contacts.csv

envloped contacts import [file]

Bulk create or update contacts from CSV or JSON. Reads stdin when the file argument is omitted or -.

envloped contacts import contacts.csv
envloped contacts import contacts.csv --list ls_abc123 --member-status approved
cat contacts.json | envloped contacts import --format json

CSV shape. A header row is required. email, first_name, last_name, member_status and list_ids (; or | separated) map to fields; every other column becomes an attribute under its verbatim header, validated against your contact fields. A blank attribute cell is omitted rather than sent, because the server reads "" as clear this attribute. Read-only export columns (id, status, consent_*, created_at) are ignored, and the ignored set is printed — so an export → import round trip does not become a wall of unknown_fields.

Reporting. Two tables follow the counts: rows that did not import, and rows that imported with data dropped (unknown fields, invalid fields, invalid list ids). The second table matters — those rows succeed, so it is the only place a dropped list_id is visible, and a silently dropped list id is how you mail the wrong audience. The command exits non-zero if any row failed.

Requests larger than --batch-size are chunked, and each chunk gets its own suffixed idempotency key (key-1, key-2); one key reused across chunks would make chunk 2 look like a replay of chunk 1 and return chunk 1's receipt.

envloped contacts activity [id]

Show a contact's per-campaign engagement history — every campaign they were sent, with opens, clicks, bounces, complaints, and unsubscribes, plus totals.

envloped contacts activity ct_abc123
envloped contacts activity ct_abc123 --json

The table shows proxy-excluded opens. Raw opens are reported separately in the footer, because Apple Mail Privacy Protection prefetches images and inflates them.

Lists

Manage contact lists and membership. See the Lists API for the underlying endpoints.

envloped lists list

List all lists with member counts.

envloped lists list
envloped lists list --json

envloped lists get [id]

Show a list's details.

envloped lists get ls_newsletter

envloped lists create [name]

Create a list.

envloped lists create "Newsletter"
envloped lists create "Newsletter" --description "Weekly product digest"

envloped lists update [id]

Rename or re-describe a list.

envloped lists update ls_newsletter --name "Weekly Newsletter"
envloped lists update ls_newsletter --description "Every Monday"

envloped lists delete [id]

Soft-delete a list (contacts are untouched). Requires confirmation unless --force is used.

envloped lists delete ls_newsletter
envloped lists delete ls_newsletter --force

envloped lists members [id]

List the members of a list.

envloped lists members ls_newsletter
envloped lists members ls_newsletter --limit 100 --page 2

envloped lists add [id] [contactID...]

Add one or more existing contacts to a list.

envloped lists add ls_newsletter ct_abc123
envloped lists add ls_newsletter ct_abc123 ct_def456

envloped lists remove [id] [contactID...]

Remove one or more contacts from a list (membership only — the contacts are not deleted).

envloped lists remove ls_newsletter ct_def456

Segments

Build and evaluate audience definitions. See the Segments API for the definition grammar.

envloped segments list|get|count

envloped segments list
envloped segments get sg_abc123
envloped segments count sg_abc123
envloped segments count sg_abc123 --quiet     # bare integer, pipeable

envloped segments create [name]

envloped segments create "Singapore 25-35" --definition-file ./segment.json
cat segment.json | envloped segments create "Singapore 25-35" --stdin

The three input modes are mutually exclusive and one is required. Prefer a file: a definition is a nested boolean tree, and a shell will mangle the quoting on a --definition string. Only JSON syntax is checked locally — the grammar is owned by the API, and duplicating it in the CLI is how two systems drift into disagreeing about who is in an audience.

A 422 prints every entry from the response's errors array on its own line as code: path — message, so a rejected tree tells you which leaf to fix.

envloped segments update [id]

envloped segments update sg_abc123 --name "Singapore 25-40"
envloped segments update sg_abc123 --definition-file ./revised.json
envloped segments update sg_abc123 --clear-description

Only flags you pass are sent. Replacing the definition changes who a campaign targeting this segment will reach — a segment stores a rule, not a snapshot, so a scheduled campaign resolves the new rule when it fires. The command says so when you change one.

envloped segments delete [id]

envloped segments delete sg_abc123
envloped segments delete sg_abc123 --yes

Soft delete. Campaigns that already sent keep their records; campaigns still targeting it lose an audience source, and a send whose only include source is gone fails with dead_source rather than quietly mailing nobody. Confirms first, unless --yes or a non-TTY stdout.

envloped segments preview [id]

Count and sample a definition. With an id it previews a saved segment; without one it evaluates an unsaved tree without persisting it — the try-before-you-commit loop.

envloped segments preview sg_abc123 --limit 25
envloped segments preview --definition-file ./candidate.json

Campaigns

Draft, target, test, and send marketing campaigns. See the Campaigns API.

envloped campaigns list|get|cancel

envloped campaigns list --page 1 --limit 25
envloped campaigns get cp_abc123
envloped campaigns cancel cp_abc123

envloped campaigns create [name]

envloped campaigns create "August newsletter" \
  --from "You <hello@yourdomain.com>" \
  --subject "What shipped in August" \
  --html-file ./newsletter.html \
  --include segment:sg_abc123 --exclude segment:sg_churned

envloped campaigns update [id]

Takes the same content flags as create, plus --name. Nullable fields are three-state: an unset flag is omitted, --reply-to "" clears the column, and any other value replaces it.

envloped campaigns audience|preview

envloped campaigns audience cp_abc123                                   # show
envloped campaigns audience cp_abc123 --include segment:sg_abc123       # replace
envloped campaigns preview cp_abc123 --limit 25

audience with no --include/--exclude reads; with either, it replaces the whole audience rather than appending. preview resolves the audience to an eligible recipient count plus a sample, applying the unsubscribe and suppression gates that a raw segment count does not.

envloped campaigns test [id]

envloped campaigns test cp_abc123 --to you@yourdomain.com

envloped campaigns send [id]

envloped campaigns send cp_abc123
envloped campaigns send cp_abc123 --at 2026-08-11T02:00:00Z
envloped campaigns send cp_abc123 --yes        # CI

This is the one CLI verb that reaches thousands of inboxes and cannot be undone, so it confirms first — printing the campaign, subject, sender, and the eligible recipient count from the audience preview before asking. The prompt is skipped automatically when stdout is not a terminal, so CI is unaffected without --yes.

A refused send renders the audience snapshot the error carries — included, excluded, eligible, and the per-reason drop breakdown — not just the message.

envloped campaigns delete [id]

envloped campaigns delete cp_abc123
envloped campaigns delete cp_abc123 --yes

Deletes a draft, canceled, failed, or sent campaign together with its recipients and events — the record of what was actually sent, and to whom. An in-flight campaign must be cancelled first. Confirms before proceeding, unless --yes or a non-TTY stdout.

envloped campaigns report [id]

envloped campaigns report cp_abc123
envloped campaigns report cp_abc123 --section summary --section links
envloped campaigns report cp_abc123 --json

The CLI defaults to the full report — a human scrolling 72 rows pays nothing. Its MCP counterpart defaults to summary for the opposite reason. Same data, opposite verbosity defaults.

Headline open figures are the proxy-excluded ones. The raw rate appears once, labelled, because Apple Mail Privacy Protection prefetches images and inflates it — on a real campaign that is the difference between an 80.6% open rate and a 62.9% one.

Templates

envloped templates list                # TYPE column marks system vs custom
envloped templates list --mine         # hide the Envloped starters
envloped templates get tpl_abc123
envloped templates create "Monthly digest" --html-file ./digest.html
envloped templates update tpl_abc123 --name "Monthly digest v2"
envloped templates delete tpl_abc123 --force

System starters (TYPE = system) are readable but not writable — the TYPE column is the discovery path, rather than a write failing. update is metadata-only by design; body edits go through a campaign.

Contact Fields

The typed attribute registry that governs what attributes may contain. See Contact fields.

envloped fields list
envloped fields list --include-archived
envloped fields get fld_abc123
envloped fields create plan --label "Plan" --type text
envloped fields create tier --label "Tier" --type enum --option free --option pro
envloped fields update fld_abc123 --label "Pricing tier"
envloped fields archive fld_abc123

archive never drops data — values stay on the contacts and reappear if the key is re-created.

Suppressions

Addresses Envloped refuses to mail.

envloped suppressions list --reason complaint --limit 50
envloped suppressions get user@example.com
envloped suppressions add user@example.com --notes "emailed support 2026-08-24"
cat unsubscribes.txt | envloped suppressions add --stdin
envloped suppressions delete user@example.com

The two write directions are deliberately asymmetric. Adding is the safe move — it stops mail, and it is what you run when someone asks to be removed out-of-band, so it needs no confirmation. Removing re-enables mail to someone who bounced, complained, or asked you to stop, so it prompts (skipped by --yes and when stdout is not a terminal), and the server refuses complaint-reason removals outright.

On list, an unrecognised --reason or --origin is dropped server-side rather than rejected, so a typo returns the whole unfiltered list with a 200.

Marketing Profile

Your business identity. A campaign send fails its compliance gate without a complete profile, and this is how you find out which field is missing without reading a 403 body.

envloped profile get
envloped profile set --legal-name "Acme Pte Ltd" --address-line1 "1 Raffles Place" \
  --city Singapore --postal-code 048616 --country SG

get prints the server's completeness verdict, and when incomplete it names the missing flags and prints a ready-to-paste profile set line. On set, only flags you actually passed are sent, so unset fields are preserved and --flag "" clears.

Sender Reputation

envloped reputation
envloped reputation --json

Shows a status banner (healthy / warning / suspended), the SES tenant sending status, and 24h/7d bounce and complaint rates against the thresholds the server echoes back, with a per-row verdict — so a number is interpretable rather than just a number.

When a send is refused with reputation_suspended, this is how you see why and how bad it is. Recovery is manual: a suspension does not clear on its own, and the command says so rather than implying it will.

API Key Management

envloped keys list

List all API keys for your account.

envloped keys list
envloped keys list --json

envloped keys create [name]

Create a new API key. The key is only displayed once.

envloped keys create "Production Key"
envloped keys create "CI Pipeline Key" --json

envloped keys delete [id]

Delete an API key. Requires confirmation unless --force is used.

envloped keys delete abc123
envloped keys delete abc123 --force

MCP Server

envloped mcp

Run the CLI as a Model Context Protocol server, exposing 20 tools to Claude, Cursor, and any MCP client.

envloped mcp                              # stdio, for a local client
envloped mcp --http --addr :8080          # Streamable HTTP, for a hosted deployment

Over stdio it authenticates with the API key envloped login already stored, so no key goes in your MCP client's config file. See MCP Server for client setup and the full tool table.

Note the deliberate asymmetry with the commands above: the CLI can do things the MCP tools cannot. campaigns send, keys create, every delete, and suppressions add/delete are reachable here and are not tools. A human at a terminal is an acceptable operator for bulk sends, credential minting, and compliance edits; an autonomous agent is not.

Configuration

envloped config set [key] [value]

Set a configuration value.

envloped config set default_from hello@mydomain.com
envloped config set api_url https://api.envloped.com

envloped config get [key]

Get a configuration value.

envloped config get default_from

Valid keys: api_url, default_from, output_format

Shell Completions

envloped completion [shell]

Generate shell completion scripts.

# Bash
source <(envloped completion bash)

# Zsh
source <(envloped completion zsh)

# Fish
envloped completion fish | source

Other

envloped version

Print the CLI version, commit, and build date.

envloped version
# envloped v0.1.0 (commit: abc123, built: 2026-03-28)