API reference
Automations
Record what contacts do as events, and run timed sequences of emails that start on an event, stop when the contact converts, and share per-person sending limits. Create and edit automations, their emails and language versions, turn them on and off, and add or remove people. Available to enabled workspaces.
No operations match this filter.
/eventsRecord something a contact did
Records one event for the contact with this `email` and applies it, in this order: the contact changes in `contact` and the event are written; every open enrolment of the contact whose automation names the event as its goal ends as converted (the latest email sent within the attribution window before the event is credited), and every one that lists it as a stop event ends; an enrolment that already completed within the attribution window is credited too; then the contact enters every automation that is on and starts on this event, unless it is already in it or the automation's `reentry` rule forbids it. Entering sends nothing by itself: the automation's emails go out later, each once it is due (its offset from `occurred_at`) and the workspace's sending limits and hours allow it. A contact that is unsubscribed, bounced, or complained is recorded and can leave automations, but never enters one. A new contact requires `contact.consent_basis` (422 `consent_required`). Returns the automations the event `started` and `ended`, by key. With `dedupe_key` (or the Idempotency-Key header) a retry changes nothing and returns the first result, with `Idempotent-Replayed: true`. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/events \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.net","event":"checkout_started","properties":{"plan":"pro","amount":49},"occurred_at":"2026-11-18T12:00:00.000Z","dedupe_key":"checkout_8f3a","contact":{"name":"Ada Lovelace","timezone":"Europe/London","consent_basis":"Created an account on acme.com and accepted product emails"}}'{
"id": "cev_…",
"contact_id": "ct_…",
"started": [
"checkout-recovery"
],
"ended": [
"trial-ending"
]
}/events/batchRecord up to 100 events
`events` is an array of up to 100 events, each exactly as in POST /events and applied in order. Returns one result per event: `ok: true` with the same fields as a single event, or `ok: false` with the error. 201 when every event was recorded, 207 when some were not. An Idempotency-Key header covers every event without a `dedupe_key` of its own, so a retried batch records nothing twice. A very large batch may stop early: the events it did not reach come back with 503 `batch_budget_reached` and can be sent again. `source` says where the batch came from, for GET /events: `api` (the default) or `upload` for rows taken from a spreadsheet. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/events/batch \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"email":"ada@example.net","event":"checkout_started","properties":{"plan":"pro"}},{"email":"grace@example.net","event":"payment_completed"}]}'{
"data": [
{
"index": 0,
"ok": true,
"id": "cev_…",
"contact_id": "ct_…",
"started": [
"checkout-recovery"
],
"ended": [
"trial-ending"
]
}
],
"count": 1,
"successful": 1,
"failed": 0
}/automationsList automations with their 30-day totals
Every automation in priority order (`position`, lowest first) with how many emails it has and its totals for the last 30 days: people who entered, emails sent, delivered, opened, clicked, and converted, plus bounces, complaints, unsubscribes, and `held`, which counts each time an email was made to wait by the workspace's sending limits, the sending hours, or the automation's daily cap. Email bodies are not included; read one automation for those. Each automation carries `domain`: the domain of its `from_address` in lower case, or null while it has no sender. `domain` narrows it to the automations that send from one domain (the exact domain of their `from_address`, such as example.com; `none` for automations with no sender yet). `domains` lists every domain the workspace's automations send from, in alphabetical order, with how many automations each has; it always describes the whole workspace, whatever the filter. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"data": [
{
"id": "aut_…",
"key": "checkout-recovery",
"name": "Checkout recovery",
"domain": "example.com",
"audience_label": "Started checkout and left",
"goal_label": "paid",
"status": "draft",
"entry": {
"type": "event",
"event": "checkout_started",
"reentry": "never"
},
"exit_rules": {
"goal_event": "payment_completed",
"no_goal": false,
"stop_events": [
"account_closed"
],
"attribution_days": 14
},
"position": 1,
"settings": {
"exempt_from_hold": false,
"daily_send_cap": null,
"daily_entry_cap": null,
"holdout_pct": 0,
"stale_days": 4,
"resume_after_days": 3
},
"from_name": "Acme",
"from_address": "hello@example.com",
"reply_to": null,
"switched_on_at": null,
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z",
"steps_count": 3,
"totals": {
"entered": 40,
"sent": 61,
"delivered": 60,
"opened": 31,
"clicked": 9,
"converted": 6,
"bounced": 1,
"complained": 0,
"unsubscribed": 1,
"held": 4
}
}
],
"count": 1,
"domains": [
{
"domain": "example.com",
"count": 1
}
]
}/automationsCreate an automation as a draft
Create a sequence of emails for one kind of person. `key` is its address in the API and cannot be changed. `entry` says how people enter, `exit_rules` when they leave, and `steps` are the emails, each due `offset_seconds` after the moment the person entered. When several are due at once, only the latest is sent and the earlier ones are skipped; one more than `settings.stale_days` overdue is skipped too. A new automation is always a draft: nothing is sent until POST /automations/{key}/status turns it on. `from_address` must be on a verified workspace domain. Returns 409 when the key is taken. A workspace may have 100 automations. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"key":"checkout-recovery","name":"Checkout recovery","audience_label":"Started checkout and left","goal_label":"paid","from_name":"Acme","from_address":"hello@example.com","entry":{"type":"event","event":"checkout_started"},"exit_rules":{"goal_event":"payment_completed","stop_events":["account_closed"]},"steps":[{"offset_seconds":3600,"subject":"Still thinking it over, {{ first_name | there }}?","html":"<p>Your cart is waiting.</p>"}]}'{
"id": "aut_…",
"key": "checkout-recovery",
"name": "Checkout recovery",
"domain": "example.com",
"audience_label": "Started checkout and left",
"goal_label": "paid",
"status": "draft",
"entry": {
"type": "event",
"event": "checkout_started",
"reentry": "never"
},
"exit_rules": {
"goal_event": "payment_completed",
"no_goal": false,
"stop_events": [
"account_closed"
],
"attribution_days": 14
},
"position": 1,
"settings": {
"exempt_from_hold": false,
"daily_send_cap": null,
"daily_entry_cap": null,
"holdout_pct": 0,
"stale_days": 4,
"resume_after_days": 3
},
"from_name": "Acme",
"from_address": "hello@example.com",
"reply_to": null,
"switched_on_at": null,
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z",
"steps": [
{
"id": "ast_…",
"position": 1,
"offset_seconds": 3600,
"subject": "Still thinking it over, {{ first_name | there }}?",
"preheader": "Your cart is saved",
"editor": "html",
"content": null,
"html": "<p>Your cart is waiting.</p>",
"text": "Your cart is waiting.",
"skip_if_empty": [
"fields.plan"
],
"ignore_send_window": false,
"variants": [
{
"locale": "fr",
"subject": "Vous hésitez encore, {{ first_name | bonjour }} ?",
"preheader": "",
"content": null,
"html": "<p>Votre panier vous attend.</p>",
"text": "Votre panier vous attend.",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"enrollments": {
"active": 12,
"waiting": 1
},
"overlap": [
{
"key": "trial-ending",
"name": "Trial ending",
"contacts": 3,
"position": 0,
"goes_first": true
}
],
"merge_fields": [
{
"key": "first_name",
"label": "First name"
}
],
"to_fill": [
{
"id": "placeholder",
"position": 1,
"locale": null,
"where": "body",
"placeholder": "[First step]",
"key": null,
"message": "Email 1 still says \"First step\" in its text: replace it with your own words"
}
]
}/automations/:keyRetrieve an automation with its emails
The automation, its emails in order with their language versions, how many people are in it now (`enrollments.active` and `enrollments.waiting`), and `overlap`: the other automations that are on and currently have the same people in them, with how many (`contacts`), each one's `position`, and `goes_first`: true when that automation ranks above this one, so the shared people get its emails first and wait in this one. `merge_fields` lists the merge tags its emails print, each with a plain-word `label`. `to_fill` lists what must still be filled in before it can be switched on: each placeholder of the template library left in an email or a language version (`id` `placeholder`, with `position`, `locale`, `where`: `subject`, `preview_text`, `body`, or `link`, and the `placeholder`), and each workspace name the emails print that is blank (`id` `workspace_name`, with `key`). It is empty when there is nothing. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"id": "aut_…",
"key": "checkout-recovery",
"name": "Checkout recovery",
"domain": "example.com",
"audience_label": "Started checkout and left",
"goal_label": "paid",
"status": "draft",
"entry": {
"type": "event",
"event": "checkout_started",
"reentry": "never"
},
"exit_rules": {
"goal_event": "payment_completed",
"no_goal": false,
"stop_events": [
"account_closed"
],
"attribution_days": 14
},
"position": 1,
"settings": {
"exempt_from_hold": false,
"daily_send_cap": null,
"daily_entry_cap": null,
"holdout_pct": 0,
"stale_days": 4,
"resume_after_days": 3
},
"from_name": "Acme",
"from_address": "hello@example.com",
"reply_to": null,
"switched_on_at": null,
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z",
"steps": [
{
"id": "ast_…",
"position": 1,
"offset_seconds": 3600,
"subject": "Still thinking it over, {{ first_name | there }}?",
"preheader": "Your cart is saved",
"editor": "html",
"content": null,
"html": "<p>Your cart is waiting.</p>",
"text": "Your cart is waiting.",
"skip_if_empty": [
"fields.plan"
],
"ignore_send_window": false,
"variants": [
{
"locale": "fr",
"subject": "Vous hésitez encore, {{ first_name | bonjour }} ?",
"preheader": "",
"content": null,
"html": "<p>Votre panier vous attend.</p>",
"text": "Votre panier vous attend.",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"enrollments": {
"active": 12,
"waiting": 1
},
"overlap": [
{
"key": "trial-ending",
"name": "Trial ending",
"contacts": 3,
"position": 0,
"goes_first": true
}
],
"merge_fields": [
{
"key": "first_name",
"label": "First name"
}
],
"to_fill": [
{
"id": "placeholder",
"position": 1,
"locale": null,
"where": "body",
"placeholder": "[First step]",
"key": null,
"message": "Email 1 still says \"First step\" in its text: replace it with your own words"
}
]
}/automations/:keyEdit an automation
Change `name`, `audience_label`, `goal_label`, `entry`, `exit_rules`, `from_name`, `from_address`, `reply_to`, or `position` (the priority order, lowest first). `settings` are merged; `entry` and `exit_rules` are replaced whole. The key and the status cannot be changed here. While the automation is on, an edit that would leave it unable to send (no goal, no sender, no entry) is refused with 422 `automation_not_ready`. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value \
-X PATCH \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Checkout recovery","position":1,"settings":{"holdout_pct":10}}'{
"id": "aut_…",
"key": "checkout-recovery",
"name": "Checkout recovery",
"domain": "example.com",
"audience_label": "Started checkout and left",
"goal_label": "paid",
"status": "draft",
"entry": {
"type": "event",
"event": "checkout_started",
"reentry": "never"
},
"exit_rules": {
"goal_event": "payment_completed",
"no_goal": false,
"stop_events": [
"account_closed"
],
"attribution_days": 14
},
"position": 1,
"settings": {
"exempt_from_hold": false,
"daily_send_cap": null,
"daily_entry_cap": null,
"holdout_pct": 0,
"stale_days": 4,
"resume_after_days": 3
},
"from_name": "Acme",
"from_address": "hello@example.com",
"reply_to": null,
"switched_on_at": null,
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z",
"steps": [
{
"id": "ast_…",
"position": 1,
"offset_seconds": 3600,
"subject": "Still thinking it over, {{ first_name | there }}?",
"preheader": "Your cart is saved",
"editor": "html",
"content": null,
"html": "<p>Your cart is waiting.</p>",
"text": "Your cart is waiting.",
"skip_if_empty": [
"fields.plan"
],
"ignore_send_window": false,
"variants": [
{
"locale": "fr",
"subject": "Vous hésitez encore, {{ first_name | bonjour }} ?",
"preheader": "",
"content": null,
"html": "<p>Votre panier vous attend.</p>",
"text": "Votre panier vous attend.",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"enrollments": {
"active": 12,
"waiting": 1
},
"overlap": [
{
"key": "trial-ending",
"name": "Trial ending",
"contacts": 3,
"position": 0,
"goes_first": true
}
],
"merge_fields": [
{
"key": "first_name",
"label": "First name"
}
],
"to_fill": [
{
"id": "placeholder",
"position": 1,
"locale": null,
"where": "body",
"placeholder": "[First step]",
"key": null,
"message": "Email 1 still says \"First step\" in its text: replace it with your own words"
}
]
}/automations/:keyDelete an automation and its history
Permanently removes the automation with its emails, language versions, enrolments, send records, and statistics. Only a draft or switched-off automation that nobody is currently in can be deleted; otherwise 409. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value \
-X DELETE \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"ok": true
}/automations/:key/steps/:positionCreate or change one email of an automation
Creates the email at `position` (1 to 50), or changes the fields sent on the one that is there; fields left out keep their value. An existing email keeps its ID, so people who already received it are not sent the edited version again. A block document in `content` sent without `html` is rendered with the workspace design. An email built in the dashboard's drag-and-drop builder has `editor` `design`: its `content` is the builder's project (opaque, cleaned when saved, accepted only with the `html` compiled from it) and its plain-text part is read from that project unless `text` is sent. An API caller who wants a designed email without the builder sends `html` with `editor` `html`. Sending a block document to a designed email makes it a written one again. With `template`, the email becomes that template of the library (GET /automation-library): its subject, preview text, content and skip rule replace the email's, its language versions are removed, and its own `offset_seconds` is kept unless one is sent. Returns 404 for an unknown template and 400 for the id of a set. While the automation is on, an email must keep a subject and content, may not hold a placeholder of the template library (in the subject, the preview text, the body, or a link's address), and may not print `{{ product_name }}` or `{{ sender_name }}` while that workspace name is blank (422 `automation_not_ready` with a `problems` list). Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/steps/position_value \
-X PUT \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"offset_seconds":86400,"subject":"Your cart is still here","html":"<p>Pick up where you left off.</p>","skip_if_empty":["fields.plan"]}'{
"id": "ast_…",
"position": 1,
"offset_seconds": 3600,
"subject": "Still thinking it over, {{ first_name | there }}?",
"preheader": "Your cart is saved",
"editor": "html",
"content": null,
"html": "<p>Your cart is waiting.</p>",
"text": "Your cart is waiting.",
"skip_if_empty": [
"fields.plan"
],
"ignore_send_window": false,
"variants": [
{
"locale": "fr",
"subject": "Vous hésitez encore, {{ first_name | bonjour }} ?",
"preheader": "",
"content": null,
"html": "<p>Votre panier vous attend.</p>",
"text": "Votre panier vous attend.",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z"
}/automations/:key/steps/:positionRemove one email from an automation
Archives the email at `position`: it is no longer sent or listed, and records of who received it are kept. The position can be used again. While the automation is on, its only email cannot be removed (409). Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/steps/position_value \
-X DELETE \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"ok": true
}/automations/:key/steps/:position/variants/:localeCreate or change a language version of an email
Saves the version of one email for contacts whose `locale` is this language tag (such as fr or pt-br): `subject`, `preheader`, and `content`, `html`, or `text`. A contact with a regional locale such as pt-br gets the pt version when there is no pt-br one. A version is made the way its email is: a designed email takes the builder's project in `content` with its `html`, or `html` alone. Fields left out keep their value; a version without a body uses the email's own body, and a blank subject or preheader falls back to the email's. Contacts without a matching version get the email as written. While the automation is on, a version is refused on the same grounds as an email: a placeholder of the template library, or a blank workspace name it prints (422 `automation_not_ready`). Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/steps/position_value/variants/locale_value \
-X PUT \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"subject":"Vous hésitez encore, {{ first_name | bonjour }} ?","html":"<p>Votre panier vous attend.</p>"}'{
"locale": "fr",
"subject": "Vous hésitez encore, {{ first_name | bonjour }} ?",
"preheader": "",
"content": null,
"html": "<p>Votre panier vous attend.</p>",
"text": "Votre panier vous attend.",
"updated_at": "2026-11-18T12:00:00.000Z"
}/automations/:key/steps/:position/testSend one email of an automation to yourself as a test
Sends the email at `position` to the account's own address (the address of the workspace's owner) and nowhere else; a recipient cannot be given. It is the email as the automation would send it: the language version for `locale` when there is one, the same sender, the same unsubscribe footer and headers, and the same checks as any send (a sender on a verified domain, an active subscription, suppressions and unsubscribes). The merge tags are filled with stand-in values, such as Alex for `first_name`; `sample` replaces any of them. The subject is prefixed `[Test] `. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's sending limits, its links and opens are not tracked, and the automation does not have to be on. It does count toward the workspace's own sending allowance, like any email. With `dry_run: true` nothing is sent and the response is the email as the test would deliver it, with `locales` (the languages it has versions for) and `sample` (the values used). Returns 422 `automation_not_ready` when the automation has no sender yet or the email has no subject or content, and 429 `test_limit_reached` after 100 test emails in 24 hours. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/steps/position_value/test \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"locale":"fr","sample":{"first_name":"Dana"}}'{
"to": "owner@example.com",
"position": 1,
"locale": null,
"subject": "[Test] Still thinking it over, Alex?",
"id": "em_…",
"status": "sent"
}/automations/:key/testSend every email of an automation to yourself as tests
Sends each email of the automation, in order, to the account's own address and nowhere else, so the whole sequence can be read in an inbox: the subjects are prefixed `[Test 1 of 3] `, `[Test 2 of 3] `, and so on, and nothing waits for the emails' delays. Everything else is as in POST /automations/{key}/steps/{position}/test: the same rendering, footer and checks, stand-in values for the merge tags (`sample` replaces any), the version for `locale` where an email has one, and no enrolment, report, tracking or sending-limit effect. Nothing is sent unless everything can be: the automation needs a sender and a subject and content on every email (422 `automation_not_ready` with a `problems` list), and room for all of them under 100 test emails in 24 hours (429 `test_limit_reached`). If a send is refused after others went out, the rest are not tried and the response is 207 with each email's outcome. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/test \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sample":{"first_name":"Dana"}}'{
"to": "owner@example.com",
"data": [
{
"position": 1,
"locale": null,
"subject": "[Test 1 of 2] Still thinking it over, Alex?",
"id": "em_…",
"status": "sent"
},
{
"position": 2,
"locale": null,
"subject": "[Test 2 of 2] Your cart is still here",
"id": "em_…",
"status": "sent"
}
],
"count": 2,
"sent": 2,
"failed": 0,
"not_sent": 0
}/automations/:key/statusTurn an automation on or off
`status` is `on` or `off`. Turning on checks that the automation can send: a way in (`entry`), a goal or an explicit `exit_rules.no_goal`, at least one email and a subject and content on every email, no placeholder of the template library such as `[First step]` or `[Link to plans]` left in any email or language version (subject, preview text, body, or a link's address), and no blank workspace name where an email prints `{{ product_name }}` or `{{ sender_name }}` (422 `automation_not_ready` with a `problems` list that names each email and detail; GET /automations/{key} lists the same under `to_fill`), a sender on a verified domain (403), and an active subscription (402 `subscription_required`). Test emails are not held back by placeholders. Once on, people who enter are emailed on the automation's schedule, within the workspace's sending limits and hours; GET /automations/{key}/preview shows who would get which email. Turning off stops new entries and sending; people already in it stay where they are and continue if it is turned on again, except that an email more than `settings.stale_days` overdue by then is skipped. People who were waiting behind it in a lower-priority automation become active there again, due after that automation's `settings.resume_after_days`. A draft cannot be turned off (409). Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/status \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"on"}'{
"id": "aut_…",
"key": "checkout-recovery",
"name": "Checkout recovery",
"domain": "example.com",
"audience_label": "Started checkout and left",
"goal_label": "paid",
"status": "on",
"entry": {
"type": "event",
"event": "checkout_started",
"reentry": "never"
},
"exit_rules": {
"goal_event": "payment_completed",
"no_goal": false,
"stop_events": [
"account_closed"
],
"attribution_days": 14
},
"position": 1,
"settings": {
"exempt_from_hold": false,
"daily_send_cap": null,
"daily_entry_cap": null,
"holdout_pct": 0,
"stale_days": 4,
"resume_after_days": 3
},
"from_name": "Acme",
"from_address": "hello@example.com",
"reply_to": null,
"switched_on_at": "2026-11-18T12:05:00.000Z",
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z"
}/automations/:key/enrollAdd a contact to an automation
Starts the automation for one existing, subscribed contact, counting from `anchor_at` (now by default; it may lie ahead, for emails that lead up to a date). `properties` are available to its emails as merge tags. The automation must be on (409 `automation_not_on`). Returns 404 when the email is not a contact, 422 `contact_not_subscribed` for a contact that cannot be mailed, and 409 when the contact is already in it (`already_enrolled`) or went through it before and `entry.reentry` is `never` (`reentry_not_allowed`). Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/enroll \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.net","properties":{"plan":"pro"},"anchor_at":"2026-11-25T09:00:00.000Z"}'{
"id": "aen_…",
"automation_key": "checkout-recovery",
"contact_id": "ct_…",
"status": "active",
"source": "api",
"is_holdout": false,
"anchor_at": "2026-11-18T12:00:00.000Z",
"entered_at": "2026-11-18T12:00:00.000Z",
"next_due_at": "2026-11-18T13:00:00.000Z",
"exit_reason": null,
"ended_at": null,
"converted_at": null
}/automations/:key/exitTake a contact out of an automation
Ends the contact's open enrolment in this automation, with an optional `reason` (up to 200 characters). No further emails of it are sent to them. Returns 404 when the contact is not in it. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/exit \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.net","reason":"Asked support to stop"}'{
"id": "aen_…",
"automation_key": "checkout-recovery",
"contact_id": "ct_…",
"status": "exited",
"source": "api",
"is_holdout": false,
"anchor_at": "2026-11-18T12:00:00.000Z",
"entered_at": "2026-11-18T12:00:00.000Z",
"next_due_at": null,
"exit_reason": "Asked support to stop",
"ended_at": "2026-11-18T12:30:00.000Z",
"converted_at": null
}/automations/:key/previewDry run: what each person in an automation would get now
For the people in this automation now (active and waiting, in the order they come due; `limit` up to 200 and `offset` page through them), what would happen if each were evaluated at this moment. Nothing is sent, claimed, or changed. `outcome` is `send` (the email in `step` would go out now), `scheduled` (nothing is due before `until`; `step` is the email due then), `held` (the email waits until `until`, and `reason` says what holds it: `limit_cap` for the workspace's `max_emails` in `period_days`, `limit_gap` for `min_gap_hours`, `window` for the sending hours, `daily_cap` for the automation's `daily_send_cap`), `waiting` (behind the higher-priority automation in `behind`), `skip` (the email would be skipped: `stale`, `empty_field`, or `holdout`), `exit` (the contact can no longer be mailed and would leave the automation; `reason` says why), `complete` (no email is left), `blocked` (nobody is evaluated: `automation_off` or `subscription_required`), or `in_progress` (an interrupted attempt at this email is settled first). `superseded` lists the positions of earlier emails the chosen one replaces, and `counts` totals the outcomes on this page. These are the rules the automation itself applies; a refusal that only a real send meets, such as the workspace's daily sending limit or a paused sender, is not foreseen here. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/preview \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"automation_key": "checkout-recovery",
"status": "on",
"evaluated_at": "2026-11-18T12:00:00.000Z",
"data": [
{
"enrollment_id": "aen_…",
"contact_id": "ct_…",
"email": "ada@example.net",
"status": "active",
"next_due_at": "2026-11-18T11:58:00.000Z",
"outcome": "send",
"reason": null,
"until": null,
"step": {
"position": 2,
"subject": "Your cart is still here",
"locale": null
},
"behind": null,
"superseded": [
1
]
},
{
"enrollment_id": "aen_…",
"contact_id": "ct_…",
"email": "grace@example.net",
"status": "active",
"next_due_at": "2026-11-18T11:59:00.000Z",
"outcome": "held",
"reason": "limit_gap",
"until": "2026-11-19T09:00:00.000Z",
"step": {
"position": 1,
"subject": "Still thinking it over, Grace?",
"locale": null
},
"behind": null,
"superseded": []
}
],
"count": 2,
"counts": {
"send": 1,
"held": 1
}
}/automations/overviewTotals and a daily series across every automation
What every automation of the workspace did between `from` and `to` (UTC dates, both inclusive; the last 30 days by default, at most 366 days): `totals` and one `series` entry per day, each with people who entered, emails sent, delivered, opened, clicked, and converted (a goal event credited to an email), plus bounces, complaints, unsubscribes, and `held`. Days on which nothing happened are in the series with zeros. `domain` narrows it to the automations that send from one domain (the exact domain of their `from_address`, such as example.com; `none` for automations with no sender yet). Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are stored but never counted. Never claim that a person read an email. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/overview \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"from": "2026-11-17",
"to": "2026-11-18",
"totals": {
"entered": 3,
"sent": 5,
"delivered": 5,
"opened": 2,
"clicked": 1,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 1
},
"series": [
{
"day": "2026-11-17",
"entered": 3,
"sent": 5,
"delivered": 5,
"opened": 2,
"clicked": 1,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 1
},
{
"day": "2026-11-18",
"entered": 0,
"sent": 0,
"delivered": 0,
"opened": 0,
"clicked": 0,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 0
}
]
}/automations/:key/reportResults of one automation, with one row per email
The same `totals` and daily `series` as GET /automations/overview for one automation, and `steps`: one row per email with what it sent and what came of it in the range. Emails the automation has now are always listed, in order; a removed email is listed after them, with `archived: true`, while it still has numbers in the range. `from` and `to` are UTC dates, both inclusive (the last 30 days by default, at most 366 days). Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are stored but never counted. Never claim that a person read an email. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/report \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"automation": {
"key": "checkout-recovery",
"name": "Checkout recovery",
"status": "on",
"goal_label": "paid"
},
"from": "2026-11-17",
"to": "2026-11-18",
"totals": {
"entered": 3,
"sent": 5,
"delivered": 5,
"opened": 2,
"clicked": 1,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 1
},
"series": [
{
"day": "2026-11-17",
"entered": 3,
"sent": 5,
"delivered": 5,
"opened": 2,
"clicked": 1,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 1
},
{
"day": "2026-11-18",
"entered": 0,
"sent": 0,
"delivered": 0,
"opened": 0,
"clicked": 0,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 0
}
],
"steps": [
{
"step_id": "ast_…",
"position": 1,
"subject": "Still thinking it over, {{ first_name | there }}?",
"offset_seconds": 3600,
"archived": false,
"sent": 3,
"delivered": 3,
"opened": 2,
"clicked": 1,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 1
},
{
"step_id": "ast_…",
"position": 2,
"subject": "Your cart is still here",
"offset_seconds": 86400,
"archived": false,
"sent": 2,
"delivered": 2,
"opened": 0,
"clicked": 0,
"converted": 0,
"bounced": 0,
"complained": 0,
"unsubscribed": 0,
"held": 0
}
]
}/automations/:key/peopleList the people in an automation by what they did
One row per person who did `did` in this automation, most recent first: `entered` (the default: everyone who was ever in it), `sent`, `delivered`, `opened`, `clicked`, `converted` (their goal was credited to an email), `bounced`, `unsubscribed`, or `waiting` (waiting now behind a higher-priority automation). `step` (an email's position, or its `ast_` ID) narrows every filter except `entered` and `waiting` to one email. Each row has the contact's email and name, `at` (when they did it), their enrolment's status, and `latest`: the most recent thing that happened to them in the automation (`did` is entered, sent, delivered, opened, clicked, bounced, complained, unsubscribed, converted, completed, or exited, with its time, the email's position, and the reason for an exit). `counts` says how many people each filter would list. Pages are keyset pages: pass `next_cursor` as `cursor` for the next one (null on the last), with `limit` up to 200. `offset` skips rows instead, for clients that page by position; it cannot be combined with `cursor`. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are stored but never counted. Never claim that a person read an email. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/people \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"automation_key": "checkout-recovery",
"did": "clicked",
"step": null,
"data": [
{
"contact_id": "ct_…",
"email": "ada@example.net",
"name": "Ada Lovelace",
"contact_status": "subscribed",
"enrollment_id": "aen_…",
"enrollment_status": "converted",
"at": "2026-11-12T10:12:00.000Z",
"latest": {
"did": "converted",
"at": "2026-11-13T09:40:00.000Z",
"step_position": 1,
"reason": null
}
}
],
"count": 1,
"next_cursor": null,
"counts": {
"entered": 40,
"sent": 38,
"delivered": 38,
"opened": 22,
"clicked": 7,
"converted": 5,
"bounced": 1,
"unsubscribed": 1,
"waiting": 2
}
}/automations/:key/people/:contact_idOne person's history in an automation
Everything that happened to one contact in this automation: each enrolment with how it ended, each email with when it was sent, delivered, first opened, first clicked, bounced, complained about, or unsubscribed from, the individual opens and clicks on it (`machine: true` marks an automated request, with the `reason`; those are not counted), and the `conversion` with the email it was credited to. A click's `url` is the email's link at that position. Returns 404 for a contact that was never in the automation. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are stored but never counted. Never claim that a person read an email. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/people/contact_id_value \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"automation_key": "checkout-recovery",
"contact": {
"id": "ct_…",
"email": "ada@example.net",
"name": "Ada Lovelace",
"status": "subscribed"
},
"enrollments": [
{
"id": "aen_…",
"status": "converted",
"source": "event",
"is_holdout": false,
"anchor_at": "2026-11-12T09:00:00.000Z",
"entered_at": "2026-11-12T09:00:00.000Z",
"next_due_at": null,
"last_sent_at": "2026-11-12T10:00:00.000Z",
"exit_reason": "event:payment_completed",
"ended_at": "2026-11-13T09:40:00.000Z",
"converted_at": "2026-11-13T09:40:00.000Z",
"converted_send_id": "asd_…"
}
],
"sends": [
{
"id": "asd_…",
"enrollment_id": "aen_…",
"step_id": "ast_…",
"step_position": 1,
"subject": "Still thinking it over, Ada?",
"status": "sent",
"skip_reason": null,
"locale": null,
"email_id": "em_…",
"sent_at": "2026-11-12T10:00:00.000Z",
"delivered_at": "2026-11-12T10:00:04.000Z",
"opened_at": "2026-11-12T10:06:00.000Z",
"clicked_at": "2026-11-12T10:12:00.000Z",
"bounced_at": null,
"complained_at": null,
"unsubscribed_at": null,
"converted_at": "2026-11-13T09:40:00.000Z",
"open_count": 1,
"machine_open_count": 1,
"click_count": 1,
"events": [
{
"kind": "open",
"machine": true,
"reason": "apple_privacy_prefetch",
"position": null,
"url": null,
"country": "GB",
"at": "2026-11-12T10:00:09.000Z"
},
{
"kind": "open",
"machine": false,
"reason": null,
"position": null,
"url": null,
"country": "GB",
"at": "2026-11-12T10:06:00.000Z"
},
{
"kind": "click",
"machine": false,
"reason": null,
"position": 0,
"url": "https://example.com/checkout",
"country": "GB",
"at": "2026-11-12T10:12:00.000Z"
}
]
}
],
"conversion": {
"enrollment_id": "aen_…",
"converted_at": "2026-11-13T09:40:00.000Z",
"goal_event": "payment_completed",
"send_id": "asd_…",
"step_position": 1
}
}/automations/:key/import-historyRecord emails another system already sent
For moving a sequence over from another tool. `rows` is up to 500 entries of `{ email, step_position, sent_at }`: each records that the contact already received that email, so it is not sent again and counts toward reports and sending limits. Nothing is emailed. A contact with emails left continues from there once the automation is on; one that got every email is complete; one that can no longer be mailed gets the history only. Unknown addresses come back in `not_found`, unusable rows in `invalid`, and running the same rows again changes nothing. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automations/key_value/import-history \
-X POST \
-H "Cookie: sendhq_session_v2=…" \
-H "Content-Type: application/json" \
-d '{"rows":[{"email":"ada@example.net","step_position":1,"sent_at":"2026-11-10T09:00:00.000Z"}]}'{
"imported": 1,
"already_recorded": 0,
"enrollments_created": 1,
"not_found": [
"unknown@example.net"
],
"invalid": [
{
"index": 3,
"reason": "no email at position 9"
}
]
}/automation-settingsRetrieve the workspace's sending limits for automations
How much automation email one person may get across every automation, and when: at most `max_emails` in any `period_days`, at least `min_gap_hours` apart, only between `window_start` and `window_end` (hours, in the contact's time zone or `default_timezone`) on `weekdays` (0 is Sunday, 6 is Saturday). An email that would break a limit is not dropped: it waits until the earliest moment the limits allow. `product_name` and `sender_name` are available to every automation email as merge tags. Defaults are returned until they are changed. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automation-settings \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"max_emails": 2,
"period_days": 7,
"min_gap_hours": 44,
"window_start": 9,
"window_end": 18,
"weekdays": [
1,
2,
3,
4,
5
],
"default_timezone": "Europe/London",
"product_name": "Acme",
"sender_name": "Dana",
"updated_at": "2026-11-18T12:00:00.000Z"
}/automation-settingsChange the workspace's sending limits for automations
Change any of the fields returned by GET /automation-settings; fields left out keep their value. `window_end` must be later than `window_start`. `product_name` or `sender_name` cannot be cleared while an automation that is on prints it (409 `workspace_name_in_use`). Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automation-settings \
-X PUT \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"max_emails":3,"min_gap_hours":24,"default_timezone":"Europe/London","product_name":"Acme","sender_name":"Dana"}'{
"max_emails": 2,
"period_days": 7,
"min_gap_hours": 44,
"window_start": 9,
"window_end": 18,
"weekdays": [
1,
2,
3,
4,
5
],
"default_timezone": "Europe/London",
"product_name": "Acme",
"sender_name": "Dana",
"updated_at": "2026-11-18T12:00:00.000Z"
}/automation-libraryList the template library: ready-made lifecycle emails
Finished emails to start an automation from instead of writing one. The library covers the emails a product sends through a customer's life: welcome, onboarding tips, a nudge to finish setup (activation), trial ending and trial ended, abandoned checkout, failed payment (dunning), receipt, upgrade at a usage limit, feature announcement, review request, feedback score (NPS), cancellation survey, and winback for retention. `data` is every template with its `name`, one-line `purpose`, `group` (the goal it serves, in the order of `groups`), `subject`, `preview_text`, the merge tags it prints (`merge_keys`), and `start`: the suggested `entry`, the email's wait (`offset_seconds`), the `goal_event` that ends the automation for a person (null when there is none) and `skip_if_empty`. Every suggested start is an event (one your payment connection records, such as `paid`, `payment_failed`, `checkout_abandoned` or `subscription_cancelled`, or one your own code sends, such as `signed_up`, `trial_ending` or `usage_limit_near`) or `manual`. `sets` are templates that belong together and arrive as one automation: the three onboarding tips, trial ending and trial ended, and payment failed with its last notice; a template in a set names it in `set`. A template is finished except for what only the customer knows, written as placeholders in square brackets such as `[First step]` (and `[Link to plans]` as the address of a link). `fill_in` lists them with a plain-word `label` and, for text, an `example`; it also lists the workspace names the email prints (`kind` is `setting`; set them with PUT /automation-settings). `needs_consent` marks promotional email, which may go only to people who agreed to marketing email. Email bodies are not included: read one with GET /automation-library/{id}. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automation-library \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"version": 1,
"groups": [
"Welcome",
"Onboarding",
"Trial",
"Checkout",
"Payments",
"Receipts",
"Upgrade",
"Announce",
"Feedback",
"Leaving",
"Win back"
],
"data": [
{
"id": "welcome-note",
"kind": "email",
"name": "Welcome note",
"purpose": "A personal hello with one first step and one question",
"group": "Welcome",
"set": null,
"subject": "Welcome to {{ product_name }}",
"preview_text": "One thing to do first, and one question for you.",
"needs_consent": false,
"start": {
"entry": {
"type": "event",
"event": "signed_up",
"reentry": "never"
},
"offset_seconds": 0,
"goal_event": null,
"goal_label": "",
"skip_if_empty": []
},
"merge_keys": [
"product_name",
"first_name",
"sender_name"
],
"fill_in": [
{
"kind": "setting",
"key": "product_name",
"placeholder": null,
"label": "Your product's name",
"example": null
},
{
"kind": "text",
"key": null,
"placeholder": "[First step]",
"label": "The one thing a new user should do first",
"example": "connect your calendar"
},
{
"kind": "link",
"key": null,
"placeholder": "[Link to the first step]",
"label": "The page where that first step happens",
"example": null
}
]
}
],
"sets": [
{
"id": "onboarding-tips",
"kind": "set",
"name": "Three onboarding tips",
"purpose": "One feature per email over a new user's first week",
"group": "Onboarding",
"needs_consent": false,
"emails": [
{
"template": "onboarding-tip-1",
"offset_seconds": 86400
},
{
"template": "onboarding-tip-2",
"offset_seconds": 259200
},
{
"template": "onboarding-tip-3",
"offset_seconds": 432000
}
],
"start": {
"entry": {
"type": "event",
"event": "signed_up",
"reentry": "never"
},
"goal_event": "activated",
"goal_label": "activated"
},
"merge_keys": [
"product_name",
"first_name"
],
"fill_in": [
{
"kind": "setting",
"key": "product_name",
"placeholder": null,
"label": "Your product's name",
"example": null
},
{
"kind": "text",
"key": null,
"placeholder": "[First step]",
"label": "The one thing a new user should do first",
"example": "connect your calendar"
},
{
"kind": "link",
"key": null,
"placeholder": "[Link to the first step]",
"label": "The page where that first step happens",
"example": null
}
]
}
],
"count": 18
}/automation-library/:idRead one template or set, with the email as it will look
One template, or one set, by `id`, as the draft automation it would make: its `start` (the `entry`, the `goal_event` and a word for having reached it), `fill_in`, and `emails` in order, each with its wait (`offset_seconds`), `subject`, `preview_text`, the email as a block document (`content`, the form PUT /automations/{key}/steps/{position} takes), and `preview`: the email as this workspace would send it, with its design, sample values in place of the merge tags, and the unsubscribe footer. `preview.text` is always there; `preview.html` is null unless `html=true` is sent. In a preview a workspace name that is not set yet reads "Your product" or "Your name"; in a real email it would be blank, which is why switching on is refused until it is set. Placeholders are shown as written. Returns 404 for an unknown id. The library covers the emails a product sends through a customer's life: welcome, onboarding tips, a nudge to finish setup (activation), trial ending and trial ended, abandoned checkout, failed payment (dunning), receipt, upgrade at a usage limit, feature announcement, review request, feedback score (NPS), cancellation survey, and winback for retention. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automation-library/id_value \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"id": "welcome-note",
"kind": "email",
"name": "Welcome note",
"purpose": "A personal hello with one first step and one question",
"group": "Welcome",
"set": null,
"needs_consent": false,
"start": {
"entry": {
"type": "event",
"event": "signed_up",
"reentry": "never"
},
"goal_event": null,
"goal_label": ""
},
"merge_keys": [
"product_name",
"first_name",
"sender_name"
],
"fill_in": [
{
"kind": "setting",
"key": "product_name",
"placeholder": null,
"label": "Your product's name",
"example": null
},
{
"kind": "text",
"key": null,
"placeholder": "[First step]",
"label": "The one thing a new user should do first",
"example": "connect your calendar"
},
{
"kind": "link",
"key": null,
"placeholder": "[Link to the first step]",
"label": "The page where that first step happens",
"example": null
}
],
"emails": [
{
"template": "welcome-note",
"name": "Welcome note",
"offset_seconds": 0,
"skip_if_empty": [],
"subject": "Welcome to {{ product_name }}",
"preview_text": "One thing to do first, and one question for you.",
"content": {
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Hi "
},
{
"type": "mergeTag",
"attrs": {
"key": "first_name",
"fallback": "there"
}
},
{
"type": "text",
"text": ","
}
]
}
]
},
"preview": {
"subject": "Welcome to Acme",
"preheader": "One thing to do first, and one question for you.",
"text": "Hi Alex,\n\nI'm Dana, and I work on Acme. Thank you for signing up.\n\nThe best place to start is to [First step]. …",
"html": null
}
}
]
}/automation-library/:id/useCreate a draft automation from a template or set
Makes a new automation from one template (one email) or one set (two or three), as a draft: the emails as the library has them, each at its wait, the suggested `entry`, and the suggested goal (`exit_rules.goal_event` with a `goal_label`, or `no_goal` where the template has none). Nothing is sent. The body is optional: `name` (the template's own by default), `key` (by default the template's id, with a number added when that is taken), and the sender (`from_name`, `from_address` on a verified domain, `reply_to`). The response is the automation as GET /automations/{key} returns it, with `template` and `to_fill`: every placeholder to replace, by email, and each workspace name the emails print that is still blank. Replace them with PUT /automations/{key}/steps/{position} and PUT /automation-settings; until then POST /automations/{key}/status refuses to turn it on (422 `automation_not_ready`), while test emails are allowed. The start is a suggestion: change it with PATCH /automations/{key}, and make sure the event it names is one your code or a connection records (GET /events/names). Returns 404 for an unknown id and 409 when `key` is taken. The library covers the emails a product sends through a customer's life: welcome, onboarding tips, a nudge to finish setup (activation), trial ending and trial ended, abandoned checkout, failed payment (dunning), receipt, upgrade at a usage limit, feature announcement, review request, feedback score (NPS), cancellation survey, and winback for retention. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/automation-library/id_value/use \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Welcome","from_name":"Dana from Acme","from_address":"dana@example.com"}'{
"id": "aut_…",
"key": "welcome-note",
"name": "Welcome",
"domain": "example.com",
"audience_label": "Started checkout and left",
"goal_label": "paid",
"status": "draft",
"entry": {
"type": "event",
"event": "checkout_started",
"reentry": "never"
},
"exit_rules": {
"goal_event": "payment_completed",
"no_goal": false,
"stop_events": [
"account_closed"
],
"attribution_days": 14
},
"position": 1,
"settings": {
"exempt_from_hold": false,
"daily_send_cap": null,
"daily_entry_cap": null,
"holdout_pct": 0,
"stale_days": 4,
"resume_after_days": 3
},
"from_name": "Acme",
"from_address": "hello@example.com",
"reply_to": null,
"switched_on_at": null,
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z",
"steps": [
{
"id": "ast_…",
"position": 1,
"offset_seconds": 3600,
"subject": "Still thinking it over, {{ first_name | there }}?",
"preheader": "Your cart is saved",
"editor": "html",
"content": null,
"html": "<p>Your cart is waiting.</p>",
"text": "Your cart is waiting.",
"skip_if_empty": [
"fields.plan"
],
"ignore_send_window": false,
"variants": [
{
"locale": "fr",
"subject": "Vous hésitez encore, {{ first_name | bonjour }} ?",
"preheader": "",
"content": null,
"html": "<p>Votre panier vous attend.</p>",
"text": "Votre panier vous attend.",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"created_at": "2026-11-18T12:00:00.000Z",
"updated_at": "2026-11-18T12:00:00.000Z"
}
],
"enrollments": {
"active": 0,
"waiting": 0
},
"overlap": [],
"merge_fields": [
{
"key": "first_name",
"label": "First name"
}
],
"to_fill": [
{
"id": "placeholder",
"position": 1,
"locale": null,
"where": "body",
"placeholder": "[First step]",
"key": null,
"message": "Email 1 still says \"First step\" in its text: replace it with your own words"
}
],
"template": "welcome-note"
}/eventsList what contacts did, newest first
The events recorded for the workspace, newest first by `occurred_at`. Each has the contact (`id`, `email`, `name`), the event's name and the same name as words (`checkout_started` reads `checkout started`), when it happened and when it was received, its `properties`, where it came from (`source.type` is `api` for your own code, `connection` with the connection's name, `upload` for a spreadsheet, or `system` for SendHQ itself), and `effects`: the automations it `started`, `ended`, or `converted` for that contact, by key and name. Filter with `contact` (a contact ID or an email address), `name` (one event name), and `from` and `to` (a UTC date, or a date-time). With `contact`, the response also has `enrollments`: every automation that contact is or was in. Pages are keyset pages: pass `next_cursor` as `cursor` (null on the last page), with `limit` up to 200; `offset` skips rows instead and cannot be combined with `cursor`. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/events \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"data": [
{
"id": "cev_…",
"contact": {
"id": "ct_…",
"email": "ada@example.net",
"name": "Ada Lovelace"
},
"event": "checkout_started",
"words": "checkout started",
"occurred_at": "2026-11-19T09:12:00.000Z",
"received_at": "2026-11-19T09:12:01.000Z",
"source": {
"type": "connection",
"label": "Stripe",
"connection_id": "acn_…"
},
"properties": {
"plan": "pro"
},
"effects": [
{
"did": "started",
"automation_key": "checkout-recovery",
"automation_name": "Checkout recovery"
}
]
}
],
"count": 1,
"next_cursor": null
}/events/namesList the kinds of event recorded in the last 30 days
Every distinct event name recorded in the last 30 days with how many times, the most frequent first (at most 200), each with the name as words. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/events/names \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"data": [
{
"event": "checkout_started",
"words": "checkout started",
"count": 128
}
],
"count": 1,
"days": 30
}/events/previewDry run: what a set of events would start and end
Takes up to 5,000 events (`email`, `event`, and optionally the `dedupe_key` each would be sent with) and answers what recording them, in this order, would do, without recording anything: `would_start` and `would_end` list the automations with how many people each, decided by the same rules POST /events applies. An event whose `dedupe_key` was already recorded, or appears earlier in the same request, counts under `already_recorded` and does nothing; `already_recorded_indexes` gives the positions of those events in the request, so they can be left out of what is then submitted. People who are not contacts yet are `unknown` and start nothing, as POST /events refuses a new contact without a consent basis; with `add_missing_contacts: true` they are counted as if they had been added first (unless their address is suppressed or unsubscribed), which is what a spreadsheet upload does. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/events/preview \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"email":"ada@example.net","event":"checkout_started"},{"email":"grace@example.net","event":"checkout_started"}],"add_missing_contacts":true}'{
"dry_run": true,
"events": 2,
"people": 2,
"new_people": 1,
"unknown": 0,
"invalid": 0,
"already_recorded": 0,
"already_recorded_indexes": [],
"would_start": [
{
"automation_key": "checkout-recovery",
"automation_name": "Checkout recovery",
"people": 2
}
],
"would_end": []
}/connectionsList the workspace's connections (incoming webhooks)
A connection is a secret address another system posts to, such as a payment provider's webhook; what arrives is recorded as events, exactly as POST /events records them. Each connection has its `kind` (`stripe`, `dodo`, or `generic`), whether it is `enabled`, the `consent_basis` recorded on contacts it creates, an optional `event_prefix`, whether a signing secret is set (`has_signing_secret`; the secret itself is never returned), the last four characters of its address (`address_ending`; the address is shown only when it is made), and `last_delivery` in plain words. A workspace may have 10. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/connections \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"data": [
{
"id": "acn_…",
"name": "Stripe",
"kind": "stripe",
"enabled": true,
"event_prefix": "",
"consent_basis": "Bought a plan on acme.com and accepted product emails",
"has_signing_secret": true,
"address_ending": "c2e1",
"last_delivery": {
"id": "acd_…",
"at": "2026-11-19T09:12:00.000Z",
"result": "recorded",
"reason": null,
"recorded": 2,
"events": [
"checkout_completed",
"paid"
],
"text": "Recorded 2 events",
"provider_event": "checkout.session.completed",
"email": "ada@example.net"
},
"created_at": "2026-11-19T09:00:00.000Z",
"updated_at": "2026-11-19T09:00:00.000Z"
}
],
"count": 1,
"limit": 10
}/connectionsCreate a connection and get its address
Creates a connection of `kind` `stripe`, `dodo`, or `generic` and returns its `address` (`https://…/api/hooks/<token>`) once: only a hash of the token is stored, so it cannot be read again (POST /connections/{id}/address makes a new one). From then on, whatever that system posts to the address is recorded as events, and a recorded event can start an automation that sends email. `consent_basis` is required: it is recorded on every contact the connection creates. `event_prefix` is put in front of every event name (for example `stripe_`). `signing_secret` (Stripe and Dodo Payments) is the secret the provider shows for the endpoint: once set, a delivery without a valid signature is refused. A `generic` connection needs a `mapping` of dotted paths into the payload: `email`, then either `event` (where the payload names what happened) or `event_name` (one fixed name), and optionally `time`, `id` (a unique ID, so a retried delivery is recorded once), and `keep` (the fields to keep as properties; by default the top-level text, number, and boolean fields). Stripe and Dodo Payments are mapped for you; see the Events guide. Returns 409 `connection_limit_reached` at 10 connections. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/connections \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Stripe","kind":"stripe","consent_basis":"Bought a plan on acme.com and accepted product emails"}'{
"id": "acn_…",
"name": "Stripe",
"kind": "stripe",
"enabled": true,
"event_prefix": "",
"consent_basis": "Bought a plan on acme.com and accepted product emails",
"has_signing_secret": true,
"address_ending": "c2e1",
"last_delivery": null,
"created_at": "2026-11-19T09:00:00.000Z",
"updated_at": "2026-11-19T09:00:00.000Z",
"address": "https://sendhq.cc/api/hooks/3f9a…c2e1"
}/connections/testDry run: what a sample payload would record
Maps a sample `payload` (an object, a list, or the JSON as a string) the way a connection would and returns the events it would record, with each name as words. Nothing is recorded and no signature is checked. Pass `connection_id` to use a saved connection (with `mapping` to try a mapping that is not saved yet), or `kind` with `mapping` and `event_prefix` to try settings before creating one. `result` is `recorded` or `skipped`, and `text` says which in plain words, such as "Would skip: no email address". Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/connections/test \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"generic","mapping":{"email":"customer.email","event":"type"},"payload":{"type":"order.placed","plan":"pro","customer":{"email":"ada@example.net"}}}'{
"dry_run": true,
"result": "recorded",
"reason": null,
"text": "Would record 1 event",
"provider_event": "order.placed",
"events": [
{
"email": "ada@example.net",
"event": "order_placed",
"words": "order placed",
"occurred_at": null,
"properties": {
"plan": "pro"
}
}
]
}/connections/:idRetrieve a connection with its last deliveries
The connection and `deliveries`: its last 50, newest first. A delivery records the time, the `result` (`recorded`, `skipped`, or `refused`) with a `reason` and the same in plain words (`text`, such as "Recorded 2 events", "Skipped: no email address", or "Refused: bad signature"), the sender's own event type, the names of the events recorded, and the contact's email address. Payloads are not stored. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/connections/id_value \
-X GET \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"id": "acn_…",
"name": "Stripe",
"kind": "stripe",
"enabled": true,
"event_prefix": "",
"consent_basis": "Bought a plan on acme.com and accepted product emails",
"has_signing_secret": true,
"address_ending": "c2e1",
"last_delivery": {
"id": "acd_…",
"at": "2026-11-19T09:12:00.000Z",
"result": "recorded",
"reason": null,
"recorded": 2,
"events": [
"checkout_completed",
"paid"
],
"text": "Recorded 2 events",
"provider_event": "checkout.session.completed",
"email": "ada@example.net"
},
"created_at": "2026-11-19T09:00:00.000Z",
"updated_at": "2026-11-19T09:00:00.000Z",
"deliveries": [
{
"id": "acd_…",
"at": "2026-11-19T09:12:00.000Z",
"result": "recorded",
"reason": null,
"recorded": 2,
"events": [
"checkout_completed",
"paid"
],
"text": "Recorded 2 events",
"provider_event": "checkout.session.completed",
"email": "ada@example.net"
}
]
}/connections/:idChange a connection or switch it on or off
Change `name`, `enabled`, `consent_basis`, `event_prefix`, `signing_secret` (null removes it), or a generic connection's `mapping`. The kind cannot be changed. While `enabled` is false the address answers 404 and records nothing; switching it back on lets what arrives start automations again. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/connections/id_value \
-X PATCH \
-H "Authorization: Bearer $SENDHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled":false}'{
"id": "acn_…",
"name": "Stripe",
"kind": "stripe",
"enabled": true,
"event_prefix": "",
"consent_basis": "Bought a plan on acme.com and accepted product emails",
"has_signing_secret": true,
"address_ending": "c2e1",
"created_at": "2026-11-19T09:00:00.000Z",
"updated_at": "2026-11-19T09:00:00.000Z"
}/connections/:idDelete a connection
Removes the connection with its delivery records. Its address stops working at once. The events it recorded stay, as part of each contact's history. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/connections/id_value \
-X DELETE \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"ok": true
}/connections/:id/addressReplace a connection's address
Makes a new secret address for the connection and returns it once. The old address stops working in the same moment, so the sender must be given the new one. Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 `automations_not_enabled`.
curl https://sendhq.cc/api/v1/connections/id_value/address \
-X POST \
-H "Authorization: Bearer $SENDHQ_API_KEY"{
"id": "acn_…",
"name": "Stripe",
"kind": "stripe",
"enabled": true,
"event_prefix": "",
"consent_basis": "Bought a plan on acme.com and accepted product emails",
"has_signing_secret": true,
"address_ending": "7a40",
"created_at": "2026-11-19T09:00:00.000Z",
"updated_at": "2026-11-19T09:00:00.000Z",
"address": "https://sendhq.cc/api/hooks/8b1d…7a40"
}