API Reference

Create Automation

POST /automations — create an entire automation flow in a single request.

POST/automations

Creates an automation. The trigger is defined as the first item in the steps array with type: "trigger" (its config.event_name is the event that starts a run); a top-level trigger string is also accepted.

Body parameters

namestringrequired

The name of the automation.

statusstringoptional

The status of the automation. One of enabled or disabled. Defaults to disabled. Creating with enabled requires at least one step besides the trigger.

domainstringrequired

The sending domain this automation belongs to (one of your domains, e.g. yourdomain.com). Only events sent with the same domain trigger it.

stepsarrayoptional

The steps that compose the automation graph. Each step is { key, type, config }; the first item with type: "trigger" defines the trigger.

connectionsarrayoptional

The connections between steps. Each is { from, to, type }, where from/to are step keys and type is one of default, condition_met, condition_not_met, event_received, or timeout. Cyclic graphs are rejected.

triggerstringoptional

Optional alternative to a trigger step — the event name that starts the automation, as a plain string. Custom event names cannot start with the reserved mailblastr: prefix; the built-in mailblastr:schedule scheduled trigger is the one exception. Defaults to `contact.created` (the built-in "contact added to audience" trigger) when you supply neither a top-level trigger nor a type: "trigger" step — so an automation created without a trigger is not inert: once enabled it enrolls every contact added to the domain pool.

trigger_configobjectoptional

Required when the trigger is mailblastr:schedule — the built-in scheduled trigger that runs the automation once for every contact in the domain’s audience at a set time. An object { at, timezone }: at is an ISO 8601 instant that must be in the future and at most 366 days ahead; timezone is the IANA timezone name it was picked in (e.g. America/New_York).

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

Response

Returns the full automation object (HTTP 201). The first entry in steps is the trigger step (with its key preserved) and its config also carries the automation domain, followed by the executable steps. Every automation response also carries trigger_key (the key of the type: "trigger" step in your request, and null when the automation was created from a top-level trigger event name with no trigger step in steps) and trigger_config (null unless the trigger is mailblastr:schedule, in which case it holds { at, timezone } and those fields are merged into the trigger step config too).

{
  "object": "automation",
  "id": "c9b16d4f-ba6c-4e2e-b044-6bf4404e57fd",
  "audience_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "domain": "yourdomain.com",
  "name": "Welcome series",
  "trigger": "user.created",
  "status": "disabled",
  "trigger_config": null,
  "trigger_key": "start",
  "steps": [
    {
      "key": "start",
      "type": "trigger",
      "config": { "event_name": "user.created", "domain": "yourdomain.com" }
    },
    {
      "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "key": "welcome",
      "type": "send_email",
      "position": 0,
      "config": {
        "template": { "id": "34a080c9-b17d-4187-ad80-5af20266e535" }
      }
    }
  ],
  "connections": [
    { "from": "start", "to": "welcome", "type": "default" }
  ],
  "created_at": "2026-06-23T10:00:00.000Z",
  "updated_at": "2026-06-23T10:00:00.000Z"
}