Automations

An automation is a sequence of up to twenty emails, each sent a set number of minutes after the one before. You define it once, then enrol people by API, by an event, by adding them to an audience, or by tagging them. Prefer it over scheduling several emails yourself: an enrolment ends on its own when the person unsubscribes, replies, is suppressed, opts out of the automation's topic, or their tags say so, which you would otherwise have to track and cancel by hand. The Automations guide walks through a complete sequence.

Every step is sent as marketing mail, with the unsubscribe footer that brings, so an automation's from must be on a verified marketing sending domain. A new automation is a draft and sends nothing until its status is set to active.

The automation object

Create, list, retrieve, update and Change an automation's status all return this object, with the same fields. The enrolments themselves are a list of their own: List an automation's enrolments.

{
  "id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
  "name": "Onboarding",
  "slug": "onboarding",
  "status": "active",
  "trigger": { "kind": "api", "audience_id": null, "event_name": null, "tag": null },
  "identity_id": "b2d7e4a1-6c3f-4e8a-9b5d-1f0a7c2e8d34",
  "from": "Ana <ana@news.example.com>",
  "reply_to": null,
  "steps": [
    { "delay_minutes": 0, "subject": "Welcome to Example", "html": null, "template_slug": "welcome" },
    { "delay_minutes": 4320, "subject": "Three things to try", "html": "<p>Here are three things to try.</p>", "template_slug": null }
  ],
  "exit_on_reply": true,
  "topic_key": "onboarding",
  "exit_tags": ["customer"],
  "required_tags": [],
  "reenrollment": "after_completion",
  "default_variables": {},
  "created_at": "2026-09-15T12:00:00.000Z",
  "updated_at": "2026-09-15T12:05:00.000Z",
  "enrollments": { "active": 12, "completed": 30, "canceled": 4, "failed": 0 }
}

Triggers

The enrol endpoint accepts any active automation whatever its trigger kind, so a contact_added, event or tag_added automation can also be enrolled into directly.

Reach for tag_added when an audience holds everyone and a tag says who the sequence is for. With one audience of every signup, a contact_added welcome for one product would go to all of them; a tag_added one on that product's tag goes only to the people who use it. A tag carried before the automation became active starts nothing, so turning one on does not mail your existing list.

A key that could not enrol the address itself (one that holds sends for approval, or a recipient allowlist that leaves the address out) still adds the tag, and starts nothing.

Default variables

default_variables gives every enrolment the same template values, and whatever an enrolment passes in variables wins for the same name. They are read when each step is sent, so a corrected value reaches people already enrolled from their next step.

A contact_added or tag_added trigger enrols people with no values of its own, so every placeholder its steps use, in their subjects, their html and their templates, must have a default. Create refuses one that does not with 422 missing_variables and a missing array, rather than accepting a sequence whose every enrolment would fail at that step. api and event automations are not checked, because their values arrive with each enrolment.

Steps

Give each step html, template_slug, or both; when both are set the template's HTML body wins. Placeholders work the same way in every part of a step as they do in a template: values are HTML-escaped in a body and inserted as given in the subject, and every placeholder needs a value. The step's own subject is always the one sent, so a template's subject is not used by an automation. Only the template's HTML body is sent; its text body is not, although its placeholders still need values. Steps are read from the automation each time one comes due, so a template edit reaches people already partway through.

A step that sends nothing does not move the enrolment on. When the address's domain cannot receive mail (no mail server for it), the message is recorded in the email log as rejected and the enrolment ends failed, with last_error naming the step and undeliverable_domain. When the address was suppressed or opted out of the automation's topic in the moment between the exit check and the send, the enrolment is cancelled with cancel_reason suppressed or unsubscribed_from_topic, as the exit would have done.

A step that cannot be built marks that person's enrolment failed, with the reason in last_error, rather than retrying: a template slug that has since been deleted, a placeholder in the subject, body or template that the enrolment has no value for, a topic that has since been deleted, or the automation having been deleted. A send refused because the workspace is suspended, because from no longer has a verified marketing domain, or because the request is invalid also marks it failed.

