Templates, rules and webhooks

These three namespaces let a mailbox run without anyone watching it. templates stores bodies you send many times, rules files mail as it arrives, and webhooks tells your own server what happened. Each command is an SDK method under its kebab-case name, so webhooks.rotateSecret is openemail webhooks rotate-secret, and it reads arguments and flags like every other resource command.

This page lists every command and what is worth knowing before you script it. For every argument and flag, with its type, the scopes it needs, its endpoint and what it returns, run openemail <namespace> <verb> --help. Add --json to get the same page as JSON.

openemail templates --helpopenemail rules create --helpopenemail webhooks replay-delivery --help --json

Bodies stored once and sent many times, with versions, previews and typed props. Every command that takes <id-or-slug> accepts the tpl_ id or the slug. The slug never changes when the template is renamed, so pin the slug in scripts.

• —An archived template refuses to send with template_archived. publish makes it active again.
• —A workspace holds at most 200 templates, archived ones included, so deleting is the only way to make room.
• —delete is refused with template_in_use while a scheduled or queued broadcast still names the template.

Conditions and actions evaluated on arriving mail, in the order rules list shows. A rule acts only on mail that arrives while it is enabled. No command applies a rule to mail already in the mailbox, and rules test is how you see what it would catch. Rule ids start with rul_.

--conditions is a list of { field, op, value } objects, joined by --match all or --match any, where value is always a string and negate: true inverts one condition. --actions is a list of { type, value } objects, applied in order. A rule takes 1 to 20 conditions and 1 to 10 actions, and a mailbox holds at most 100 rules.

• —Condition fields: from, from_domain, envelope_from, to, cc, bcc, recipient, reply_to, delivered_to, subject, body, header, list_id, attachment_name, attachment_type, has_attachment, attachment_size, message_size, spam, hour and weekday.
• —Operators: matches, contains, equals, starts_with, ends_with, gt and lt. gt and lt work only on the number fields, and has_attachment and spam take only equals with true or false.
• —Action types: label, remove_label, archive, mark_read, star, spam, trash, forward, reply, block_sender and reject. label and remove_label take a label id such as USER_RECEIPTS, forward takes an address and reply takes a template id or slug.
• —from_domain also matches subdomains, and hour and weekday are read in UTC, with 0 for Sunday.
• —A rule with a reject action must also test envelope_from, or it is refused with reject_needs_envelope.

Endpoints on your own server that receive signed mailbox events, with their signing secrets, their delivery log and an audit log of every change. Endpoint ids start with whe_ and delivery ids with whd_.

Leave --event-types out and an endpoint receives the default set, the email.* events other than email.replied. email.replied, the domain.* events and the suppression.* events reach it only when you name them. --address-allowlist and --domain-allowlist narrow an endpoint to some addresses or domains, the way they narrow an API key.

• —A workspace holds 10 endpoints unless support has raised its limit.
• —An endpoint that fails 100 deliveries in a row is switched off by the server, and webhooks update <id> --enabled brings it back.
• —With a browser sign-in, only the workspace owner can read a delivery with get-delivery. Anyone else gets owner_only and exit code 4.

templates preview renders exactly what a send with the same values would produce, drafts included, and needs only templates:read, so even a read-only key can run it. It reports a missing required prop as a warning where send would refuse it, so fail the build on any warning. publish is safe on every deploy, because publishing a head that is already live changes nothing.

draft=$(openemail templates get order-shipped --json | jq .latestVersion)openemail templates preview order-shipped --template-version "$draft" \  --props '{"orderId":"AC-4192","customer":"Ada"}' --json | jq -e '.warnings == []'openemail templates publish order-shipped

Pin the version, so a rewrite published tomorrow does not change what this code sends, and pass an idempotency key taken from what caused the send, so a retry after a lost answer replays the first message instead of sending a second. --dry-run prints the method, the URL, the headers with your credential redacted and the body, sends nothing and exits with code 0. Run it again without --dry-run to send.

openemail templates send order-shipped \  --from 'Acme <[email protected]>' \  --to [email protected] \  --template-version 5 \  --props '{"orderId":"AC-4192","customer":"Ada"}' \  --idempotency-key order-shipped:AC-4192 \  --dry-run

Create the rule switched off, dry run it against recent mail, and switch it on once it catches what you meant. With a browser sign-in, rules create and rules update ask for a verification code, which a script cannot type, so run openemail verify first. For the next 60 minutes that profile runs them without asking.

[  { "field": "from_domain", "op": "equals", "value": "stripe.com" },  { "field": "has_attachment", "op": "equals", "value": "true" }]

[  { "type": "label", "value": "USER_RECEIPTS" },  { "type": "archive" }]

openemail verifyrule=$(openemail rules create --name 'Stripe receipts' \  --conditions @conditions.json --actions @actions.json --no-enabled --json | jq -r .id)openemail rules test "$rule" --days 30 --limit 100openemail rules update "$rule" --enabled

Read the warnings of rules test before its matches. field_unevaluable means a condition reads something stored mail no longer carries, so the test could not judge it, and forward_unverified means a forward target is not hosted here. wouldApply lists what the rule declares: a forward to an address that has not confirmed still fails when real mail arrives.

rules reorder takes every rule on the mailbox exactly once. A rule left out or named twice is refused and nothing moves. rules list returns the ids in the order they run, so put the one you want first in front of the rest.

