Trigger

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` names the domain it targets — so the same event name used across several products never cross-fires. See Using automations for how the steps fit together.

How it works

The trigger is the first node in the editor. Choose an existing custom event 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.

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 });

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:

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).

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 });

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; 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.

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 });

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 });

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.

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 });

In this example, event.amount, event.currency, and event.retryDate become available in email templates, conditions, and other steps.

Configuration

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