# Trigger

> The first step of every automation — the event that starts a run for a contact.

A **trigger** is the first step in every automation. It defines which event starts the automation when MailBlastr receives it.

When your application sends an event to MailBlastr, every **enabled** automation with a matching trigger **on the event's domain** executes its workflow for the identified contact. Every automation belongs to one of your sending domains (shown on the trigger step), and [`POST /events/send`](https://www.mailblastr.com/docs/api/events-send) names the domain it targets — so the same event name used across several products never cross-fires. See [Using automations](https://www.mailblastr.com/docs/automations/overview) for how the steps fit together.

## How it works

The trigger is the first node in the editor. Choose an existing [custom event](https://www.mailblastr.com/docs/automations/custom-events) or type a new event name, and pick the **domain** the automation belongs to (selected automatically when you have one domain). When creating an automation over the API, the trigger is the first item in the `steps` array with `type: "trigger"`, and `domain` is a required top-level field.

**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" }
    }
  ],
  "connections": []
});
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"
      }
    }
  ],
  "connections": []
})
```

**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"
      ]
    ]
  ],
  'connections' => []
]);
```

**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"
      }
    }
  ],
  "connections": []
})
```

**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" }
    }
  ],
  "connections": []
}`))
    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" }
    }
  ],
  "connections": []
}"#)
        .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" }
    }
  ],
  "connections": []
}
"""))
    .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"" }
    }
  ],
  ""connections"": []
}", 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" }
    }
  ],
  "connections": []
}'
```

> **Warning:** Event names cannot start with the `mailblastr:` prefix, which is reserved for system events.

## Engagement triggers

Besides custom events, an automation can start when a contact **engages** with one of your emails. Set the trigger to one of these built-in events — no code required, the platform enrolls the contact automatically:

| Trigger | Starts a run when… |
| --- | --- |
| `email.opened` | the contact opens one of your emails |
| `email.clicked` | the contact clicks a link in one of your emails |
| `email.replied` | the contact replies to one of your emails |
| `email.bounced` | an email to the contact bounces (e.g. tag or notify on bounce) |
| `email.delivered` | an email to the contact is delivered (post-delivery sequences) |

In the editor, pick one under **Event trigger… → When a recipient…**. Over the API, pass the event name as the trigger string (or the trigger step's `config.event_name`).

**Node.js**

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

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.automations.create({
  "name": "Re-engage on click",
  "domain": "yourdomain.com",
  "trigger": "email.clicked",
  "steps": [
    { "key": "start", "type": "trigger", "config": { "event_name": "email.clicked" } }
  ],
  "connections": []
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Automations.create({
  "name": "Re-engage on click",
  "domain": "yourdomain.com",
  "trigger": "email.clicked",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": {
        "event_name": "email.clicked"
      }
    }
  ],
  "connections": []
})
```

**PHP**

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

$mailblastr->automations->create([
  'name' => "Re-engage on click",
  'domain' => "yourdomain.com",
  'trigger' => "email.clicked",
  'steps' => [
    [
      'key' => "start",
      'type' => "trigger",
      'config' => [
        'event_name' => "email.clicked"
      ]
    ]
  ],
  'connections' => []
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Automations.create({
  "name": "Re-engage on click",
  "domain": "yourdomain.com",
  "trigger": "email.clicked",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": {
        "event_name": "email.clicked"
      }
    }
  ],
  "connections": []
})
```

**Go**

```go
package main

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

func main() {
    req, _ := http.NewRequest("POST", "https://api.mailblastr.com/automations", strings.NewReader(`{
  "name": "Re-engage on click",
  "domain": "yourdomain.com",
  "trigger": "email.clicked",
  "steps": [
    { "key": "start", "type": "trigger", "config": { "event_name": "email.clicked" } }
  ],
  "connections": []
}`))
    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": "Re-engage on click",
  "domain": "yourdomain.com",
  "trigger": "email.clicked",
  "steps": [
    { "key": "start", "type": "trigger", "config": { "event_name": "email.clicked" } }
  ],
  "connections": []
}"#)
        .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": "Re-engage on click",
  "domain": "yourdomain.com",
  "trigger": "email.clicked",
  "steps": [
    { "key": "start", "type": "trigger", "config": { "event_name": "email.clicked" } }
  ],
  "connections": []
}
"""))
    .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"": ""Re-engage on click"",
  ""domain"": ""yourdomain.com"",
  ""trigger"": ""email.clicked"",
  ""steps"": [
    { ""key"": ""start"", ""type"": ""trigger"", ""config"": { ""event_name"": ""email.clicked"" } }
  ],
  ""connections"": []
}", 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": "Re-engage on click",
  "domain": "yourdomain.com",
  "trigger": "email.clicked",
  "steps": [
    { "key": "start", "type": "trigger", "config": { "event_name": "email.clicked" } }
  ],
  "connections": []
}'
```

> **Note:** Engagement on an email that an automation itself sent does not re-trigger an automation — this prevents send → open → re-enrol loops. Only opens, clicks and replies on your regular (API, campaign, or manual) sends start engagement automations. Engagement triggers are domain-scoped like everything else: a click on an email sent from `abc.com` only starts `abc.com`'s automations.

A **poll vote** also emits a trigger. When a recipient answers an in-email poll, a `poll.responded` event fires for the contact with the chosen answer available as `event.answer` — set an automation trigger (or a `wait_for_event` step) to `poll.responded` to branch on how they voted. Only existing contacts trigger it.

## Identifying contacts

When you send an event to start an automation, you must identify the contact with either a `contact_id` or an `email`, and name the `domain` the event belongs to. Use `contact_id` when the contact already exists in your [audience](https://www.mailblastr.com/docs/audiences/overview); use `email` to look the contact up by address. If no contact with the provided email exists in that domain's contacts, MailBlastr creates one when the run starts — each domain keeps its own contact records, so unsubscribe state stays separate per product.

**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": "26e2b838-bf6d-4515-b6a7-17525b12b05a",
  "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": "26e2b838-bf6d-4515-b6a7-17525b12b05a",
  "payload": {
    "plan": "pro"
  }
})
```