Any other refused send is retried about every five minutes, and the reason is written to last_error while the enrolment stays active. Two refusals do not clear by waiting and are given about a day: the workspace's plan allowance being reached, and the workspace having no postal address set, which marketing mail requires. Once the step has been attempted 288 times for one of those, the enrolment is marked failed with the reason. Provider throttling, other provider errors and the sending domain's daily warm-up allowance being used up (it resets at 00:00 UTC) are retried without a limit. Each retry after a warm-up or provider refusal records another message in the email log, queued or failed.

Automatic exits

An enrolment ends on its own for five reasons. Suppression, topic opt-out and the tag rules are checked when the person is enrolled and again before every step, so a change made by any path, including a CSV import or the preference centre, stops the next step. An unsubscribe also writes a marketing suppression, so it is caught the same way. A reply is acted on only at the moment it arrives, and an earlier reply does not keep anyone out. Most exits also cancel the enrolment immediately when they happen, so the dashboard shows it ended at once.

Tags are matched on the person's contact in the workspace by email address. Pausing an automation is not an exit: its enrolments stay active and continue when it is activated again (see Change an automation's status). Deleting an automation cancels its active enrolments with manual and then deletes them, so that reason is never visible through the API.

The enrolment object

Returned by List an automation's enrolments and Enrol someone.

List automations

GET /v1/automations · requires broadcasts:read

Returns a cursor-paged list of automation objects, newest first, each with its enrollments counts.

Query parameters

Example

curl https://api.sendraven.ai/v1/automations \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
      "name": "Onboarding",
      "slug": "onboarding",
      "status": "active",
      "trigger": { "kind": "api", "audience_id": null, "event_name": null, "tag": null },
      "identity_id": "b2d7e4a1-6c3f-4e8a-9b5d-1f0a7c2e8d34",
      "from": "Ana <ana@news.example.com>",
      "reply_to": null,
      "steps": [
        { "delay_minutes": 0, "subject": "Welcome to Example", "html": null, "template_slug": "welcome" },
        { "delay_minutes": 4320, "subject": "Three things to try", "html": "<p>Here are three things to try.</p>", "template_slug": null }
      ],
      "exit_on_reply": true,
      "topic_key": "onboarding",
      "exit_tags": ["customer"],
      "required_tags": [],
      "reenrollment": "after_completion",
      "default_variables": {},
  "default_variables": {},
      "created_at": "2026-09-15T12:00:00.000Z",
      "updated_at": "2026-09-15T12:05:00.000Z",
      "enrollments": { "active": 12, "completed": 30, "canceled": 4, "failed": 0 }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create an automation

POST /v1/automations · requires broadcasts:write

Creates an automation as a draft. Nothing is sent and nobody can be enrolled until you change its status to active.

The definition is checked here rather than at the first send, so a mistake is a 422 now instead of a failed enrolment per person later. from must be on a domain that is verified in this workspace as a marketing sending domain, matched exactly on the part after the @ (news.example.com, not example.com), and identity_id must be that domain's id from GET /v1/domains, resolved like every other id in a body: a domain name passed instead is refused with the id it should have been. A topic_key must name an existing topic, a contact_added trigger's audience_id must be an audience in this workspace, a tag_added trigger must name a tag, and every step must have an html body or a template_slug naming an existing template. identity_id, topic_key, trigger.audience_id and each template_slug are trimmed before they are checked and stored.

For an api or event trigger, placeholder values are not checked here, because they arrive with each enrolment: a missing value fails the enrolment when the step comes due. A contact_added or tag_added trigger enrols with none, so default_variables must cover every placeholder (see Default variables).

Body

Tags are normalised as contact tags are: trimmed, lower-cased, runs of whitespace turned into hyphens, and deduplicated, and a tag that is only whitespace is dropped. "Paid Customer" is stored as paid-customer. The 60-character limit applies to each tag as sent: a longer one is refused with 422, not shortened.

Example

curl -X POST https://api.sendraven.ai/v1/automations \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Onboarding",
    "slug": "onboarding",
    "identity_id": "b2d7e4a1-6c3f-4e8a-9b5d-1f0a7c2e8d34",
    "from": "Ana <ana@news.example.com>",
    "trigger": { "kind": "api" },
    "topic_key": "onboarding",
    "exit_tags": ["customer"],
    "steps": [
      { "delay_minutes": 0, "subject": "Welcome to Example", "template_slug": "welcome" },
      { "delay_minutes": 4320, "subject": "Three things to try", "html": "<p>Here are three things to try.</p>" }
    ]
  }'

