Docs / Marketing and deliverability

Automations

An automation sends emails and updates contacts on its own when something happens: a contact joins a list, confirms a signup form, changes an attribute, does something in your app (a custom event), reaches a date, engages with a campaign or converts. Each contact goes through the automation's steps one at a time: emails, waits, branches, attribute and list changes, webhooks and splits.

In the dashboard, open Automations (under Marketing). The API is under /v1/automations and /v1/events; the full schemas are in the API reference at /docs (tags Automations and Events). Writes need an API key with Full access (full) and the member role or higher; POST /v1/events/track also accepts a Sending only key.

The examples assume:

export ONESEND_BASE_URL=http://localhost:3000
export ONESEND_API_KEY=os_live_…

How an automation runs

An automation has a trigger, a list of steps, settings and optional goals. It is a draft until you activate it.

curl -X POST "$ONESEND_BASE_URL/v1/automations" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series",
    "trigger": { "type": "list_added", "listId": "lst_…" },
    "steps": [
      { "id": "welcome", "type": "send_email", "fromName": "Acme", "fromEmail": "hello@news.acme.dev",
        "subject": "Welcome, {{first_name}}", "templateId": "tpl_…" },
      { "id": "wait", "type": "wait", "duration": { "amount": 2, "unit": "days" }, "until": { "time": "10:00" } },
      { "id": "opened", "type": "condition", "match": "all",
        "conditions": [{ "kind": "email", "op": "opened", "stepId": "welcome" }],
        "yes": [{ "type": "send_email", "fromEmail": "hello@news.acme.dev", "subject": "Getting started", "templateId": "tpl_…" }],
        "no":  [{ "type": "send_email", "fromEmail": "hello@news.acme.dev", "subject": "In case you missed it", "templateId": "tpl_…" }] }
    ]
  }'

curl -X POST "$ONESEND_BASE_URL/v1/automations/aut_…/activate" -H "Authorization: Bearer $ONESEND_API_KEY"

When the trigger fires for a contact, the contact enters the automation and a run starts. A run goes through the steps in order. Branching steps (condition, wait for an event, split) hold their paths as nested step lists; after a path ends, the run continues with the step after the branching step. A run ends when it passes the last step (completed) or leaves early (exited: a goal, an exit step, an exit condition, an unsubscribe).

Run statusMeaning
activeDue to run its next step
waitingAt a wait, waiting for an event, or held by quiet hours or the frequency cap (waitingFor)
completedWent through every step
exitedLeft early; exitReason says why
failedCould not continue (for example its version was deleted)
canceledThe automation was stopped or deleted

Activation checks the whole definition and lists every problem, with the step it belongs to: POST /v1/automations/{id}/activate answers 400 automation_invalid with details.problems (stepId, field, message). POST /v1/automations/{id}/validate returns the same list without activating.

ActionEffect
POST /automations/{id}/activatePublishes the definition as a version (when it changed) and accepts entries. Resumes a paused automation.
POST /automations/{id}/pauseNo new entries; runs stay where they are until you activate again.
POST /automations/{id}/stopNo new entries; every run in progress is canceled. You can activate it again later.
DELETE /automations/{id}Pause or stop it first. Runs and step history are deleted; emails it sent stay in the email logs.

Triggers

typeFieldsStarts when
list_addedlistIdA contact is added to the list: through the API, the dashboard, a CSV import, a signup form or another automation. Being added again while already a member does not count.
form_confirmedformId (optional)A double opt-in subscription is confirmed, or a single opt-in form signup is accepted. Any form when formId is not set.
attribute_changedkey, value (optional)An existing contact's attribute changes (to value, when set), through the API, the dashboard or a form. New contacts and CSV imports do not count. first_name, last_name and phone work too.
eventname, filters (optional)Your app sends the event with POST /v1/events/track and its properties match the filters.
dateattribute, offsetDays, repeat, timeOnce a day at time (default 09:00) in the workspace time zone, for contacts whose date attribute matches today plus offsetDays. repeat: "yearly" (default) matches the month and day every year (birthdays; 29 February counts as 28 February in other years); "once" matches the date itself (renewals, trial ends).
campaign_engagementcampaignId, action (opened or clicked)A contact opens or clicks the campaign.
conversiongoal (optional)A conversion is recorded for the contact (POST /v1/conversions or the browser script), with this goal when set.
manualOnly when you enroll contacts from the dashboard or with POST /v1/automations/{id}/enroll. Every automation also accepts manual enrollment.