**PHP**

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

$mailblastr->events->send([
  'event' => "user.created",
  'domain' => "yourdomain.com",
  'contact_id' => "26e2b838-bf6d-4515-b6a7-17525b12b05a",
  'payload' => [
    'plan' => "pro"
  ]
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Events.send({
  "event": "user.created",
  "domain": "yourdomain.com",
  "contact_id": "26e2b838-bf6d-4515-b6a7-17525b12b05a",
  "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": "26e2b838-bf6d-4515-b6a7-17525b12b05a",
  "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" }
}'
```

## Event payload

Include a `payload` object with your event to pass data into the automation. This data becomes available as variables in later steps through the `event.*` namespace.

**Node.js**

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

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.events.send({
  "event": "payment.failed",
  "domain": "yourdomain.com",
  "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "payload": {
    "amount": 49.99,
    "currency": "USD",
    "retryDate": "2026-11-01"
  }
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Events.send({
  "event": "payment.failed",
  "domain": "yourdomain.com",
  "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "payload": {
    "amount": 49.99,
    "currency": "USD",
    "retryDate": "2026-11-01"
  }
})
```

**PHP**

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

$mailblastr->events->send([
  'event' => "payment.failed",
  'domain' => "yourdomain.com",
  'contact_id' => "e169aa45-1ecf-4183-9955-b1499d5701d3",
  'payload' => [
    'amount' => 49.99,
    'currency' => "USD",
    'retryDate' => "2026-11-01"
  ]
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Events.send({
  "event": "payment.failed",
  "domain": "yourdomain.com",
  "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "payload": {
    "amount": 49.99,
    "currency": "USD",
    "retryDate": "2026-11-01"
  }
})
```

**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": "payment.failed",
  "domain": "yourdomain.com",
  "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "payload": {
    "amount": 49.99,
    "currency": "USD",
    "retryDate": "2026-11-01"
  }
}'
```

In this example, `event.amount`, `event.currency`, and `event.retryDate` become available in email templates, [conditions](https://www.mailblastr.com/docs/automations/condition), and other steps.

## Configuration

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `config.event_name` | string | Yes | The name of the event that triggers the automation. |

```json
{
  "key": "start",
  "type": "trigger",
  "config": {
    "event_name": "user.created"
  }
}
```