---
title: "Automations"
description: "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,…"
url: https://onesend.email/docs/automations/
---
# 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:

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

- [How an automation runs](#how-an-automation-runs)
- [Triggers](#triggers)
- [Steps](#steps)
- [Conditions](#conditions)
- [Goals and exits](#goals-and-exits)
- [Settings](#settings)
- [Versions](#versions)
- [Testing](#testing)
- [Custom events](#custom-events)
- [Enrolling contacts](#enrolling-contacts)
- [Reports and journeys](#reports-and-journeys)
- [Recipes](#recipes)
- [Webhook events](#webhook-events)
- [Limits for constrained runtimes](#limits-for-constrained-runtimes)

## 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.

```bash
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 status | Meaning |
|---|---|
| `active` | Due to run its next step |
| `waiting` | At a wait, waiting for an event, or held by quiet hours or the frequency cap (`waitingFor`) |
| `completed` | Went through every step |
| `exited` | Left early; `exitReason` says why |
| `failed` | Could not continue (for example its version was deleted) |
| `canceled` | The 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.

| Action | Effect |
|---|---|
| `POST /automations/{id}/activate` | Publishes the definition as a version (when it changed) and accepts entries. Resumes a paused automation. |
| `POST /automations/{id}/pause` | No new entries; runs stay where they are until you activate again. |
| `POST /automations/{id}/stop` | No 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

| `type` | Fields | Starts when |
|---|---|---|
| `list_added` | `listId` | A 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_confirmed` | `formId` (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_changed` | `key`, `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. |
| `event` | `name`, `filters` (optional) | Your app sends the event with `POST /v1/events/track` and its properties match the filters. |
| `date` | `attribute`, `offsetDays`, `repeat`, `time` | Once 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_engagement` | `campaignId`, `action` (`opened` or `clicked`) | A contact opens or clicks the campaign. |
| `conversion` | `goal` (optional) | A conversion is recorded for the contact (`POST /v1/conversions` or the browser script), with this goal when set. |
| `manual` | | Only 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](#conditions)). For example, a welcome series only for the `pro` plan:

```json
{ "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`.

| `type` | Fields | What it does |
|---|---|---|
| `send_email` | `fromEmail`, `fromName`, `subject`, `previewText`, `templateId` or `html`, `replyTo`, `variables`, `tracking`, `quietHours` | Emails the contact (see below). |
| `wait` | `duration` (`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_event` | `event`, `filters`, `timeout`, `matched`, `timedOut` | Continues on `matched` as soon as the event arrives (after the run reached this step), or on `timedOut` when the timeout passes. |
| `condition` | `match` (`all` or `any`), `conditions`, `yes`, `no` | Takes `yes` or `no`. |
| `ab_split` | `branches`: 2 to 4 of `{ key, label, percent, steps }`, percentages adding up to 100 | Sends each contact down one path. The same run always takes the same path. |
| `update_attribute` | `key`, `value` | Sets the attribute (`null` removes it). Text can use `{{variables}}`. |
| `add_to_list`, `remove_from_list` | `listId` | Changes list membership. Adding can start other automations with a list trigger. |
| `webhook` | `url`, `payload` | POSTs signed JSON to your server (see below). |
| `exit` | | Ends 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](https://onesend.email/docs/deliverability/#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:

```json
{
  "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](https://onesend.email/docs/webhooks/#verifying-signatures): `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](https://onesend.email/docs/marketing/#lists-and-segments) (`attribute`, `list`, `status`, `engagement`) and these:

| `kind` | Operators | Example |
|---|---|---|
| `email` | `opened`, `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" }` |
| `event` | `performed`, `not_performed`, with optional `withinDays`, `sinceEntry` and `filters` | `{ "kind": "event", "name": "order_completed", "op": "not_performed", "sinceEntry": true }` |
| `event_property` | `eq`, `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 }` |
| `conversion` | `converted`, `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.

| `kind` | Fields | Reached when |
|---|---|---|
| `conversion` | `goal` (optional) | A conversion is recorded for the contact |
| `event` | `name`, `filters` | The event is tracked for the contact |
| `segment` | `match`, `conditions` | The contact matches, checked before each step |

```json
"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

| Setting | Default | Meaning |
|---|---|---|
| `reentry.mode` | `never` | `never`: a contact goes through once. `after`: again `reentry.days` after their last entry. `always`: whenever they have no run in progress. |
| `maxActiveRuns` | none | Most runs in progress at once; further entries are skipped. |
| `frequencyCap` | none | `{ "emails": 1, "hours": 24 }`: at most this many automation emails per contact, counted across every automation. Emails over the cap wait. |
| `quietHours` | none | `{ "start": "21:00", "end": "08:00" }` in the workspace time zone. Emails wait until the end. |
| `testMode` | `false` | Emails are logged as `sandboxed` and not delivered. |
| `exitOnUnsubscribe` | `true` | Leave when the contact unsubscribes, bounces or complains. |
| `exitConditions` | none | Leave as soon as any of these conditions match. |
| `includeInactive` | `false` | Email contacts marked inactive by sunsetting. |
| `includeQualityIssues` | `false` | Email addresses with quality problems that campaigns skip. |
| `migrateRuns` | `safe` | See [Versions](#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`.

```bash
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:

```bash
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](https://onesend.email/docs/marketing/#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.

| Recipe | Trigger | Steps |
|---|---|---|
| `welcome_series` | Added to a list | Welcome email, wait 2 days, branch on opened: tips or a reminder, wait, a third email |
| `double_opt_in_follow_up` | Form confirmed | Thank-you email, wait 3 days until 09:00, a first useful email |
| `abandoned_cart` | Event `cart_abandoned` | Wait 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_back` | Manual (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_reminder` | 3 days before `renewal_date` at 09:00 | Reminder, wait 2 days, last reminder; goal conversion `renewal` |
| `post_purchase_review` | Conversion `purchase` | Wait 7 days, review request, wait 4 days, reminder for people who did not click; quiet hours 21:00–08:00 |

## Webhook events

| Event | When | `data` |
|---|---|---|
| `automation.completed` | A run went through every step | `automationId`, `automationName`, `runId`, `contactId`, `version` |
| `automation.exited` | A run left early | the same, plus `reason` (`goal`, `exit_step`, `exit_condition`, `unsubscribed`, …) |

Test runs send no webhook events. See [Webhooks](https://onesend.email/docs/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.