first=rul_4f1c9a2b7d3e8f6a0b5c1d2eopenemail rules reorder "$first" $(openemail rules list --all --ndjson \  | jq -r --arg first "$first" 'select(.id != $first) | .id')openemail rules list-runs --thread-id CAHk7pQ2x9LmZ4 --json | jq '.items[] | {ruleName, actions, failures}'

list-runs is the record of what really happened. Each row is one rule matching one message, with the actions that took effect and, in failures, the ones the mailbox declined, such as a reply to a sender already answered that day. Each row keeps the name the rule had at the time, so --rule-id works for a rule you have since deleted.

webhooks create shows the signing secret once, and no later command shows it again. With --json it is in the JSON on stdout, while the reminder to store it goes to stderr, so the output still parses. webhooks test sends a signed synthetic email.sent event whatever the endpoint subscribes to, and no mail is sent.

openemail verifyopenemail webhooks create --url https://hooks.acme.com/openemail \  --event-types email.received,email.bounced,email.complained \  --description 'Support desk sync' --json > endpoint.jsonjq -r .secret endpoint.jsonopenemail webhooks test "$(jq -r .id endpoint.json)" --json | jq .deliveryrm endpoint.json

Put the secret in your secret store before you delete the file. test exits with code 0 even when your server fails, so read delivery.status: delivered for a 2xx answer and failed for anything else, a redirect included, since redirects are never followed. A responseCode of null means no answer arrived at all.

After an outage on your side, list what failed across every endpoint, check that a replay would be accepted, and send the event again. A replay carries the same event id, so a receiver that drops ids it has already handled treats it as the event it knows.

openemail webhooks list-workspace-deliveries --status failed --since 2026-09-26T00:00:00Z --all --ndjson \  | jq -r '[.endpointId, .id, .eventType, (.responseCode // "no answer")] | @tsv'openemail webhooks get-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28 --json | jq .replayRefusalopenemail webhooks replay-delivery whe_3f9c2a7b1e4d8f60a5c7b92d whd_8c1e4a7f2b9d3e6a0c5f1b28

• —--since and --until take an ISO 8601 instant.
• —A failed row whose nextAttemptAt holds a time still has an automatic retry coming.
• —replayRefusal is null when a replay would go out, and otherwise names why it would be refused, such as webhook_disabled while the endpoint is switched off.
• —Replays go one event at a time. No command sends every failed delivery again.

With a browser sign-in, four of these commands ask for a verification code before they change anything, as the web app does: rules create, rules update, webhooks create and webhooks update. An API key is never asked. Every other command on this page runs without a code, deletions and webhooks rotate-secret included.

• —In a terminal, the CLI emails you a six-digit code, or asks for one from your authenticator app when two-factor sign-in is on, then runs the command once.
• —Unattended, with --json or --no-input, in CI or without a terminal, nobody can type the code, so the command stops with exit code 4 and changes nothing. Run openemail verify first, and the profile needs no code for 60 minutes.
• —--yes confirms a deletion, but never skips a code.

Seven commands here remove or overwrite something, so they ask you to confirm first: templates delete, templates delete-version, templates replace-content, templates restore-version, rules delete, webhooks delete and webhooks rotate-secret. Unattended, each one stops with exit code 2 unless you pass --yes.

$ openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d --no-input✗ Refusing to run unattended. Pass --yes to confirm.$ openemail webhooks delete whe_3f9c2a7b1e4d8f60a5c7b92d --yes

--dry-run prints the first request that would change something and exits with code 0, without sending it or asking you to confirm. With --json it prints one { dryRun, request } document. rules test, templates render and templates preview change nothing, but they are POST requests, so a dry run prints them instead of running them.

• —templates list, templates list-versions, rules list, rules list-runs and every webhooks list… command read one page at a time, 25 rows unless --limit asks for up to 100. A terminal shows the --cursor to pass for the next page.
• —--all reads every page, --max <n> stops after that many rows, and --ndjson prints one JSON object per line. With --json, a list prints one { items, hasMore, nextCursor } document, --all included.
• —Pass a cursor back with the same filters and sort it came with. Anything else is refused as invalid_cursor, with exit code 7.
• —templates list-sends pages by number instead, with --page and --page-size, reports total, and has no --all. Page numbers shift while mail is going out, so narrow the window with --days or --minutes rather than paging deep.
• —templates list-starters and templates list-fonts return the whole catalogue at once, and rules reorder returns every rule as a plain list in its new order.
• —A mailbox holds at most 100 rules, so rules list --limit 100 always returns every rule in one page.

• —--template-version is the body field version, renamed because --version prints the CLI version. The <version> argument of get-version, restore-version and delete-version is a version number, not a tplv_ id.
• —--conditions, --actions, --document, --slots, --props and the other JSON flags take JSON inline, from a file with @path, or from stdin with -. --data takes the whole body the same way, and any flag you pass as well overrides its key.
• —--html takes the markup itself, not a file, so --html @page.html sends the text @page.html. Pass --html "$(cat page.html)", or put html in the file you give --data.
• —rules update --conditions and --actions replace the whole list, and so do webhooks update --event-types, --address-allowlist and --domain-allowlist. Read the current value, change it, and send all of it.
• —An empty --event-types is a usage error. To put an endpoint back on the default set, send --data '{"eventTypes":[]}', and to stop its deliveries, pass --no-enabled.
• —--expected-version on templates update, replace-content and restore-version takes the head version you read. When someone else has moved the head since, the command stops with exit code 6 and version_conflict, and writes nothing.
• —rules update <id> --no-enabled switches a rule off and keeps its place in the order, which is the way to pause a rule without deleting it.