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.

POST/events
API key

Record 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`.

Optional headersIdempotency-Key
Request
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"}}'
201 Response
{
  "id": "cev_…",
  "contact_id": "ct_…",
  "started": [
    "checkout-recovery"
  ],
  "ended": [
    "trial-ending"
  ]
}
POST/events/batch
API key

Record 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`.

Optional headersIdempotency-Key
Request
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"}]}'
201 Response
{
  "data": [
    {
      "index": 0,
      "ok": true,
      "id": "cev_…",
      "contact_id": "ct_…",
      "started": [
        "checkout-recovery"
      ],
      "ended": [
        "trial-ending"
      ]
    }
  ],
  "count": 1,
  "successful": 1,
  "failed": 0
}
GET/automations
API key

List 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`.

Query parametersdomain
Request
curl https://sendhq.cc/api/v1/automations \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
    }
  ]
}
POST/automations
API key

Create 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`.

Request
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>"}]}'
201 Response
{
  "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"
    }
  ]
}
GET/automations/:key
API key

Retrieve 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`.

Request
curl https://sendhq.cc/api/v1/automations/key_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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"
    }
  ]
}
PATCH/automations/:key
API key

Edit 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`.

Request
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}}'
200 Response
{
  "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"
    }
  ]
}
DELETE/automations/:key
API key

Delete 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`.

Request
curl https://sendhq.cc/api/v1/automations/key_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "ok": true
}
PUT/automations/:key/steps/:position
API key

Create 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`.

Request
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"]}'
200 Response
{
  "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"
}
DELETE/automations/:key/steps/:position
API key

Remove 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`.

Request
curl https://sendhq.cc/api/v1/automations/key_value/steps/position_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "ok": true
}
PUT/automations/:key/steps/:position/variants/:locale
API key

Create 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`.

Request
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>"}'
200 Response
{
  "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"
}
POST/automations/:key/steps/:position/test
API key

Send 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`.

Request
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"}}'
201 Response
{
  "to": "owner@example.com",
  "position": 1,
  "locale": null,
  "subject": "[Test] Still thinking it over, Alex?",
  "id": "em_…",
  "status": "sent"
}
POST/automations/:key/test
API key

Send 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`.

Request
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"}}'
201 Response
{
  "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
}
POST/automations/:key/status
API key

Turn 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`.

Request
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"}'
200 Response
{
  "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"
}
POST/automations/:key/enroll
API key

Add 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`.

Request
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"}'
201 Response
{
  "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
}
POST/automations/:key/exit
API key

Take 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`.

Request
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"}'
200 Response
{
  "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
}
GET/automations/:key/preview
API key

Dry 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`.

Query parameterslimitoffset
Request
curl https://sendhq.cc/api/v1/automations/key_value/preview \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
  }
}
GET/automations/overview
API key

Totals 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`.

Query parametersfromtodomain
Request
curl https://sendhq.cc/api/v1/automations/overview \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
    }
  ]
}
GET/automations/:key/report
API key

Results 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`.

Query parametersfromto
Request
curl https://sendhq.cc/api/v1/automations/key_value/report \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
    }
  ]
}
GET/automations/:key/people
API key

List 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`.

Query parametersdidstepcursorlimitoffset
Request
curl https://sendhq.cc/api/v1/automations/key_value/people \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
  }
}
GET/automations/:key/people/:contact_id
API key

One 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`.

Request
curl https://sendhq.cc/api/v1/automations/key_value/people/contact_id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
  }
}
POST/automations/:key/import-history
Browser session

Record 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`.

Request
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"}]}'
200 Response
{
  "imported": 1,
  "already_recorded": 0,
  "enrollments_created": 1,
  "not_found": [
    "unknown@example.net"
  ],
  "invalid": [
    {
      "index": 3,
      "reason": "no email at position 9"
    }
  ]
}
GET/automation-settings
API key

Retrieve 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`.

Request
curl https://sendhq.cc/api/v1/automation-settings \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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"
}
PUT/automation-settings
API key

Change 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`.

Request
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"}'
200 Response
{
  "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"
}
GET/automation-library
API key

List 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`.

Request
curl https://sendhq.cc/api/v1/automation-library \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
}
GET/automation-library/:id
API key

Read 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`.

Query parametershtml
Request
curl https://sendhq.cc/api/v1/automation-library/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
      }
    }
  ]
}
POST/automation-library/:id/use
API key

Create 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`.

Request
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"}'
201 Response
{
  "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"
}
GET/events
API key

List 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`.

Query parameterscontactnamefromtocursorlimitoffset
Request
curl https://sendhq.cc/api/v1/events \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
}
GET/events/names
API key

List 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`.

Request
curl https://sendhq.cc/api/v1/events/names \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "data": [
    {
      "event": "checkout_started",
      "words": "checkout started",
      "count": 128
    }
  ],
  "count": 1,
  "days": 30
}
POST/events/preview
API key

Dry 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`.

Request
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}'
200 Response
{
  "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": []
}
GET/connections
API key

List 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`.

Request
curl https://sendhq.cc/api/v1/connections \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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
}
POST/connections
API key

Create 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`.

Request
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"}'
201 Response
{
  "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"
}
POST/connections/test
API key

Dry 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`.

Request
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"}}}'
200 Response
{
  "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"
      }
    }
  ]
}
GET/connections/:id
API key

Retrieve 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`.

Request
curl https://sendhq.cc/api/v1/connections/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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"
    }
  ]
}
PATCH/connections/:id
API key

Change 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`.

Request
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}'
200 Response
{
  "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"
}
DELETE/connections/:id
API key

Delete 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`.

Request
curl https://sendhq.cc/api/v1/connections/id_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "ok": true
}
POST/connections/:id/address
API key

Replace 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`.

Request
curl https://sendhq.cc/api/v1/connections/id_value/address \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
200 Response
{
  "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"
}