Response

201 Created

An automation object. Its enrollments counts are all 0.

{
  "id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
  "name": "Onboarding",
  "slug": "onboarding",
  "status": "draft",
  "trigger": { "kind": "api", "audience_id": null, "event_name": null, "tag": null },
  "identity_id": "b2d7e4a1-6c3f-4e8a-9b5d-1f0a7c2e8d34",
  "from": "Ana <ana@news.example.com>",
  "reply_to": null,
  "steps": [
    { "delay_minutes": 0, "subject": "Welcome to Example", "html": null, "template_slug": "welcome" },
    { "delay_minutes": 4320, "subject": "Three things to try", "html": "<p>Here are three things to try.</p>", "template_slug": null }
  ],
  "exit_on_reply": true,
  "topic_key": "onboarding",
  "exit_tags": ["customer"],
  "required_tags": [],
  "reenrollment": "after_completion",
  "default_variables": {},
  "created_at": "2026-09-15T12:00:00.000Z",
  "updated_at": null,
  "enrollments": { "active": 0, "completed": 0, "canceled": 0, "failed": 0 }
}

Errors

Retrieve an automation

GET /v1/automations/{id} · requires broadcasts:read

Returns the automation object with its enrollments counts, the same object the list holds for it. To see who is enrolled, use List an automation's enrolments.

Path parameters

Example

curl https://api.sendraven.ai/v1/automations/3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90 \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
  "name": "Onboarding",
  "slug": "onboarding",
  "status": "active",
  "trigger": { "kind": "api", "audience_id": null, "event_name": null, "tag": null },
  "identity_id": "b2d7e4a1-6c3f-4e8a-9b5d-1f0a7c2e8d34",
  "from": "Ana <ana@news.example.com>",
  "reply_to": null,
  "steps": [
    { "delay_minutes": 0, "subject": "Welcome to Example", "html": null, "template_slug": "welcome" },
    { "delay_minutes": 4320, "subject": "Three things to try", "html": "<p>Here are three things to try.</p>", "template_slug": null }
  ],
  "exit_on_reply": true,
  "topic_key": "onboarding",
  "exit_tags": ["customer"],
  "required_tags": [],
  "reenrollment": "after_completion",
  "default_variables": {},
  "created_at": "2026-09-15T12:00:00.000Z",
  "updated_at": "2026-09-15T12:05:00.000Z",
  "enrollments": { "active": 1, "completed": 0, "canceled": 1, "failed": 0 }
}

Errors

Update an automation

PATCH /v1/automations/{id} · requires broadcasts:write

Changes the rules that take someone out of the sequence, topic_key, exit_tags, required_tags and exit_on_reply, reply_to, which belongs with them because it decides whether a reply can end the sequence, reenrollment, which decides who can come back in, and default_variables, which fill the steps. The name, slug, sender, trigger and steps cannot be changed once created; any other field in the body is refused with 422 rather than ignored, so a caller that sends steps learns it did not apply.

Fields left out keep their value. null clears topic_key or reply_to, and an empty array clears a tag list. Tags are normalised as on create. A topic_key is checked only when it differs from the current one.

People already enrolled are judged by the new topic_key, exit_tags and required_tags before their next step, not all at once, so a rule changed by mistake can be put back before anyone's next step comes due. A new exit_on_reply applies to the next reply that arrives, a new reply_to to each person's next step, a new default_variables to each person's next step, and a new reenrollment to the next enrolment: nobody already enrolled is affected, and switching to never also keeps out everyone whose enrolment ended before the change. Every call sets updated_at, even one with an empty body.

Path parameters

Body

Example

curl -X PATCH https://api.sendraven.ai/v1/automations/3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90 \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exit_tags": ["customer", "churned"], "reply_to": null }'

Response

200 OK

The updated automation object.

