# Automations

> Automate emails with custom events.

Automations allow you to **create email steps** based on custom events from your application.

You can use automations for use cases like:

- Welcome emails
- Drip campaigns
- Payment recovery
- Abandoned cart
- Trial expiration

Automations support `{{{MAILBLASTR_UNSUBSCRIBE_URL}}}` for compliance with non-transactional product and marketing messaging.

## How it works

To start executing an automation, you need to:

1. **Create Automation** — Outline the sequence of steps to be executed.
2. **Add Trigger** — Define the [event name](https://www.mailblastr.com/docs/automations/trigger) that will trigger the automation.
3. **Define Steps** — Configure the [steps](https://www.mailblastr.com/docs/automations/steps) to be executed.
4. **Send an Event** — Trigger the automation by sending an event from your application.
5. **Monitor Runs** — Track and debug your automation executions using [runs](https://www.mailblastr.com/docs/automations/runs).

## 1. Create an automation

The **Automations** page in the dashboard shows all existing automations. You can search by name and filter by status (**All Statuses**, **Enabled**, or **Disabled**) to quickly find the automation you need. Click **Create automation** to start a new automation.

An automation is either **enabled** or **disabled**. New automations start out disabled; only enabled automations create runs when a matching event is received.

Over the API, you can create an entire automation flow with a single request (`status` is optional and defaults to `disabled`):

- `name` — the name of the automation.
- `domain` — **required**: the sending domain this automation belongs to (one of your domains). Only [events](https://www.mailblastr.com/docs/api/events-send) sent with the same `domain` trigger it.
- `status` — the status of the automation (`enabled` or `disabled`).
- `steps` — the [steps](https://www.mailblastr.com/docs/automations/steps) that compose the automation graph.
- `connections` — the [connections between steps](https://www.mailblastr.com/docs/automations/connections) in the automation graph.

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.automations.create({
  "name": "Welcome series",
  "domain": "yourdomain.com",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": { "event_name": "user.created" }
    },
    {
      "key": "welcome",
      "type": "send_email",
      "config": {
        "template": { "id": "34a080c9-b17d-4187-ad80-5af20266e535" }
      }
    }
  ],
  "connections": [
    { "from": "start", "to": "welcome" }
  ]
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Automations.create({
  "name": "Welcome series",
  "domain": "yourdomain.com",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": {
        "event_name": "user.created"
      }
    },
    {
      "key": "welcome",
      "type": "send_email",
      "config": {
        "template": {
          "id": "34a080c9-b17d-4187-ad80-5af20266e535"
        }
      }
    }
  ],
  "connections": [
    {
      "from": "start",
      "to": "welcome"
    }
  ]
})
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->automations->create([
  'name' => "Welcome series",
  'domain' => "yourdomain.com",
  'steps' => [
    [
      'key' => "start",
      'type' => "trigger",
      'config' => [
        'event_name' => "user.created"
      ]
    ],
    [
      'key' => "welcome",
      'type' => "send_email",
      'config' => [
        'template' => [
          'id' => "34a080c9-b17d-4187-ad80-5af20266e535"
        ]
      ]
    ]
  ],
  'connections' => [
    [
      'from' => "start",
      'to' => "welcome"
    ]
  ]
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Automations.create({
  "name": "Welcome series",
  "domain": "yourdomain.com",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": {
        "event_name": "user.created"
      }
    },
    {
      "key": "welcome",
      "type": "send_email",
      "config": {
        "template": {
          "id": "34a080c9-b17d-4187-ad80-5af20266e535"
        }
      }
    }
  ],
  "connections": [
    {
      "from": "start",
      "to": "welcome"
    }
  ]
})
```

**Go**

```go
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, _ := http.NewRequest("POST", "https://api.mailblastr.com/automations", strings.NewReader(`{
  "name": "Welcome series",
  "domain": "yourdomain.com",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": { "event_name": "user.created" }
    },
    {
      "key": "welcome",
      "type": "send_email",
      "config": {
        "template": { "id": "34a080c9-b17d-4187-ad80-5af20266e535" }
      }
    }
  ],
  "connections": [
    { "from": "start", "to": "welcome" }
  ]
}`))
    req.Header.Set("Authorization", "Bearer mb_xxxxxxxxx")
    req.Header.Set("Content-Type", "application/json")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
}
```

**Rust**

```rust
use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let res = Client::new()
        .post("https://api.mailblastr.com/automations")
        .header("Authorization", "Bearer mb_xxxxxxxxx")
        .header("Content-Type", "application/json")
        .body(r#"{
  "name": "Welcome series",
  "domain": "yourdomain.com",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": { "event_name": "user.created" }
    },
    {
      "key": "welcome",
      "type": "send_email",
      "config": {
        "template": { "id": "34a080c9-b17d-4187-ad80-5af20266e535" }
      }
    }
  ],
  "connections": [
    { "from": "start", "to": "welcome" }
  ]
}"#)
        .send()
        .await?;
    println!("{}", res.text().await?);
    Ok(())
}
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mailblastr.com/automations"))
    .header("Authorization", "Bearer mb_xxxxxxxxx")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "name": "Welcome series",
  "domain": "yourdomain.com",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": { "event_name": "user.created" }
    },
    {
      "key": "welcome",
      "type": "send_email",
      "config": {
        "template": { "id": "34a080c9-b17d-4187-ad80-5af20266e535" }
      }
    }
  ],
  "connections": [
    { "from": "start", "to": "welcome" }
  ]
}
"""))
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

**.NET**

```csharp
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.mailblastr.com/automations");
request.Headers.Add("Authorization", "Bearer mb_xxxxxxxxx");
request.Content = new StringContent(@"{
  ""name"": ""Welcome series"",
  ""domain"": ""yourdomain.com"",
  ""steps"": [
    {
      ""key"": ""start"",
      ""type"": ""trigger"",
      ""config"": { ""event_name"": ""user.created"" }
    },
    {
      ""key"": ""welcome"",
      ""type"": ""send_email"",
      ""config"": {
        ""template"": { ""id"": ""34a080c9-b17d-4187-ad80-5af20266e535"" }
      }
    }
  ],
  ""connections"": [
    { ""from"": ""start"", ""to"": ""welcome"" }
  ]
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

**cURL**

```bash
curl -X POST 'https://api.mailblastr.com/automations' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Welcome series",
  "domain": "yourdomain.com",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": { "event_name": "user.created" }
    },
    {
      "key": "welcome",
      "type": "send_email",
      "config": {
        "template": { "id": "34a080c9-b17d-4187-ad80-5af20266e535" }
      }
    }
  ],
  "connections": [
    { "from": "start", "to": "welcome" }
  ]
}'
```

The [trigger](https://www.mailblastr.com/docs/automations/trigger) is defined as the first item in the `steps` array with `type: "trigger"`. `domain` ties the automation to one of your sending domains — only events sent with that `domain` trigger it, so running several products on one account can never cross-fire automations. For more help creating an automation via the API, see the [Create Automation API reference](https://www.mailblastr.com/docs/api/automations-create).

> **Note:** Creating an automation with `status: "enabled"` requires at least one step besides the trigger.

## 2. Define steps

There are several [step types](https://www.mailblastr.com/docs/automations/steps) you can add to your automation:

| Step type | Description |
| --- | --- |
| [Condition](https://www.mailblastr.com/docs/automations/condition) | Branches the workflow based on rules. |
| A/B split | Randomly splits contacts between two branches by a percentage (deterministic per contact). Add a step with `type: "split"` and `config.percent` — branch A rides the True edge, branch B the False edge. |
| [Delay](https://www.mailblastr.com/docs/automations/delay) | Pauses execution for a specified duration. |
| [Wait for Event](https://www.mailblastr.com/docs/automations/wait-for-event) | Pauses execution until a specific event is received. |
| [Send Email](https://www.mailblastr.com/docs/automations/send-email) | Sends an email using a template. |
| [Contact Update](https://www.mailblastr.com/docs/automations/contact-update) | Updates a contact's fields. |
| [Contact Delete](https://www.mailblastr.com/docs/automations/contact-delete) | Deletes the contact. |
| [Add to Segment](https://www.mailblastr.com/docs/automations/add-to-segment) | Adds the contact to a segment. |

## 3. Send an event

Trigger the automation by sending an event from your application. `domain` names the sending domain the event belongs to — only that domain's automations fire. Identify the contact with a `contact_id` or an `email`.

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.events.send({
  "event": "user.created",
  "domain": "yourdomain.com",
  "contact_id": "7f2e4a3b-dfbc-4e9a-8b2c-5f3a1d6e7c8b",
  "payload": {
    "plan": "pro"
  }
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Events.send({
  "event": "user.created",
  "domain": "yourdomain.com",
  "contact_id": "7f2e4a3b-dfbc-4e9a-8b2c-5f3a1d6e7c8b",
  "payload": {
    "plan": "pro"
  }
})
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->events->send([
  'event' => "user.created",
  'domain' => "yourdomain.com",
  'contact_id' => "7f2e4a3b-dfbc-4e9a-8b2c-5f3a1d6e7c8b",
  'payload' => [
    'plan' => "pro"
  ]
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Events.send({
  "event": "user.created",
  "domain": "yourdomain.com",
  "contact_id": "7f2e4a3b-dfbc-4e9a-8b2c-5f3a1d6e7c8b",
  "payload": {
    "plan": "pro"
  }
})
```

**Go**

```go
client := mailblastr.NewClient("mb_xxxxxxxxx")

params := &mailblastr.SendEventRequest{
    Name:   "signup.completed",
    Domain: "yourdomain.com",
    Email:  "jane@example.com",
}
event, err := client.Events.Send(params)
```

**Rust**

```rust
let mb = Mailblastr::new("mb_xxxxxxxxx");

let event = SendEventOptions::new("signup.completed", "yourdomain.com")
    .with_email("jane@example.com");
let _sent = mb.events.send(event).await?;
```

**Java**

```java
Mailblastr mailblastr = new Mailblastr("mb_xxxxxxxxx");

SendEventRequest request = SendEventRequest.builder()
    .name("signup.completed")
    .domain("yourdomain.com")
    .email("jane@example.com")
    .build();
mailblastr.events().send(request);
```

**.NET**

```csharp
IMailblastr mailblastr = MailblastrClient.Create("mb_xxxxxxxxx");

var resp = await mailblastr.EventSendAsync(new EventSendOptions
{
    Name = "signup.completed",
    Domain = "yourdomain.com",
    Email = "jane@example.com",
});
```

**cURL**

```bash
curl -X POST 'https://api.mailblastr.com/events/send' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "event": "user.created",
  "domain": "yourdomain.com",
  "contact_id": "7f2e4a3b-dfbc-4e9a-8b2c-5f3a1d6e7c8b",
  "payload": {
    "plan": "pro"
  }
}'
```

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.events.send({
  "event": "user.created",
  "domain": "yourdomain.com",
  "email": "user@example.com",
  "payload": {
    "plan": "pro"
  }
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Events.send({
  "event": "user.created",
  "domain": "yourdomain.com",
  "email": "user@example.com",
  "payload": {
    "plan": "pro"
  }
})
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->events->send([
  'event' => "user.created",
  'domain' => "yourdomain.com",
  'email' => "user@example.com",
  'payload' => [
    'plan' => "pro"
  ]
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Events.send({
  "event": "user.created",
  "domain": "yourdomain.com",
  "email": "user@example.com",
  "payload": {
    "plan": "pro"
  }
})
```

**Go**

```go
client := mailblastr.NewClient("mb_xxxxxxxxx")

params := &mailblastr.SendEventRequest{
    Name:   "signup.completed",
    Domain: "yourdomain.com",
    Email:  "jane@example.com",
}
event, err := client.Events.Send(params)
```

**Rust**

```rust
let mb = Mailblastr::new("mb_xxxxxxxxx");

let event = SendEventOptions::new("signup.completed", "yourdomain.com")
    .with_email("jane@example.com");
let _sent = mb.events.send(event).await?;
```

**Java**

```java
Mailblastr mailblastr = new Mailblastr("mb_xxxxxxxxx");

SendEventRequest request = SendEventRequest.builder()
    .name("signup.completed")
    .domain("yourdomain.com")
    .email("jane@example.com")
    .build();
mailblastr.events().send(request);
```

**.NET**

```csharp
IMailblastr mailblastr = MailblastrClient.Create("mb_xxxxxxxxx");

var resp = await mailblastr.EventSendAsync(new EventSendOptions
{
    Name = "signup.completed",
    Domain = "yourdomain.com",
    Email = "jane@example.com",
});
```

**cURL**

```bash
curl -X POST 'https://api.mailblastr.com/events/send' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "event": "user.created",
  "domain": "yourdomain.com",
  "email": "user@example.com",
  "payload": {
    "plan": "pro"
  }
}'
```

View the [Send Event API reference](https://www.mailblastr.com/docs/api/events-send) for more details.

## 4. Monitor runs

After sending events, track your automation executions through runs. Each time an event triggers an automation, a run is created to track the execution.

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.automations.runs('c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd');
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Automations.runs("c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd")
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->automations->runs('c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd');
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Automations.runs("c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd")
```

**Go**

```go
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.mailblastr.com/automations/c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd/runs", nil)
    req.Header.Set("Authorization", "Bearer mb_xxxxxxxxx")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
}
```

**Rust**

```rust
use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let res = Client::new()
        .get("https://api.mailblastr.com/automations/c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd/runs")
        .header("Authorization", "Bearer mb_xxxxxxxxx")
        .send()
        .await?;
    println!("{}", res.text().await?);
    Ok(())
}
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mailblastr.com/automations/c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd/runs"))
    .header("Authorization", "Bearer mb_xxxxxxxxx")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

**.NET**

```csharp
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.mailblastr.com/automations/c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd/runs");
request.Headers.Add("Authorization", "Bearer mb_xxxxxxxxx");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

**cURL**

```bash
curl -X GET 'https://api.mailblastr.com/automations/c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd/runs' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'
```

**CLI**

```bash
mailblastr automations runs c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd
```

You can filter runs by status (`running`, `completed`, `failed`, `cancelled`, `skipped`). Learn how to:

- View run statuses and execution details
- Filter runs by status
- Debug failed runs with step-level error information
- Stop automations when needed

See the [Runs documentation](https://www.mailblastr.com/docs/automations/runs) and the [List Automation Runs API reference](https://www.mailblastr.com/docs/api/automations-list-runs) for more details.