CLI
Use email, marketing, inboxes, SMS, Verify, Sign, Forms, Scheduling, Hooks and Risk from your terminal, follow your log and get webhooks on localhost.
The coss command line works with one environment at a time, like an API key does. Install it
with Homebrew, the install script or npm:
brew install cosscom/tap/coss # macOS and Linux, with shell completions
curl -fsSL https://raw.githubusercontent.com/cosscom/coss-cli/main/install.sh | sh
npm install -g coss-cli # Node.js 22+
coss loginOr run any command with npx coss-cli <command> without installing it (npx coss is the SDK,
not the CLI).
- Homebrew and the install script install a standalone executable, which needs no Node.js:
each release on cosscom/coss-cli (
coss-cli@<version>) has one for macOS, Linux (glibc and musl) and Windows, arm64 and x64, with aSHA256SUMS. - The install script picks the archive for your machine, checks it against
SHA256SUMSand installscossinto~/.local/bin(setCOSS_INSTALL_DIRfor another directory,COSS_VERSIONfor another version). - Alpine and other musl systems need
libstdc++(apk add libstdc++). - macOS executables are signed with coss.com's Developer ID and notarized by Apple (since 0.3.0), so one you download with a browser runs without a Gatekeeper warning.
- Windows: download
coss-cli-<version>-windows-x64.zipfrom the release, or use npm.
Sign in
coss login opens the dashboard in your browser. Check that the page shows the same verification
code as your terminal, pick the environment the CLI should work in (a development environment
is the default), and approve: the CLI gets a new API key of that environment, named after your
machine, and saves it. It is your personal key: what it sends
counts as your spend.
coss login
coss whoami # Acme / Default / Development (sandbox)- No browser on that machine (over SSH, the default there):
coss login --no-browserprints a link to open anywhere you're signed in; paste the code the page shows back into the terminal. - Members sign in to environments open to personal keys (new projects' development
environments are). Elsewhere, ask an owner or admin for a key and run
coss login --manual, which asks for the key (or reads it from stdin:echo "$KEY" | coss login --manual). - Several environments: save each under a profile (
coss login --profile prod), then pass--profile prodor setCOSS_PROFILE=prod.coss profiles listshows the saved profiles (--json: one object per profile, never its key) andcoss use prodmakes one the default. - CI and scripts: set
COSS_API_KEY; it wins over saved profiles. No flag takes a key, since command lines are visible to other processes on the machine.
coss logout removes the saved key and revokes it if coss login created it (--revoke also
revokes a key you pasted; --all signs every profile out). Keys are saved in ~/.config/coss/config.json ($XDG_CONFIG_HOME, or
%APPDATA% on Windows), readable only by you.
coss open opens the environment in the dashboard: coss open logs, coss open webhooks,
coss open api-keys, coss open domains, or an organization page (coss open members, coss open billing).
coss open --help lists every page, each product's included (coss open risk-rules,
coss open scheduling-hosts); --print (or --json) prints the URL instead.
Set a project up
coss init, in a project's directory, gets it ready to send:
cd my-app
coss init- It asks the dashboard for a new development key for the project (approved like
coss login, offering only sandbox environments, and named after the project) and writes it asCOSS_API_KEYto.env.localin a Next.js project,.envotherwise, or the file--env-filenames. This key is the project's, not the CLI's. A file that already has a key keeps it unless you pass--force; it warns when git doesn't ignore the file. - It installs the
cosspackage with the project's package manager (from its lockfile: bun, pnpm, yarn or npm);--no-installskips that. --product <product>ends with that product's step instead of email's: what it still needs, or with a development key how to try it (email,sms,verify,sign,forms,scheduling,inboxes,hooks,riskormarketing).- It adds a short section on coss.com to the project's
AGENTS.md(itsCLAUDE.mdwhen it has noAGENTS.md): where the docs are for agents, what the development key does, and how to test.--agentsis the default. Running it again updates that section.--no-agentsskips it. See Coding agents. - It prints the one next step for this key (a from address that will succeed, or the DNS still
missing) and, when the project already uses one, the Nodemailer, Better Auth, Auth.js, Laravel,
Rails or Django drop-in.
--jsonincludes that report assetup. --no-browserworks as withcoss login;--jsonprints what it did as one object.
Receive webhooks locally
coss.com can't reach localhost, so coss listen fetches the environment's events and forwards each
one to your local server, exactly as an endpoint would receive it:
coss listen --forward-to localhost:3000/webhooks
# Ready! Listening to Acme / Default / Development (sandbox), forwarding to http://localhost:3000/webhooks.
# COSS_WEBHOOK_SECRET=whsec_…
# Saved COSS_WEBHOOK_SECRET in .env.local (API version 2026-10-10)Requests are signed with that secret. An existing COSS_WEBHOOK_SECRET in the project's env file
is kept, so the handler's secret does not change; otherwise coss listen writes the profile's
secret, or a new one, into the same file as COSS_API_KEY. Verify requests as you would in
production:
import { } from "coss";
export async function (: ) {
// In development, the secret `coss listen` printed; in production, the endpoint's.
const = await (
await .(),
.,
..!,
);
.(., .);
return new ("ok");
}- Only events created while it runs are forwarded, oldest first; the
webhook-idheader is the event's id, as in production.--events email.delivered,email.bouncedsubscribes to fewer. - Each forward shows its status in the terminal and in the environment's log
(
webhook.forward). A failed forward isn't retried: trigger it again. - Without
--forward-to, events are only printed (--print-jsonshows their bodies,--jsonprints one JSON object per event). --header "Authorization: Bearer dev-token"adds a header to every forwarded request (repeatable), for a local server that expects one.- Events render in your organization's API version unless you pass
--api-version. domain.*,account.*andbilling.*events only reach live environments. Listening to a live environment, with its real events, needs--live.- An environment has at most 5 listeners at once. One that stops polling (your laptop sleeps)
closes after 10 minutes, and
coss listenopens a new one when it wakes up: events in between are missed.
Trigger test events
With coss listen running, coss trigger sends a test event of any type, so you can work on a
handler without making the real thing happen:
# terminal 1
coss listen --forward-to localhost:3000/webhooks
# terminal 2
coss trigger email.bounced
# ✔ email.bounced evt_01k7c8m4r0c2b8w9y3d5f6g7h8 → 0 endpoints, 1 listener
coss trigger contact.unsubscribed -F contact.email=ada@example.com
coss trigger risk.assessment.review --data '{"user_id":"u_42","score":0.91}'The event is a realistic sample of its type, sent to the environment's subscribed
endpoints and open listeners exactly like a real one: same body, signature,
retries and log lines, with nothing marking it as a test. Its ids are made up, so pass real ones
for a handler that looks them up: --data takes a JSON object merged over the sample's data,
and -F name=value (--field) sets one field, with dotted names reaching into objects
(-F bounce.sub_type=NoEmail) and values read as JSON when they parse (@path reads a file).
Unknown fields are refused. --json prints the event that was sent.
- Test events are for development environments (sandbox keys) only, and of every type except the
live-only
domain.*,account.*andbilling.*. Tab completes the types. - To run an email through the real pipeline instead (sending, the provider, then its events),
send it to the mailbox simulator:
coss emails send --simulate bounced.
Webhook endpoints and deliveries
coss webhooks list
coss webhooks add https://example.com/webhooks --events email.delivered,email.bounced
coss webhooks deliveries whep_01k7c8m4q2f3e9v6t5r1n0p8yz --status failed
coss webhooks retry whep_01k7c8m4q2f3e9v6t5r1n0p8yz whdel_01k7c8m4q2f3e9v6t5r1n0p8yzcoss webhooks list shows the environment's endpoints with their URL, state (enabled, failing,
disabled) and event types. coss webhooks add <url> creates one. Its signing secret is returned
once and written to the project env file as COSS_WEBHOOK_SECRET (a previous value is replaced,
so coss listen signs with the same secret). --description stores a note, --events limits
the types (the default is every event, including ones added later), and --force creates another
endpoint when that URL already has one. Without --force the existing endpoint is left as it is.
Creation is not retried. coss webhooks deliveries <endpoint> lists an endpoint's deliveries,
newest first, with the last status code and error; filter with --status pending|succeeded|failed
or --event <event id>, and show up to --limit 100 (default 20).
coss webhooks retry <endpoint> <delivery> sends a finished delivery once more, within seconds. Each takes --json.
Send test emails
coss emails send --to you@example.com
coss emails send --simulate bounced --waitWith a development key nothing is delivered, but every event and webhook a real send has still
happens. --simulate delivered|bounced|complained|suppressed sends to the mailbox
simulator, which produces that outcome in development and production alike;
--wait follows the email until it's known and prints its events, so with coss listen running
you see the matching webhooks arrive. It waits up to 60 seconds (--timeout <seconds>).
The default sender for development keys is coss.com CLI <cli@example.com>; production keys need
--from on a verified domain. Also: --subject, --text/--text-file, --html/--html-file,
--template <id or alias> with --var name=value, --cc, --bcc, --reply-to, --category,
--tag name=value and --json.
Find and debug emails
coss emails list --recipient-status bounced --since 1d
coss emails diagnose email_01k7c8m4q2f3e9v6t5r1n0p8yz
coss emails diagnose --to ada@example.comcoss emails list shows the environment's emails, newest first, with where each one stands: its
status until it was handed to the provider, then its recipients' (delivered,
2 delivered, 1 bounced). Filter by --to, --status, --recipient-status, free text (-q), --category,
--batch <id> and creation time (--since, --until); --limit sets how many (20 by default,
read page by page). --json prints one email per line.
coss emails get <id> shows one email: sender, recipients and their statuses, its failure,
tracking counts and attachments (--text or --html prints that body alone).
coss emails events <id> lists its events, with what the receiving server answered.
coss emails diagnose <id> explains the outcome: a verdict, what each recipient's status means (a
hard bounce and the server's reason, the suppression entry that skipped an address, a delay, a
failure and its cause), account problems that affect it (an unverified domain, reputation, a
billing hold) and the next steps, as commands to run. --to <address> diagnoses the newest email
to that address. It's the same diagnosis as the SDK's coss/diagnose and the MCP server's
diagnose_email, and each product has one (coss sms diagnose, coss verify diagnose,
coss sign diagnose, coss forms diagnose, coss hooks diagnose, coss scheduling diagnose).
Scheduled emails
coss emails cancel <email> cancels an email scheduled for later. coss emails reschedule <email> --at <time>
moves it (ISO 8601 with an offset, at most 30 days ahead). A time that has passed sends it right
away, so a live key asks first; off a terminal that needs --yes.
Suppressions
coss suppressions check ada@example.com --category newsletter
coss suppressions add ada@example.com --scope newsletter
coss suppressions list --scope "*"
coss suppressions remove sup_01k7c8m4q2f3e9v6t5r1n0p8yzSuppressions are the addresses sends skip.
coss suppressions listlists them, newest first (--address,--scope,--limit).coss suppressions check <address>says whether a send would skip it and which entries match (--category,--stream transactional|marketing). It exits0either way: scripts readsuppressedfrom--json.coss suppressions add <address>adds one, for every email or one category (--scope).coss suppressions remove <suppression>removes one by id. Someone who complained or unsubscribed asked not to be contacted.
Each takes --subaccount <subaccount> for a sub-account's own list (check for the sub-account you
plan to send for), except remove, which takes the entry's id.
Sub-accounts
coss subaccounts create "Acme Inc" --uid acme --per-day 1000
coss subaccounts stats acme --from 2026-10-01Sub-accounts give each of your users their own domains, suppressions,
quotas and reputation. Every <subaccount> is its id or your uid.
coss subaccounts list(--limit) andcoss subaccounts get <subaccount>show them, with their quotas and reputation.coss subaccounts create <name>makes one (--uid,--metadata name=value, and the quotas--per-day,--per-second,--burst).coss subaccounts update <subaccount>changes what is given:--name,--uid(noneremoves it),--status active|disabled,--metadata(replaces what it has) and the quotas (noneremoves one).coss subaccounts reinstate <subaccount>lifts a reputation pause once you fixed the cause.coss subaccounts stats <subaccount>prints its sending per day (--from,--to; at most the last 45 days).coss subaccounts delete <subaccount>starts deleting it: its sends are refused at once, then its domains are released and it is removed with its suppressions. It can't be undone, so with a live key it asks first, and off a terminal it needs--yes.
Send test SMS
coss sms send --simulate filtered --wait
coss sms send --to +14155550199 --from +14155550123 --body "Your code is 482913"--simulate delivered|invalid|filtered|opted-out|reply sends to the SMS
simulator and needs a development key: nothing reaches a phone, but every
event and webhook a real send has still happens. Otherwise pass --to (E.164). --wait follows
the message until its outcome is known and prints its events (with --simulate reply, also the
simulated reply); it waits up to 60 seconds (--timeout <seconds>).
The default sender for development keys is +14155550100; production keys need --from, one of
your organization's registered numbers. Also: --body (default "Test message
from the coss.com CLI"), --tag name=value (repeatable) and --json.
Read SMS
coss sms listlists the environment's messages, newest first (--to,--status,--limit).coss sms get <message>prints a message's text, status, failure and events.coss sms receivedlists what your numbers received (--from,--to,--limit).coss sms numberslists your numbers and whether each can send.coss sms suppressions list(--number,--limit),coss sms suppressions add <number>andcoss sms suppressions remove <suppression>manage the numbers that won't be texted.coss sms diagnose <message>(or--to <number>, the newest to it) explains the outcome: a verdict, what the failure code means, the carrier's error code, problems with the sender's registration, suppressions, reputation or billing, and what to do next.
coss sms cancel <message> cancels a scheduled message. coss sms suppressions check <number>
says whether a send to a number would be skipped; it exits 0 either way.
Verify
Send and check one-time codes. Development keys deliver nothing, and the code is all zeros:
coss verify start +15005550006
coss verify check --to +15005550006 --code 000000coss verify start <to>sends a code to a number in E.164 form or an address (--channel,--ip,--user).coss verify check --code <code>compares a code, by--id <verification>or--to <destination>. It exits 0 only when the code is right, and a wrong code spends an attempt.coss verify list(--to,--status,--limit),coss verify get <verification>andcoss verify cancel <verification>.coss verify diagnose <verification>(or--to <to>) says why no code arrived or a check failed: the fraud guard's reasons, expiry and attempts, each code's route and the latest message's outcome. It never shows a code.coss verify settings getshows the settings, andcoss verify settings setchanges them:--app-name,--code-length,--ttl,--max-attempts,--sms-from,--email-from,--countries US,CA,GB. The worddefaultgoes back to coss.com's sender or the project's name.
Contacts and broadcasts
coss contacts add ada@example.com --audience aud_01kd2m8n3p4q5r6s7t8v9w0x1y
coss broadcasts create --name October --from news@acme.com --subject News --html october.html \
--audience aud_01kd2m8n3p4q5r6s7t8v9w0x1y
coss broadcasts test bcast_01kd2m8n3p4q5r6s7t8v9w0x1y --to you@acme.com
coss broadcasts send bcast_01kd2m8n3p4q5r6s7t8v9w0x1ycoss contacts list(--email,--status,--audience,--limit),coss contacts get <contact>andcoss contacts remove <contact>, by id or address.coss contacts add <email>creates or updates a contact (--first-name,--last-name,--audience, repeatable, and--double-opt-in).coss broadcasts list(--status,--limit),coss broadcasts get <broadcast>andcoss broadcasts cancel <broadcast>.coss broadcasts createmakes a draft:--name,--from,--subject,--html <file>,--text <file>, and--audience,--segmentor--topic. It sends nothing.coss broadcasts test <broadcast> --to <address>sends a test (--contactrenders it for one).coss broadcasts send <broadcast>sends it, or schedules it with--at <time>. With a production key it asks first, and needs--yesoff a terminal.
Change and move contacts in bulk:
coss contacts update ada@example.com --first-name Ada --property plan=pro
coss contacts import people.csv --audience aud_01k7c8m4q2f3e9v6t5r1n0p8yz
coss contacts export --status subscribed --out contacts.csvcoss contacts update <contact>changes what is given:--first-nameand--last-name(""clears one),--status subscribed|unsubscribed,--property name=value(JSON values when they parse,nullremoves it), and--data '{…}'for the rest of the body, such astopics.coss contacts import <file>creates or updates contacts from a CSV or a JSON array of import entries (-reads stdin), and adds them to--audience. A CSV is whatcoss contacts exportwrites, or any file with an email column (First Name-style headers work) or just addresses, one per line. Columns named after a custom property set it, and other columns are reported and left out. Imports never resubscribe an unsubscribed contact and are safe to run again. Rows it can't use are skipped and listed, and then it exits1. Only import people who agreed to hear from you.coss contacts exportprints the contacts as CSV (--status,--audience), or saves them with--out <file>(a new file is readable only by you). A pipe gets the bytes as they came; a terminal gets them without control characters.--jsonprints{ csv }, or{ file, size }with--out.
Broadcasts can change until they send, and stop and start while they do:
coss broadcasts update <broadcast>changes a draft (--name,--from,--subject,--html,--text,--audience,--segment,--topic, wherenonemeans every contact, and--data).coss broadcasts remove <broadcast>deletes a draft, or a broadcast canceled before it sent anything.coss broadcasts pause <broadcast>pauses a scheduled or sending one.coss broadcasts resume <broadcast>sends the rest: with a live key it asks first, and off a terminal it needs--yes.
Audiences, segments and topics
coss audiences create Customers
coss audiences contacts add aud_01k7c8m4q2f3e9v6t5r1n0p8yz ada@example.com bo@example.com
coss segments create "Acme staff" --filter '{"version":1,"match":"all","conditions":[{"field":"email","op":"ends_with","value":"@acme.com"}]}'
coss topics create product --name "Product news" --default opt_in- Audiences are static lists:
coss audiences list,coss audiences get <audience>,coss audiences create <name>,coss audiences update <audience> --name <name>andcoss audiences remove <audience>, which leaves their contacts.coss audiences contacts list <audience>,coss audiences contacts add <audience> <contact>...(ids or addresses of existing contacts; exits1when one is no contact) andcoss audiences contacts remove <audience> <contact>manage who is in one. - Segments are filters, evaluated whenever they're used:
coss segments list,coss segments get <segment>,coss segments create <name> --filter <json>,coss segments update <segment>(--name,--filter) andcoss segments remove <segment>.--filtertakes JSON inline, as@fileor as-for stdin.coss segments contacts list <segment>lists who a segment matches now. - Topics are what contacts subscribe to:
coss topics list,coss topics get <topic>,coss topics create <key> --name <name> --default opt_in|opt_out,coss topics update <topic>andcoss topics remove <topic>(--description, wherenoneclears it on update,--visibility public|private,--position). coss marketing settings getshows the sender's name and postal address marketing email carries, and how double opt-in confirms.coss marketing settings setchanges--display-name,--mailing-address,--double-opt-inor--no-double-opt-in,--confirmation-from,--confirmation-subject,--confirmation-html <file>,--confirmation-text <file>and--confirmed-redirect-url; the worddefaultclears one.
Sign
Collect signatures on a PDF:
coss sign upload nda.pdf
coss sign create --title NDA --document sdoc_01kd2m8n3p4q5r6s7t8v9w0x1y --signer "Ada Lovelace <ada@example.com>"
coss sign send sreq_01kd2m8n3p4q5r6s7t8v9w0x1ycoss sign upload <file.pdf>prints the document's id and the text anchors found in it.coss sign createmakes a draft:--title,--message,--document(repeatable) and--signer "Name <email>"(repeatable), each signer signing at the anchor{{signature:signer_1}},{{signature:signer_2}}…; or--templatewith--signer "role:Name <email>"and--merge name=value.--sendsends it at once.coss apitakes any other fields.coss sign list(--status,--limit),coss sign get <request>,coss sign send <request>,coss sign remind <request>andcoss sign cancel <request>.coss sign download <request>saves the sealed PDF (--out <file>), andcoss sign audit <request>prints the audit trail.coss sign templateslists templates and their roles.coss sign diagnose <request>says where a request stands: each signer's state and whose turn it is, a draft never sent, declined, expired, or signed and still being sealed.
coss sign templates (or coss sign templates list) lists templates.
coss sign templates create <name> makes one: --title, --message,
--signing-order parallel|sequential, --document <document> (repeatable), --role key:Name
(repeatable), and --data '{"fields":[…]}' or --data @template.json for its fields. It may start
empty and be built in the embedded builder; requests can be made from it once it has documents and a
signature field for every role.
coss sign settings get shows the name signers see, the sender, branding, reminders and embedding
origins. coss sign settings set changes --display-name, --email-from, --accent-color,
--theme system|light|dark, --disclosure, --reminder-days and --origin (repeatable, replacing
the list); the word default clears one.
Follow the log
coss logs tail
coss logs tail --source email --level error
coss logs tail --type api.request --status 4xx,5xx --since 15mNew lines of the environment's log as they arrive: API requests made with its keys,
email and SMS events, webhook attempts and coss listen forwards. Filter by --source, --level,
--type, --status and free text (-q); --since starts with earlier lines, and --json
prints one log object per line for jq. It checks for new lines every 2 seconds (--interval <ms>,
at least 500).
Log drains
coss log-drains create https://logs.acme.com/in --source api,email
printf '%s' "$DD_API_KEY" | coss log-drains create https://http-intake.logs.datadoghq.com/api/v2/logs --format datadog --auth-header DD-API-KEY
coss log-drains update ldr_01k7c8m4q2f3e9v6t5r1n0p8yz --disabledLog drains stream the environment's log to your own endpoint or an intake API.
coss log-drains listandcoss log-drains get <drain>show them; secrets are never included.coss log-drains create <url>makes one (--description,--source api|email|webhook|audit, repeatable or comma-separated,--format ndjson|loki|datadog|otlp) and prints its signing secret: the only time it's shown. It isn't retried, since the API doesn't deduplicate it.--auth-header <name>sends that header with every batch. Its value is a secret, and no flag takes a secret, since command lines are visible to other local processes: a terminal asks for it without echoing, and anything else pipes it to stdin.coss log-drains update <drain>changes what is given:--url,--description(noneclears it),--source,--format,--auth-header,--remove-auth-header.--disabledstops it and drops the lines waiting for it;--enabledstarts it again, also after coss.com disabled it for failing.coss log-drains delete <drain>deletes it and its batch log.
Hooks
The Hooks loop from the terminal: set up an application with an endpoint, send it
messages, and see what its endpoints answered. Wherever a command takes <app>, an application's
uid works as well as its id.
coss hooks event-types create invoice.paid --example '{"invoice_id":"in_1","amount":4200}'
coss hooks apps create "Acme" --uid acme
coss hooks endpoints add acme --url https://example.com/hooks --types invoice.paid
coss hooks send acme invoice.paid -F amount=4200 -f invoice_id=in_2
coss hooks deliveries acme --status failed
coss hooks portal acme --opencoss hooks apps listandcoss hooks apps create <name>(--uid,--metadata key=value) manage applications;coss hooks event-types list(--archived) andcoss hooks event-types create <name>(--description,--schema,--example, each JSON inline,@fileor-for stdin) the event types. Lists show 50 (--limit, up to 100).coss hooks endpoints list <app>shows each endpoint's state;coss hooks endpoints add <app> --url <url>(--types,--description,--rate-limit) prints the new endpoint's signing secret, the only time it's shown.coss hooks send <app> <event-type>sends a message: the payload is--data(a JSON object) with-F name=value(JSON values,@file) and-f name=value(strings) on top, or, with none of them, the event type's first example.--idempotency-keysends it once only.coss hooks deliveries <app>lists deliveries, newest first, of every endpoint or one (--endpoint), or of one message (--message), by--status(pending, succeeded, failed);coss hooks attempts <app> <delivery>shows each HTTP request of one, andcoss hooks retry <app> <delivery>queues a finished one for another attempt.coss hooks diagnose <app> <delivery>(or--message <message>, its worst delivery, or--endpoint <endpoint>, its latest failure) says what the endpoint answered on each attempt, when the next retry is, whether it's disabled or failing, and what to do next.coss hooks portal <app>prints a link that signs in to the application's portal (--openopens it,--read-only,--expires-in <seconds>). Anyone with the link is signed in until it expires.
Risk
Try Risk decisions before wiring them into your app, and manage what the environment remembers:
coss risk assess --event signup --email ada@disposable.test --ip 192.0.2.1
coss risk assessments --review open
coss risk feedback rass_01k7c8m4q2f3e9v6t5r1n0p8yz --outcome fraud --note "chargeback"
coss risk lists add block domain evil.example --expires 30d --note "spam wave"coss risk assess --event <event>(signup, login, message, checkout or custom with--event-name) takes--email,--ip,--user(your user id),--user-agent,--content,--captchaand--devicetokens, and--datafor anything else of the request (a checkout, say), and prints the decision, its score and each reason. It counts like any assessment.- In development environments the test fixtures produce each decision:
192.0.2.1(Tor),.2(a cloud),.3(a VPN),.4(a proxy) and.5(a privacy relay); addresses atdisposable.test,undeliverable.testandnew.test; captcha tokenstest-passandtest-fail; the device tokentest-device-automated; content with[coss-test:spam](orphishing,malware,fraud, and[coss-test:spam:0.6]for a given score). coss risk assessmentslists assessments by--decision,--event,--userand--review(openis the review queue);coss risk feedback <assessment> --outcome legitimate|fraud|abuse(--note) reports what the user turned out to be.coss risk lists list(--list allow|block,--type),coss risk lists add <allow|block> <email|domain|ip|asn|country|user> <value>(--note,--expiresas7d,12hor a time) andcoss risk lists remove <entry>manage the allow and block lists.
Manage what decides:
coss risk rules create "No Tor sign-ups" --action block --event signup --condition "ip.tor is true"
coss risk check email ada@gmial.com
coss risk classify --file message.txt
coss risk settings set --review-threshold 0.4coss risk rules listandcoss risk rules get <rule>show the rules, in the order they're tried: the first enabled one whose conditions match decides, after the lists.coss risk rules create <name>adds one:--action allow|review|blockand--condition "<field> <operator> <value>", repeatable ("velocity.ip_1h gt 10","ip.country in RU,KP"; operatorsis,eq,neq,gt,gte,lt,lte,in,not_in), with--match all|any,--event(repeatable),--position,--enabledor--disabled, and--datafor the same body as JSON.coss risk rules update <rule>changes what is given (--nametoo);--conditionreplaces all of its conditions.coss risk rules delete <rule>deletes it.coss risk check email <address>,coss risk check ip <ip>andcoss risk check phone <number>ask about one signal on its own. Nothing is stored. Live phone checks that get an answer are billed, so they're never retried.coss risk classify <text>scores text for spam, phishing, malware and fraud (--file <path>, or-for stdin). You choose the thresholds, and the text is neither stored nor logged.coss risk settings getshows the settings.coss risk settings setchanges--review-threshold,--block-threshold,--disabled-reason(repeatable, replacing the list;noneempties it) and--dataforcontent_thresholdsandreason_weights.--captcha turnstile|hcaptcha|offsets the captcha provider, with--captcha-requiredor--captcha-optional.--captcha-secret-stdinreads its secret from stdin (a terminal asks without echoing), and inline--datarefuses one: no secret goes on a command line.
Forms
See the environment's forms and what was submitted to them:
coss forms list
coss forms submissions form_01kd2m8n3p4q5r6s7t8v9w0x1y --status heldcoss forms listprints each form's id, name, whether it takes submissions and its endpoint (--limit).coss forms get <form>prints a form's endpoint and settings;coss forms create <name>makes one that accepts any field (--origin, repeatable, and--redirect <url>;coss apitakes every other setting).coss forms update <form>changes what is given and leaves the rest:--name,--enabledor--disabled,--origin(replaces the list),--redirect(noneclears it) and--data '{…}'for any other setting (fields,spam,notifications,hosted…).coss forms remove <form>deletes a form with its submissions and files. It can't be undone, so with a live key it asks first, and off a terminal it needs--yes.coss forms submission <form> <submission>prints one submission's values, andcoss forms release <form> <submission>accepts one Risk held for review, which sends it on to the form's webhooks, notification emails and contacts.coss forms submissions <form>lists a form's submissions, newest first, with their status, submitter and field names;--status accepted|held|spam|pending_confirmationnarrows them (heldis Risk's review queue),--limitcaps them. Values are what someone typed: read them with--jsonorcoss api forms/<form>/submissions/<id>.coss forms diagnose <form> [submission]says what happened to a submission (the form's newest without an id): held, spam and why, waiting to be confirmed, or accepted and where it goes. Spam is answered exactly like a success, so a submitter who saw a success proves nothing.
Scheduling
See the environment's hosts and bookings:
coss scheduling hosts
coss scheduling bookings --host doctor_482 --status confirmedcoss scheduling hostsprints each host's id, youruid, name, time zone and status (--limit).coss scheduling bookingslists bookings, newest first;--hostand--status held|pending_approval|confirmed|cancelled|declinednarrow them,--limitcaps them.--jsonprints attendees' details, whichcoss scheduling bookingsotherwise leaves out.coss scheduling event-typeslists what can be booked (--limit).coss scheduling slots <event-type> --start <time> --end <time>lists bookable starts (--host).coss scheduling booking-events <booking>shows a booking's history (--json), andcoss scheduling cancel <booking>takes--reason.coss scheduling slots explain <event-type> --start <time>says whether one start can be booked and, host by host, why not (--host).coss scheduling booking <booking>shows a booking, andcoss scheduling cancel <booking>cancels it and tells the attendee.coss scheduling candidates <booking>lists who a booking could go to, and why not.coss scheduling reassign <booking> --to <host>gives it to another host, or--autolets coss.com pick.--fromsays who's leaving, if it has several hosts;--reasonsays why, with--notein your own words;--any-hostallows someone who doesn't take the event type,--overridegoes past what a candidate couldn't do, and--no-notifydoesn't tell the attendee.coss scheduling reassign-many --from <host>moves many bookings, or--ooo <id>those in an out of office entry.--togives them all to one host;--preferredtries those first (comma-separated) and then the fairest who's free, unless--leave-rest.--afterand--beforenarrow it,--reasonand--notesay why,--no-notifydoesn't tell attendees, and--dry-runshows who they'd go to and moves nothing.coss scheduling reassignmentslists runs (--limit).coss scheduling reassignment <id>shows one and what didn't move,--cancelstops what hasn't happened yet, and--undogives back what it moved.coss scheduling ooolists time hosts are away (--host,--limit).coss scheduling no-show <booking>marks a booking as a no-show, once it has started.coss scheduling notifications <booking>lists what was queued for a booking and what became of it, newest first, including why a reminder wasn't sent (--limit).coss scheduling reminderslists what goes out around a booking (--event-typefor one event type's own list). Change it withcoss apior in the dashboard.coss scheduling calendars <host>lists a host's calendar connections.needs_reauthmeans that calendar can't be read, so the host isn't offered.coss scheduling diagnose <event-type>explains an empty list (--start,--end,--host), each finding certain, likely or possible: no host or schedule, a calendar to reauthorize, minimum notice, the booking window, limits, bookings and buffers. A calendar's busy times aren't readable through the API, so they can only be possible.
Set scheduling up and book from the command line:
coss scheduling hosts create "Dr. Reyes" --uid doctor_482 --time-zone America/New_York
coss scheduling schedules create doctor_482 --rule "mon-fri 09:00-17:00"
coss scheduling event-types create Consultation --uid consult --minutes 30 --host doctor_482
coss scheduling book consult --start 2027-01-04T15:00:00Z --time-zone America/New_York --name Bo --email bo@example.comcoss scheduling hosts and coss scheduling event-types still list; coss scheduling hosts list and
coss scheduling event-types list are the same commands.
coss scheduling hosts create <name> --time-zone <zone>adds a host (--uid,--email,--attribute name=value, repeat a name for a list,--metadata name=value,--data).coss scheduling hosts update <host>changes what is given (--name,--time-zone,--status active|disabled;--uidand--emailtakenone).coss scheduling hosts remove <host>deletes one.coss scheduling schedules list <host>,coss scheduling schedules create <host> --rule "<days> <start>-<end>"(repeatable:"mon-fri 09:00-17:00","sat,sun 10:00-12:00";--name,--time-zone,--default,--dataforoverrides),coss scheduling schedules update <host> <schedule>(--rulereplaces its rules; without one they stay) andcoss scheduling schedules remove <host> <schedule>manage when a host is free.coss scheduling event-types create <title> --minutes <n>adds what can be booked (--uid,--kind one_on_one|pool|collective|group,--host, repeatable,--requires-approval,--datafor buffers, limits, questions and locations).coss scheduling event-types update <event-type>changes what is given (--title,--status active|archived,--no-approval;--hostreplaces the hosts).coss scheduling book <event-type> --start <time> --time-zone <zone>books a slot for an attendee (--name,--email,--phone,--uid,--host,--minutes,--attribute,--answer name=value,--metadata,--data).coss scheduling reschedule <booking> --start <time>moves a booking (--host); the old time stays booked if the new one isn't free.coss scheduling approve <booking>andcoss scheduling decline <booking>decide one waiting for approval.
book, reschedule, approve and decline tell the attendee, so with a live key they ask first, and
off a terminal they need --yes.
Receive emails
coss inbox
# Inbound domain: k3j9x2m7qp4l.inbound.coss.com
coss inbox get rcv_01k7c8m4q2f3e9v6t5r1n0p8yzcoss inbox prints the environment's inbound domain: mail to any address at it is
received with no DNS setup. It then prints each email the environment receives
as it arrives, at that domain or at a receiving domain (--since 1h shows earlier ones too,
--interval <ms> sets how often it checks, --json prints the address and then one email per
line).
coss inbox get <id> shows a received email: sender, recipients, the receiving server's spam,
virus, SPF, DKIM and DMARC verdicts, attachments and the text body (--html for the HTML,
--headers for every header). Received mail is written by someone else, so control characters in
it are left out of what's printed. --raw > message.eml saves the whole message as received
(it refuses to write it to a terminal).
Inboxes
coss inboxes create --username support-agent --name "Acme Support"
coss inboxes threads inbox_01k7c8m4q2f3e9v6t5r1n0p8yz
coss inboxes thread inbox_01k7c8m4q2f3e9v6t5r1n0p8yz thread_01k7c8m4r0c2b8w9y3d5f6g7h8
coss inboxes reply inbox_01k7c8m4q2f3e9v6t5r1n0p8yz imsg_01k7c8m4s1d3c9x0z4e6g7h8j9 --text "On it."Inboxes are email addresses for agents. coss inboxes create makes one
(--username, --domain for one of the environment's receiving domains, --name for the name
it sends with, --client-id for your own id: creating it again returns the same inbox), and
coss inboxes list lists them (--limit). coss inboxes threads <inbox> lists its
conversations, latest first, with ● on those whose latest message is inbound;
coss inboxes thread <inbox> <thread> prints one, each message's own words without the quoted
conversation (--full for all of it). coss inboxes reply <inbox> <message> --text <text> replies
in the thread (--all replies to everyone on the message). Run coss listen to get each
inbox.message.received event as it arrives.
Domains
coss domains add acme.com # the DNS records to publish
coss domains add acme.com --format bind # the same, as zone-file lines to import
coss domains verify acme.com --wait # check now, and keep checking until it's verifiedcoss domains list shows the organization's sending domains, and
coss domains get <domain> one domain's records with what the last DNS check saw: verified,
missing, or a mismatch (with the value DNS returned). Domains are named by their name or their id.
coss domains verify checks now instead of waiting for the background check; with --wait it
checks again every 10 seconds, printing the records still missing, until the domain is verified
(exit 0), verification gives up (1), or --timeout passes (600 seconds by default, 1). A
domain whose verification had given up starts over with new DKIM records, which you publish
again. --json prints the domain object.
Templates as code
Keep email templates in your repository and push them from there:
coss templates pull # every template's draft, into ./templates
coss templates push --watch # save the draft again on every edit
coss templates preview welcome --var first_name=Ada --open
coss templates push --publish # publish the drafts sends usecoss templates pull [<template>...] writes each draft into a folder of --dir (templates by
default) named by the template's alias, else its id:
templates/welcome/
template.json # name, alias, description, default_locale, variables, sample_variables
en.subject.txt
en.html
en.txt
de.subject.txt
de.txtFiles are written byte for byte, so pulling and pushing changes nothing; a locale needs its
.subject.txt and an .html, a .txt or both. coss templates push [<path>...] (template
folders, or folders of them; --dir without arguments) replaces each draft with its files. It
finds the template by its alias, so the same folder pushes to every environment (sign in to
another with --profile), and creates templates that don't exist there yet. Without an alias
the folder is tied to the template's id. A push saves only drafts its files change, lists
problems (syntax errors, undeclared variables) with their file, line and column, and with
--publish publishes each draft too. --watch keeps running and pushes a template again
whenever one of its files changes.
coss templates preview <template> renders the draft as a send would, without sending: with its
sample_variables, overridden by --var name=value (JSON values when they parse), in --locale,
or a published --version. It prints the subject and text; --open shows the HTML in your
browser and --output preview.html saves it. Given a folder, it previews that template's draft
and warns when your files differ from it. coss templates list lists the environment's
templates.
Call any endpoint
coss api calls an endpoint of the API with the CLI's key and prints the
response's JSON, for anything the other commands don't cover (an unknown command's error says so too).
Paths are relative to /v1:
coss api domains
coss api emails/email_01k7c8m4q2f3e9v6t5r1n0p8yz/events
coss api -X POST domains/dom_01k7c8m4q2f3e9v6t5r1n0p8yz/verify
coss api suppressions -f reason=bounce --paginate | jq -r .address- Fields:
-f name=value(--raw-field) is always a string;-F name=value(--field) is JSON when it parses (-F limit=5,-F enabled=true,-F 'to=["a@example.com"]') and a file's contents with@path.name[]=valueadds to a list. GET and DELETE send fields as query parameters, every other method as the JSON body. - Methods:
-X(--method) takesGET(the default),POST,PUT,PATCHorDELETE.--input body.jsonsends that file as the body (--input -reads stdin) and makes the defaultPOST; fields then go in the query. - Lists:
--paginatereads every page and prints each item as one JSON object per line. - Other bodies:
--rawprints a response that isn't JSON as it is, such as a CSV export or a received email's raw message (coss api received_emails/<id>/raw --raw > message.eml). - Versions: requests use the API version the CLI was built for;
--api-version 2026-10-10asks for another.--jsonprints JSON on one line instead of indented.
A failed call prints the error ({ "error": { "type", "code", "message", … } }) on stdout too,
and exits with 1. Writes aren't retried automatically, since not every endpoint deduplicates
them: run the command again.
Shell completion
coss completion bash|zsh|fish prints a script that completes commands, flags and their values
(--simulate b → bounced):
eval "$(coss completion zsh)" # in ~/.zshrc, after compinit
eval "$(coss completion bash)" # in ~/.bashrc
coss completion fish > ~/.config/fish/completions/coss.fishScripting
Results go to stdout and progress to stderr, so pipes get only the results; --json makes them one
JSON object per line. coss <command> --help lists a command's options and coss --version prints
the CLI's. Exit codes:
| Code | |
|---|---|
0 | Done. |
1 | It failed: an API error, a network error, a key that isn't valid. |
2 | Wrong usage: an unknown command or option, or a bad value. |
130 | Stopped with Ctrl-C (how coss listen and coss logs tail end). |
Updates
Once a day, when it runs in a terminal, the CLI asks the npm registry for its latest version (a
plain GET https://registry.npmjs.org/coss-cli/latest; nothing else is sent) and prints one line
on stderr if a newer one exists. It never checks with --json, in CI (CI set) or when stderr
isn't a terminal, never delays a command, and COSS_NO_UPDATE_CHECK=1 turns it off.
Environment variables
| Variable | |
|---|---|
COSS_API_KEY | Use this key instead of a saved profile. |
COSS_PROFILE | The saved profile to use. |
COSS_BASE_URL | Another API origin. Remembered by coss login. |
COSS_DASHBOARD_URL | Another dashboard for coss login. |
NO_COLOR | No colors (or --no-color). |
COSS_NO_UPDATE_CHECK | 1: no update notice. |
Last updated
On This Page