{
  "id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
  "name": "Onboarding",
  "slug": "onboarding",
  "status": "active",
  "trigger": { "kind": "api", "audience_id": null, "event_name": null, "tag": null },
  "identity_id": "b2d7e4a1-6c3f-4e8a-9b5d-1f0a7c2e8d34",
  "from": "Ana <ana@news.example.com>",
  "reply_to": null,
  "steps": [
    { "delay_minutes": 0, "subject": "Welcome to Example", "html": null, "template_slug": "welcome" },
    { "delay_minutes": 4320, "subject": "Three things to try", "html": "<p>Here are three things to try.</p>", "template_slug": null }
  ],
  "exit_on_reply": true,
  "topic_key": "onboarding",
  "exit_tags": ["customer", "churned"],
  "required_tags": [],
  "reenrollment": "after_completion",
  "default_variables": {},
  "created_at": "2026-09-15T12:00:00.000Z",
  "updated_at": "2026-09-16T08:00:00.000Z",
  "enrollments": { "active": 12, "completed": 30, "canceled": 4, "failed": 0 }
}

Errors

Delete an automation

DELETE /v1/automations/{id} · requires broadcasts:write

Cancels every active enrolment, then deletes the automation together with all of its enrolments, including completed, cancelled and failed ones. Messages already sent are unaffected and stay in the email log.

Path parameters

Example

curl -X DELETE https://api.sendraven.ai/v1/automations/3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90 \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

enrollments_canceled is the number of enrolments that were still active.

{
  "id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
  "deleted": true,
  "enrollments_canceled": 12
}

Errors

List an automation's enrolments

GET /v1/automations/{id}/enrollments · requires broadcasts:read

Everyone enrolled in the automation, newest enrolment first (by enrolled_at, then id), as enrolment objects. Cursor-paged like every other list (pagination): pass next_cursor back as cursor while has_more is true. Ended enrolments stay listed with their status, so status=canceled and each row's cancel_reason answer who left the sequence and why.

Path parameters

Query parameters

Example