Every trigger accepts conditions: only contacts who match all of them enter (see Conditions). For example, a welcome series only for the pro plan:

{ "type": "list_added", "listId": "lst_…", "conditions": [{ "kind": "attribute", "key": "plan", "op": "eq", "value": "pro" }] }

Unsubscribed, bounced and complained contacts do not enter (unless exitOnUnsubscribe is false).

Steps

Every step has an id (generated when you leave it out; keep it stable, reports and email conditions refer to it) and an optional name.

typeFieldsWhat it does
send_emailfromEmail, fromName, subject, previewText, templateId or html, replyTo, variables, tracking, quietHoursEmails the contact (see below).
waitduration (amount, unit: minutes, hours, days, weeks), until (time HH:MM, weekdays 1 = Monday … 7 = Sunday)Waits the duration, then until the next allowed time and day in the workspace time zone. For example "2 days, then at 10:00 on a weekday".
wait_until_eventevent, filters, timeout, matched, timedOutContinues on matched as soon as the event arrives (after the run reached this step), or on timedOut when the timeout passes.
conditionmatch (all or any), conditions, yes, noTakes yes or no.
ab_splitbranches: 2 to 4 of { key, label, percent, steps }, percentages adding up to 100Sends each contact down one path. The same run always takes the same path.
update_attributekey, valueSets the attribute (null removes it). Text can use {{variables}}.
add_to_list, remove_from_listlistIdChanges list membership. Adding can start other automations with a list trigger.
webhookurl, payloadPOSTs signed JSON to your server (see below).
exitEnds the run (exit reason exit_step).

Email steps

Automation emails are marketing email (type: broadcast): they only route to provider connections with Use for campaigns on, they carry List-Unsubscribe headers, and they follow your routing policy, quotas and failover. Include {{unsubscribe_url}} in the content.

  • Who gets it. The step is skipped (outcome skipped, with a reason) for contacts that are pending, unsubscribed, bounced or complained, on the suppression list, marked inactive by sunsetting (unless includeInactive), or with an address quality problem that campaigns skip (unless includeQualityIssues). The run continues with the next step.
  • Variables. Contact fields and attributes ({{first_name}}, {{contact.plan}}), the trigger event's properties ({{event.cart_url}}), the trigger ({{trigger.listId}}) and the system variables. variables adds your own, and their values can use the same variables: { "coupon": "WELCOME-{{first_name}}" }.
  • Quiet hours and frequency cap. When the automation has quiet hours, the email waits until they end (unless the step sets quietHours: false). When the contact already got the frequency cap's number of automation emails, the email waits until it is allowed.
  • Test mode. With settings.testMode, emails are logged with status sandboxed and not delivered.
  • No duplicates. Each email uses the idempotency key aut_<run id>_<step id>, so a step that runs again after a crash or a retry never emails the contact twice.

Delivery, opens, clicks, bounces, unsubscribes and conversions of automation emails are tracked per step, like campaign recipients. Messages carry the tag automation and automation:<id>, and the metadata automationId, automationRunId and automationStepId.

Webhook steps

The request body is:

{
  "id": "arun_….stp_…",
  "type": "automation.webhook",
  "createdAt": "2026-11-08T10:00:00.000Z",
  "data": {
    "automationId": "aut_…", "automationName": "Abandoned cart", "runId": "arun_…", "stepId": "stp_…", "test": false,
    "contact": { "id": "ctc_…", "email": "ada@example.com", "firstName": "Ada", "lastName": null, "attributes": { "plan": "pro" } },
    "event": { "id": "evt_…", "name": "cart_abandoned", "properties": { "cart_url": "https://shop.example/c/1" } },
    "trigger": { "type": "event", "name": "cart_abandoned" },
    "payload": { "your": "data" }
  }
}

It is signed like outgoing webhooks: x-onesend-signature: v1=<HMAC-SHA256 of "<x-onesend-timestamp>.<body>"> with the automation's signing secret (GET /v1/automations/{id}/signing-secret, POST /v1/automations/{id}/rotate-secret). Text values in payload can use {{variables}}; a value that is only one variable ("{{event.total}}") keeps its type. URLs that point at private or reserved addresses are refused, on save and on every request.

A request that fails (network error or a non-2xx answer) is tried again after 1 and 5 minutes. After the third failure the step's outcome is failed and the run continues. Because a step can run again, your endpoint can receive a request more than once: use x-onesend-delivery (the same for every attempt) to ignore repeats.

