# Automations

> Automations run steps such as sending an email, waiting or updating a contact when a trigger fires. Learn contexts, statuses, runs, credits and the API.

An automation is a workflow that starts on its own: when a trigger fires, such as a contact joining an audience or an email bouncing, Emailit starts a run that works through the steps you've connected, such as sending an email, waiting a day or updating the contact. Use automations for welcome emails, onboarding sequences, birthday emails, forwarding and alerts.

> **Automations is in beta:** Automations work in every workspace, but some options are still being finished. Where the dashboard and the API differ, these pages say so.

## How it works

1. **A trigger fires.** Every automation starts with one trigger, for example **Added to audience**. Optional filters narrow it down.
2. **Emailit starts a run** for the contact or email that caused it, and charges 3 credits.
3. **The run works through the steps** connected to the trigger, one after another. **Wait** steps pause the run, and **Condition** steps send it down a **Yes** or **No** branch.
4. **The run ends** when it reaches the last step of its branch, or fails if a step fails.

You build the flow on a canvas in the dashboard, or send it to the API as a list of steps and connections. See [Triggers](/docs/automations/triggers/) and [Steps](/docs/automations/steps/).

## Contexts

Each automation has a context, which decides what a run is about and which triggers and steps are available. You choose it when you create the automation, and it can't be changed later.

| Context | Label | Each run is about | Good for | Triggers |
| --- | --- | --- | --- | --- |
| **Contact** | Easy | One contact | Welcome series, onboarding, re-engagement | Audience membership, contact changes, date anniversaries |
| **Email** | Medium | One email | Reply handlers, auto-forwarders, bounce alerts | Email events, such as delivered, bounced or received |
| **Event** | Advanced | One API call | API-driven flows, custom integrations | A manual trigger you call with the API |

In the dashboard, the **Event** context shows a **Soon** badge and can't be selected yet. You can create Event automations with the API.

## Create an automation

1. **Start.** Go to **Email Marketing → Automations** and select **New automation**.

2. **Choose the context.** Pick **Contact** or **Email**.

3. **Choose a template.** Pick one of the [ready-made recipes](/docs/automations/recipes/) or **Start from scratch** for a blank canvas with just a trigger.

4. **Name it.** Enter a **Name** and an optional **Description**, then select **Create**. The automation opens as a draft.

5. **Build the flow.** On the **Editor** tab, select the trigger and each step to configure them, and add steps with the plus buttons. Select **Save**.

6. **Start it.** Select **Start**. From now on, every matching trigger starts a run.

The list page has tabs for **Contact**, **Email** and **Event** automations and shows each one's **Name**, **Status**, **Last triggered** time and **Created** date.

## Statuses

| Status | Triggers start runs | Editable in the dashboard | How to get there |
| --- | --- | --- | --- |
| **Draft** | No | Yes | Every new automation starts as a draft. |
| **Running** | Yes | No | **Start** a draft or paused automation. |
| **Paused** | No | Yes | **Pause** a running automation. **Start** resumes it. |
| **Stopped** | No | No | Only with the API's [stop](/docs/api-reference/automations/stop/) endpoint, which also cancels every run in progress. |

Pausing stops new runs from starting, but runs already in progress continue, including those waiting in a **Wait** step. **Delete**, in the menu at the top of the automation, removes it in any status.

### Editing rules

The **Editor** tab is only available while the automation is a draft or paused. On a running automation, the tab shows **Pause to edit**.

**Save** checks the whole flow and highlights the steps that need attention, for example a **Send email** step without a template or a wait longer than 30 days. Fix them and save again before you select **Start**: starting doesn't run the checks again.

## Runs

A run is one pass through the automation for one contact, email or API call. Each run has a status:

| Run status | Meaning |
| --- | --- |
| **Running** | The run is working through its steps or waiting. |
| **Completed** | Every step on the run's path finished. |
| **Failed** | A step failed, or the workspace didn't have enough credits when the run started. |
| **Canceled** | The automation was stopped with the API while the run was in progress. |

By default, every trigger starts a new run, even if the same contact or email already has one in progress. The same event never starts two runs of one automation. See [Runs and stats](/docs/automations/runs/) for the run history and debugging.

## Credits

| Action | Credits |
| --- | --- |
| Each run | 3, charged when the run starts |
| Each email sent by a **Send email** step | 1 |
| Each email sent by a **Forward email** step | 1 |

If the workspace doesn't have 3 credits when a trigger fires, the run is created with status **Failed** and the reason `insufficient_credits` in its `meta`. If credits run out in the middle of a run, the **Send email** or **Forward email** step fails. See [Credits](/docs/billing/credits/).

## Use the API

The [Automations API](/docs/api-reference/automations/) manages automations and reads their runs. It needs an API key with **Full Access**.

| Endpoint | Use it to |
| --- | --- |
| [Create](/docs/api-reference/automations/create/), [update](/docs/api-reference/automations/update/), [retrieve](/docs/api-reference/automations/get/), [list](/docs/api-reference/automations/list/) and [delete](/docs/api-reference/automations/delete/) | Manage automations. Steps and connections are sent together. |
| [Start](/docs/api-reference/automations/start/), [pause](/docs/api-reference/automations/pause/) and [stop](/docs/api-reference/automations/stop/) | Change the status. |
| [Trigger a run](/docs/api-reference/automations/trigger/) | Fire a **Manual** trigger, with an optional `payload`. The automation must be running. This is only possible with the API. |
| [List runs](/docs/api-reference/automations/runs/), [retrieve a run](/docs/api-reference/automations/run/), [statistics](/docs/api-reference/automations/stats/) and [step statistics](/docs/api-reference/automations/step-stats/) | Read the run history and per-step results. |

The API also accepts automation `settings` that the dashboard doesn't show yet:

| Setting | Default | Effect |
| --- | --- | --- |
| `allow_reentry` | `true` | Set to `false` to skip new runs for a contact or email that already has a run in progress. |
| `max_concurrent_runs` | `0` (no limit) | Skip new runs while this many runs are in progress. |
| `cooldown_seconds` | `0` | Skip new runs for a contact or email that started a run within this many seconds. |
| `on_step_failure` | `stop` | `stop` fails the run when a step fails. `skip` lets the run continue. |

Skipped runs aren't created and don't use credits.

```bash
curl https://api.emailit.com/v2/automations \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "contact",
    "name": "Welcome email",
    "settings": { "allow_reentry": false },
    "steps": [
      { "key": "trigger-1", "type": "trigger", "trigger": "contact.added_to_audience", "config": { "audience_id": "aud_5hJ2kL8mNp4Qr" } },
      { "key": "send_email-1", "type": "action", "action": "send_email", "config": { "type": "template", "template_id": "welcome" } }
    ],
    "connections": [
      { "from": "trigger-1", "to": "send_email-1", "branch": "default" }
    ]
  }'
```

The automation is created as a draft. Call [Start an automation](/docs/api-reference/automations/start/) to turn it on.

## Next steps

  - [Triggers](/docs/automations/triggers/): Every trigger and its options.
  - [Steps](/docs/automations/steps/): Every step, its settings and how branches work.
  - [Recipes](/docs/automations/recipes/): The six ready-made templates.
  - [Runs and stats](/docs/automations/runs/): Follow runs and debug failures.

---
Source: https://emailit.com/docs/automations/