curl "https://api.sendraven.ai/v1/automations/3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90/enrollments?limit=2" \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "8a1d4f6b-2c9e-4b7a-a3d5-6e0f1b8c2d47",
      "automation_id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
      "email": "ana@example.com",
      "current_step": 1,
      "status": "active",
      "next_due_at": "2026-09-18T12:10:00.000Z",
      "variables": { "name": "Ana" },
      "enrolled_at": "2026-09-15T12:10:00.000Z",
      "completed_at": null,
      "canceled_at": null,
      "cancel_reason": null,
      "last_error": null,
      "attempts": 0
    },
    {
      "id": "c5e2b7a9-4d1f-4a6c-8e3b-9f2d0a7c1e58",
      "automation_id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
      "email": "sam@example.com",
      "current_step": 1,
      "status": "canceled",
      "next_due_at": "2026-09-18T12:06:00.000Z",
      "variables": {},
      "enrolled_at": "2026-09-15T12:06:00.000Z",
      "completed_at": null,
      "canceled_at": "2026-09-16T09:30:00.000Z",
      "cancel_reason": "replied",
      "last_error": null,
      "attempts": 0
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Enrol someone in an automation

POST /v1/automations/{id}/enroll · requires emails:send

Puts one address into the sequence. The first step is due delay_minutes after enrolment. The address does not need a contact record, although without one it has no tags, so an automation with required_tags will not take it.

The outcome is in the status code and body rather than always an error. Every outcome answers enrolled, reason and enrollment: reason is null when the person was enrolled, and enrollment is null when they were not.

• 201 with enrolled: true and the new enrollment: the person is enrolled.
• 200 with enrolled: false and reason: "already_enrolled": they already have an active enrolment in this automation. Retrying a call is therefore safe, whatever reenrollment says. Once an enrolment has completed, been cancelled or failed, enrolling the same address again starts the sequence from the first step, unless reenrollment is never.
• 200 with enrolled: false and reason: "previously_enrolled": the automation's reenrollment is never and this address has been through it before (its enrolment completed, was cancelled or failed). Addresses are compared lower-cased.
• 200 with enrolled: false and a reason of suppressed, unsubscribed_from_topic, exit_tag or required_tag_missing: the person is deliberately excluded by one of the automatic exits. This is a correct outcome; do not work around it.
• 409 with enrolled: false and a reason of not_active, no_steps or topic_missing: the automation cannot take anyone until its definition is fixed. It is not active, has no steps, or its topic_key names a topic that has since been deleted. The body carries enrolled, reason and enrollment alongside the usual error object, whose type is invalid_state.

The checks run in this order: not_active, no_steps, suppressed, topic_missing, unsubscribed_from_topic, then the tag rules, then previously_enrolled (only when the address has no active enrolment), and already_enrolled last. So a paused automation answers 409 even for a suppressed address, a suppressed address answers 200 suppressed even when the topic is missing, and an exclusion is reported in place of already_enrolled.

The calling key's guardrails decide whether it may enrol at all. A key that holds its sends for approval cannot enrol anyone (403 forbidden): the steps are sent later with no approval step, so enrolling would be a way round the hold. A key with a recipient allowlist can enrol only addresses on it (403 recipient_not_allowed). A key's daily limit is not checked, and the steps an enrolment sends later do not count against it.

Path parameters

Body

Example

curl -X POST https://api.sendraven.ai/v1/automations/3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90/enroll \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "email": "ana@example.com", "variables": { "name": "Ana", "plan": "Pro" } }'

Response

201 Created

{
  "enrolled": true,
  "reason": null,
  "enrollment": {
    "id": "8a1d4f6b-2c9e-4b7a-a3d5-6e0f1b8c2d47",
    "automation_id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
    "email": "ana@example.com",
    "current_step": 0,
    "status": "active",
    "next_due_at": "2026-09-15T12:00:00.000Z",
    "variables": { "name": "Ana", "plan": "Pro" },
    "enrolled_at": "2026-09-15T12:00:00.000Z",
    "completed_at": null,
    "canceled_at": null,
    "cancel_reason": null,
    "last_error": null,
    "attempts": 0
  }
}

200 OK, not enrolled:

{ "enrolled": false, "reason": "already_enrolled", "enrollment": null }

Errors

Change an automation's status

POST /v1/automations/{id}/status · requires broadcasts:write

Sets the status to draft, active or paused. Any status can be set from any other.

active lets the automation enrol people and send steps. Setting anything else pauses it: triggers no longer start enrolments, enrol calls answer 409 invalid_state with reason not_active, and no step is sent. Enrolments in flight are held, not ended: they stay active on their current step, and a step that comes due while the automation is paused waits. Made active again, the automation continues each person from their current step, and steps that came due in the meantime go out from the next run of the worker (every 30 seconds), oldest first, at the usual pace rather than all at once. Every exit still applies while an automation is paused: an unsubscribe, a reply, a topic opt-out or a tag change ends an enrolment at once as usual, and a suppression is caught when the held step would have been sent.

A step's content is read when it is sent, so pausing to correct a step and activating again sends the corrected step to everyone who had not received it yet.

Activating does not re-check the sending domain. If it is no longer verified, each enrolment fails at its next step with the reason in last_error.

Path parameters

Body

Example

curl -X POST https://api.sendraven.ai/v1/automations/3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90/status \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Response

200 OK

The automation object after the change, with its enrollments counts: the same object Retrieve an automation returns.

{
  "id": "3f6c2a8e-5b7d-4c1e-9a2f-8d4b6e1c7a90",
  "name": "Onboarding",
  "slug": "onboarding",
  "status": "active",
  "trigger": { "kind": "api", "audience_id": null, "event_name": null, "tag": null },
  "identity_id": "b2d7e4a1-6c3f-4e8a-9b5d-1f0a7c2e8d34",
  "from": "Ana <ana@news.example.com>",
  "reply_to": null,
  "steps": [
    { "delay_minutes": 0, "subject": "Welcome to Example", "html": null, "template_slug": "welcome" },
    { "delay_minutes": 4320, "subject": "Three things to try", "html": "<p>Here are three things to try.</p>", "template_slug": null }
  ],
  "exit_on_reply": true,
  "topic_key": "onboarding",
  "exit_tags": ["customer"],
  "required_tags": [],
  "reenrollment": "after_completion",
  "default_variables": {},
  "created_at": "2026-09-15T12:00:00.000Z",
  "updated_at": "2026-09-15T12:20:00.000Z",
  "enrollments": { "active": 1, "completed": 0, "canceled": 1, "failed": 0 }
}

Errors