Adding a webhook step needs a signed-in admin or an Admin key. When the API key that created the automation or added a webhook step is revoked or reported as leaked, OneSend turns its webhook steps off (webhookDisabledReason: key_revoked or key_leaked): they are skipped (outcome skipped) and the rest of the automation runs. An admin saving the steps again (PATCH with steps) turns them back on, and the owners get a security alert listing the URLs.

Conditions

Condition steps, trigger conditions, exit conditions and segment goals use the segment conditions (attribute, list, status, engagement) and these:

kindOperatorsExample
emailopened, not_opened, clicked, not_clicked, with optional stepId (an earlier send step; any email of this run when omitted){ "kind": "email", "op": "clicked", "stepId": "welcome" }
eventperformed, not_performed, with optional withinDays, sinceEntry and filters{ "kind": "event", "name": "order_completed", "op": "not_performed", "sinceEntry": true }
event_propertyeq, neq, contains, not_contains, gt, lt, is_set, is_not_set on a property of the trigger event (or the event a wait-for-event step matched){ "kind": "event_property", "key": "total", "op": "gt", "value": 100 }
conversionconverted, not_converted, with optional goal; since the contact entered unless sinceEntry: false{ "kind": "conversion", "op": "converted", "goal": "purchase" }

Filters on event properties (filters on event triggers, wait-for-event steps, event conditions and goals) have key (a.b reads nested values), op and value, compared like attributes: numbers numerically, text without regard to case.

Goals and exits

A goal is what the automation is for. When a contact reaches it, the run ends with exit reason goal, unless the goal has exit: false (then it is only recorded). The report counts goals reached.

kindFieldsReached when
conversiongoal (optional)A conversion is recorded for the contact
eventname, filtersThe event is tracked for the contact
segmentmatch, conditionsThe contact matches, checked before each step
"goals": [{ "kind": "event", "name": "order_completed" }]

Runs also end when the contact unsubscribes, bounces or complains (exitOnUnsubscribe, on by default), when one of settings.exitConditions matches (checked before each step), at an exit step, or when you remove a contact with POST /v1/automations/{id}/runs/{runId}/exit.

Settings

SettingDefaultMeaning
reentry.modenevernever: a contact goes through once. after: again reentry.days after their last entry. always: whenever they have no run in progress.
maxActiveRunsnoneMost runs in progress at once; further entries are skipped.
frequencyCapnone{ "emails": 1, "hours": 24 }: at most this many automation emails per contact, counted across every automation. Emails over the cap wait.
quietHoursnone{ "start": "21:00", "end": "08:00" } in the workspace time zone. Emails wait until the end.
testModefalseEmails are logged as sandboxed and not delivered.
exitOnUnsubscribetrueLeave when the contact unsubscribes, bounces or complains.
exitConditionsnoneLeave as soon as any of these conditions match.
includeInactivefalseEmail contacts marked inactive by sunsetting.
includeQualityIssuesfalseEmail addresses with quality problems that campaigns skip.
migrateRunssafeSee Versions.

Entries are idempotent: each run has an entry key (the event id, the list membership, the day of a date trigger, the manual enrollment), unique per automation and contact, so a trigger that is processed twice enrolls once.

Versions

A draft is edited in place. Activating publishes version 1. After that, changing the trigger, steps, settings or goals of an active or paused automation (PATCH /v1/automations/{id}, or Publish changes in the dashboard) publishes the next version at once, after the same checks as activation. Renaming does not create a version.

  • New entries use the latest version.
  • Runs in progress move to the new version when their current step still exists in it with the same type (migrateRuns: "safe", the default). Other runs, and every run with migrateRuns: "none", finish on the version they entered with.

GET /v1/automations/{id}/versions lists the versions with the runs still in progress on each. Keep step ids stable when you edit, so runs can move.

Testing

POST /v1/automations/{id}/test with contactId or email:

  • Dry run (default, dryRun: true): walks the current definition (saved, not necessarily published) for the contact and returns the path, without sending or changing anything. Waits advance a simulated clock, so each step shows when it would run; conditions use the contact's data now; a wait-for-event step takes the timeout path unless a matching event already arrived; each email shows its subject and any empty variables. Pass event (name, properties) to preview with a trigger event. The response also lists problems that would stop activation.
  • Test run (dryRun: false): a real run on the published version, with emails sandboxed. The automation must be active. Test runs ignore re-entry rules and trigger conditions, and are marked test: true.
curl -X POST "$ONESEND_BASE_URL/v1/automations/aut_…/test" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","event":{"name":"cart_abandoned","properties":{"cart_url":"https://shop.example/c/1"}}}'

