# Automation triggers

> Reference for every automation trigger by context, with their options and filters, what fires them, and the trigger keys to use with the API.

A trigger decides when an automation starts a run. This page lists every trigger available in each [context](/docs/automations/#contexts), what fires it, its options, and the key you use for it in the API.

## How triggers work

- **One trigger per automation in the dashboard.** Select the trigger on the canvas and change it with **Trigger type**. With the API, Contact and Email automations can have several triggers, as long as they all connect to the same first step. Event automations have exactly one.
- **The automation must be running.** Triggers in draft, paused or stopped automations are ignored. Events from before you start an automation don't start runs later.
- **Runs start within seconds.** Emailit picks up new events every few seconds.

### Filters

Contact updated and every email trigger take an optional filter, under **Filter events (optional)**. Each rule compares one field of the event with a value:

- **Operators:** **Equals**, **Not equals**, **Contains**, **Not contains**, **Greater than**, **Less than**, **Is set**, **Is not set**, **In**, **Not in**, **Starts with** and **Ends with**. **Greater than** and **Less than** compare numbers. The rest compare text and are case-sensitive.
- **Match mode:** **All rules match** or **Any rule matches**.

With the API, a filter is `{ "match": "all", "rules": [{ "field": "...", "operator": "equals", "value": "..." }] }` in the trigger's `config.filter`, with `match` set to `all` or `any`. Fields are paths into the event's object, for example `to` or `link.url`.

## Contact triggers

| Trigger | API key | Options | Starts a run when |
| --- | --- | --- | --- |
| **Added to audience** | `contact.added_to_audience` | **Audience**. Leave it empty for any audience. | A contact joins the audience, or is added back after unsubscribing. |
| **Removed from audience** | `contact.removed_from_audience` | **Audience**. Leave it empty for any audience. | A contact's membership in the audience is deleted. |
| **Contact updated** | `contact.updated` | Optional filter | A contact's email, names, custom fields or marketing status change. |
| **Date anniversary** | `contact.date_anniversary` | **Date field** | Once a year, on the month and day stored in a date custom field. |

### Added to audience

Fires when someone is added to an audience from the dashboard (**Add subscriber**, **Add to audience**, **Add contact** with audiences), with the API ([Add a subscriber](/docs/api-reference/audiences/subscribers/add/), or [Create a contact](/docs/api-reference/contacts/create/) with `audiences`), or with the **Add to audience** bulk action. Adding back someone who unsubscribed also fires it.

It doesn't fire for contacts added by a [file import](/docs/contacts/import-export/), a [subscribe URL](/docs/audiences/subscribe-url/) sign-up, or another automation's **Add to audience** or **Create contact** step, and turning **Subscribed** back on for an existing subscriber doesn't count either.

### Removed from audience

Fires when a subscriber is deleted: **Delete** on the audience page, **Remove from audience**, [Delete a subscriber](/docs/api-reference/audiences/subscribers/delete/), or a contact update whose `audiences` list leaves the audience out. Deleting a contact fires it once for each audience the contact was on. Unsubscribing doesn't fire it, because the person stays on the audience.

### Contact updated

Fires whenever a contact is updated in the dashboard or with the API, including the **Unsubscribe** and **Resubscribe** bulk actions. The filter can check the current **Email**, **First name**, **Last name**, **Unsubscribed** and custom fields, and their previous values, listed as **Previous email**, **Previous first name** and so on. Previous values are only present for the fields that changed.

For example, to react when a contact moves to the `pro` plan, add two rules with **All rules match**: `custom_fields.plan` **Equals** `pro`, and **Previous plan** (`previous.custom_fields.plan`) **Not equals** `pro`.

### Date anniversary

Pick a **Date field**, a [custom field](/docs/contacts/custom-fields/) of type Date such as a birthday. Once a day, Emailit starts a run for every contact whose date has today's month and day, in UTC. The year doesn't matter, so a contact with `1990-04-12` gets a run every April 12. Each automation handles up to 10,000 contacts per day.

> **Set the date field with the API:** In the current beta, the daily check reads the trigger's `date_field` setting, which the dashboard's **Date field** picker doesn't set yet. If your anniversary automation doesn't start runs, set it with [Update an automation](/docs/api-reference/automations/update/): give the trigger `"config": { "date_field": "birthday" }`, using the custom field's key without a prefix.

### API-only contact triggers

| API key | Starts a run when |
| --- | --- |
| `contact.loaded_email` | A contact loads a tracked email sent to their address. |
| `contact.clicked_in_email` | A contact clicks a tracked link in an email sent to their address. |
| `contact.on_date` | A contact's date field, set in `config.date_field`, equals today's date in UTC. Fires once, not every year. |

The API also accepts `contact.visits_url`, `contact.on_purchase` and `contact.on_event`, but nothing fires them yet.

## Email triggers

Email triggers fire for emails in your workspace: everything you send with the API or SMTP, campaign and automation emails, and inbound email for **Email received**. Each run is about one email.

| Trigger | API key | Starts a run when | Filter fields |
| --- | --- | --- | --- |
| **Email delivered** | `email.delivered` | The recipient's server accepted the email. | From, To, Subject, Status |
| **Email bounced** | `email.bounced` | The email failed permanently. | From, To, Subject, Status |
| **Email failed** | `email.failed` | The email couldn't be sent because of an error. | From, To, Subject, Status |
| **Email suppressed** | `email.suppressed` | The email wasn't sent because the recipient is suppressed. | From, To, Subject, Status |
| **Email complained** | `email.complained` | The recipient reported the email as spam. | From, To, Subject, Status |
| **Email received** | `email.received` | An inbound email arrived. See [Inbound](/docs/inbound/). | From, To, Subject |
| **Email loaded** | `email.loaded` | The recipient loaded a tracked email. | Recipient, Sender, Subject, IP address, User agent |
| **Email clicked** | `email.clicked` | The recipient clicked a tracked link. | Recipient, Sender, Subject, Link URL, IP address, User agent |

The editor also lists **Email accepted**, **Email scheduled**, **Email attempted** and **Email rejected**. Automations with these triggers can't be saved yet, so pick one of the triggers above. With the API you can also use `email.canceled`, which fires when a scheduled or queued email is canceled.

> **Avoid loops:** Emails sent by automations fire email triggers too. An automation that sends an email whenever an email bounces would also run for its own notification if that bounced. Add a filter, for example **To** **Not equals** your alert address, so an automation can't trigger itself.

## Event triggers

Event automations can only be created with the API for now.

| Trigger | API key | Starts a run when |
| --- | --- | --- |
| **Manual trigger** | `system.manual` | You call [Trigger a run](/docs/api-reference/automations/trigger/). |
| Schedule | `system.schedule` | Reserved. Nothing fires it yet, so call the trigger endpoint from your own scheduler, such as a cron job, instead. |

### Manual trigger

Call the trigger endpoint of a running automation, with an optional `payload` object:

```bash
curl https://api.emailit.com/v2/automations/aut_3Mv8Xq2nKp5Lt/trigger \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payload": { "email": "ada@example.com", "plan": "pro" } }'
```

The endpoint returns `{ "message": "Automation trigger dispatched." }`, or `422` if the automation isn't running. Steps can read the payload as `{{payload.email}}`, `{{payload.plan}}` and so on. Emailit adds `automation_id` to the payload.

> **One call reaches every manual automation:** In the current beta, a call to the trigger endpoint starts a run in every running automation of the workspace whose trigger is **Manual trigger**, not only the one in the URL. If you have more than one, make each one check its own ID first with a **Condition** step on `payload.automation_id`.

`system.manual` also works as a trigger in Contact and Email automations created with the API. Include `contact_id` (a `con_` ID) or `email_id` in the payload to run the automation for that contact or email.

## Data available to steps

Step settings, such as the recipient of **Send email** or the values of **Edit contact**, can include placeholders that are filled in for each run:

| Placeholder | Contains |
| --- | --- |
| `{{contact.<field>}}` | The run's contact in Contact automations, for example `{{contact.email}}` or `{{contact.custom_fields.plan}}`. |
| `{{email.<field>}}` | The run's email in Email automations, for example `{{email.rcpt_to}}` or `{{email.subject}}`. |
| `{{payload.}}` | The event that started the run. For webhook-style events, the event's data is under `payload.object`, for example `{{payload.object.to}}`. For manual triggers, it's your `payload`. |
| `{{meta.}}` | Extra data Emailit stores about the run. |

Email templates sent by **Send email** use [Temple](/docs/templates/temple/) with the same data. See [Steps](/docs/automations/steps/#send-email).

## Related

  - [Steps](/docs/automations/steps/): What a run can do once it starts.
  - [Webhook event types](/docs/webhooks/event-types/): The events behind contact and email triggers.

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