> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maildiver.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How Automation Workflows Work

> Learn how to use automation workflows to send triggered emails

Automation workflows are typically used for:

* Welcome emails when users sign up
* Onboarding drip campaigns
* Abandoned cart reminders
* Re-engagement campaigns
* Post-purchase follow-ups
* Event-triggered notifications

## How automation workflows work

Automation workflows are event-driven. When you send an event via API, MailDiver checks if there are any active workflows configured for that event and creates an execution.

```mermaid theme={null}
graph LR
    A[Event Sent] --> B[Workflow Triggered]
    B --> C[Execution Created]
    C --> D[Steps Executed]
    D --> E[Email Sent]

    style A fill:#16A34A,stroke:#15803D,stroke-width:2px,color:#fff
    style B fill:#16A34A,stroke:#15803D,stroke-width:2px,color:#fff
    style C fill:#16A34A,stroke:#15803D,stroke-width:2px,color:#fff
    style D fill:#16A34A,stroke:#15803D,stroke-width:2px,color:#fff
    style E fill:#16A34A,stroke:#15803D,stroke-width:2px,color:#fff
```

1. Your application sends an event (e.g., `user_signed_up`) via the API
2. MailDiver finds all active workflows configured for that event
3. An execution is created for each workflow
4. The workflow steps are executed in order (send email, wait, conditional logic, etc.)
5. Emails are sent to the contact with personalized data

<Note>
  Multiple workflows can be triggered by the same event. Each workflow creates a
  separate execution.
</Note>

## Step-by-step guide

### Step 1. Create a workflow in the dashboard

Workflows can only be created in the [MailDiver dashboard](https://app.maildiver.com/automations/workflows). You cannot create workflows via API - this is intentional to ensure workflows are properly designed and tested.

In the workflow builder, you can:

* Configure the trigger event (e.g., `user_signed_up`, `purchase_completed`)
* Add steps: Send Email, Wait, Conditional Split
* Use contact properties for personalization and conditions

### Step 2. Send an event via API to trigger the workflow

Once your workflow is active, send events from your application to trigger it:

```javascript theme={null}
const response = await fetch('https://api.maildiver.com/v1/events', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_name: 'user_signed_up',
    email: 'user@example.com',
    properties: {
      first_name: 'John',
      plan: 'pro',
      signup_date: '2024-01-15',
    },
  }),
});
```

<Note>
  The `properties` object contains contact metadata that can be used in your
  email templates and workflow conditions. These properties are merged with
  existing contact data. You can also update contact properties directly via the
  [Update Contact
  API](/api-reference/automation-contact/update-automation-contact) without
  triggering workflows.
</Note>

### Step 3. Monitor executions and emails

After sending events, you can monitor workflow executions in the [MailDiver dashboard](https://app.maildiver.com/automations/workflows):

* View all executions for a workflow
* See the current step each execution is on
* Check execution status: IN\_PROGRESS, WAITING, COMPLETED, FAILED, or CANCELLED
* Review sent emails and their delivery status

<Note>
  You don't need to know any API if you use the MailDiver dashboard. Everything
  can be monitored visually. The API is available for programmatic access if
  needed.
</Note>

If you need programmatic access, use the API:

```javascript theme={null}
// List executions for a workflow
GET / v1 / workflows / { workflow_id } / executions;

// Get specific execution details
GET / v1 / executions / { execution_id };

// List emails sent during an execution
GET / v1 / executions / { execution_id } / emails;
```

### Step 4. How unsubscribe works

Include the `{{ unsubscribe_url }}` variable in your email templates:

```html theme={null}
<a
  href="{{ unsubscribe_url }}"
  style="color: #3b82f6; text-decoration: underline;"
>
  Unsubscribe
</a>
```

When a contact clicks the unsubscribe link:

1. They are immediately unsubscribed from that specific workflow
2. **All active executions** for that contact+workflow are automatically cancelled
3. The `cancellation_reason` is set to "User unsubscribed from workflow"
4. Future events will not trigger that workflow for this contact

<Note>
  Unsubscribe is workflow-specific. If a contact unsubscribes from "Welcome
  Email" workflow, they can still receive emails from other workflows like
  "Purchase Confirmation".
</Note>

## Contact properties and personalization

Contact properties are merged using **deep merge with null deletion**:

* **Omitted fields**: Preserved unchanged
* **Fields with values**: Updated or added
* **Fields set to `null`**: Explicitly deleted
* **Nested objects**: Recursively merged (not replaced)
* **Arrays**: Replaced entirely

Example - updating a contact's plan:

```javascript theme={null}
// First event creates contact
{
  event_name: 'user_signed_up',
  email: 'user@example.com',
  properties: {
    first_name: 'John',
    plan: 'free'
  }
}

// Later event updates plan (first_name is preserved)
{
  event_name: 'plan_upgraded',
  email: 'user@example.com',
  properties: {
    plan: 'pro'
  }
}

// Result: { first_name: 'John', plan: 'pro' }
```

You can also update contact properties via the API without triggering workflows:

```javascript theme={null}
PATCH / v1 / automation / contacts / { email };
```

<Note>
  For more details about contact property updates and deep merge behavior, see
  the [API
  Reference](/api-reference/automation-contact/update-automation-contact).
</Note>

## Key concepts

* **Events trigger workflows**: Send events from your application to automatically trigger workflows
* **One contact, multiple executions**: A single contact can have multiple executions (different workflows, or same workflow triggered multiple times)
* **Automatic cancellation**: Executions are automatically cancelled when a user unsubscribes
* **Contact properties persist**: Properties sent with events are stored and can be used across all workflows
* **Dashboard-only workflow creation**: Workflows can only be created in the dashboard for safety and proper design

That's it! You now understand how automation workflows work in MailDiver.