In the dashboard, Test in the builder runs a dry run and can start a sandboxed run.

Custom events

Send events from your app when contacts do something:

curl -X POST "$ONESEND_BASE_URL/v1/events/track" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","name":"cart_abandoned","properties":{"cart_url":"https://shop.example/c/1","total":49},"idempotencyKey":"cart-1001"}'
  • Identify the contact by email or contactId. Unknown addresses return 404, unless createContact: true (the contact is created as subscribed; only do this when the person agreed to receive email).
  • name: letters, digits, _, ., : and -, up to 100 characters. properties: up to 16 KB of JSON. occurredAt defaults to now.
  • idempotencyKey makes retries safe: the same key records one event (duplicate: true).
  • An event starts automations with a matching event trigger, ends runs whose goal is the event, and continues runs waiting for it. Events sent with a test-mode key are stored but start nothing.

GET /v1/events/tracked lists events (filter by contactId and name). With the SDK: onesend.events.track({ email, name, properties }).

Enrolling contacts

POST /v1/automations/{id}/enroll enrolls up to 1,000 contacts by contactIds or emails right away, or a whole listId or segmentId in the background. The automation must be active. Re-entry rules, trigger conditions and maxActiveRuns apply; the response counts skipped contacts by reason (already_entered, conditions, max_active_runs, unsubscribed).

In the dashboard, open the automation's report and select Enroll contacts.

Reports and journeys

GET /v1/automations/{id}/report returns:

  • runs: entered, in progress, completed, exited and failed, exitReasons, and goalReached.
  • emails: sent, delivered, opened, clicked, converted, revenue, bounced, unsubscribed and complained, with rates (open and click = unique / delivered, conversion = converted / delivered).
  • steps: for each step, the runs at it now (inStep), the runs that finished it (completed), the outcomes (sent/skipped/failed, yes/no, matched/timed_out, split path keys, …) and, for email steps, the same email results. Steps removed in later versions are listed with type removed.

Conversions are credited to an automation email when they carry its click token or message id (see Conversions).

GET /v1/automations/{id}/runs lists runs (filter by status, stepId, contactId); GET /v1/automations/{id}/runs/{runId} adds the step history. GET /v1/contacts/{id}/journeys returns every run of a contact with its steps, and the contact's recent events; the contact page shows it under Automations.

Recipes

GET /v1/automations/recipes lists complete automations to start from; create one with POST /v1/automations and "recipe": "<id>" (fields you send override the recipe). Lists, templates and the sender address are left for you to fill in; activation lists what is missing.

RecipeTriggerSteps
welcome_seriesAdded to a listWelcome email, wait 2 days, branch on opened: tips or a reminder, wait, a third email
double_opt_in_follow_upForm confirmedThank-you email, wait 3 days until 09:00, a first useful email
abandoned_cartEvent cart_abandonedWait up to an hour for order_completed, otherwise a reminder with {{event.cart_url}}, a second reminder a day later; goal order_completed; frequency cap 2 per day
win_backManual (contacts with no opens in 90 days)"We miss you", wait 7 days, clicked: mark winback=recovered, otherwise a last email and winback=no_response
renewal_reminder3 days before renewal_date at 09:00Reminder, wait 2 days, last reminder; goal conversion renewal
post_purchase_reviewConversion purchaseWait 7 days, review request, wait 4 days, reminder for people who did not click; quiet hours 21:00–08:00

Webhook events

EventWhendata
automation.completedA run went through every stepautomationId, automationName, runId, contactId, version
automation.exitedA run left earlythe same, plus reason (goal, exit_step, exit_condition, unsubscribed, …)

Test runs send no webhook events. See Webhooks.

Limits for constrained runtimes

The engine runs as jobs: automation_tick runs due runs in batches (claimed with a lock, so two workers never run the same contact's step at once) and schedules itself again; automation_trigger handles triggers; automation_enroll enrolls lists and segments in pages; automation_date runs date triggers daily. On runtimes with a cap on database queries per invocation (Cloudflare D1 allows 1,000), each job stops before its budget and continues in a new job. Set deps.limits.automations (AutomationLimits in apps/server/src/deps.ts): batchSize (runs per tick, default 100, or 40 with a query budget), pageSize (contacts per enrollment page, default 1,000, or 200 with a query budget), queryBudget with queryCount, and timeBudgetMs (default 20 seconds). Without them, the campaign limits (deps.limits.campaigns) apply, which the Cloudflare edition sets.