Automations

Mental model

An automation is an ordered list of steps, each step combining a template, a subject, and a trigger. The trigger fires the step's send.

• Delay triggers wait a relative duration after the previous step (or after the contact joins a list). E.g. 24h, 30m, 7d.
• Event triggers wait for a specific product event POSTed to /api/v1/events. E.g. fire only when signup_completed arrives for the contact.

A worked example

A 5-day onboarding flow that pauses if the user activates:

POST /api/v1/automations
{
  "slug":    "onboarding-v1",
  "listSlug": "all-users",
  "steps": [
    { "id": "welcome",     "template": "welcome",     "subject": "Welcome to {{product_name}}",
      "trigger": { "type": "delay", "delay": "0h" } },

    { "id": "tour",        "template": "tour",        "subject": "5 things to try first",
      "trigger": { "type": "delay", "delay": "24h" } },

    { "id": "first-value", "template": "first-value", "subject": "Did you create your first {{noun}}?",
      "trigger": { "type": "event", "event": "first_value_blocked" } },

    { "id": "day-5",       "template": "day-5-recap", "subject": "5 days in",
      "trigger": { "type": "delay", "delay": "5d" } }
  ]
}

When a contact joins all-users, the worker schedules step 1 immediately, step 2 24h after step 1's send, and step 4 five days after step 3's send. Step 3 fires only if your app POSTs the first_value_blocked event for that contact within the window — otherwise the flow waits.

Step UI in the dashboard

You don't have to author JSON. The Automations page has a structured step builder:

• Template dropdown — populated from your active templates. Inactive references show (inactive) with a warning icon so you know to reassign.
• Subject input — plain text, Handlebars allowed.
• Trigger toggle — radio between Delay (24h / 30m / 7d format, live-validated) and Event (any non-empty event name).
• Reorder — ▴/▾ buttons per row.
• Step ID — auto-generated; pencil icon to rename. Used in the unique index that prevents duplicate sends.

The list-slug field is a dropdown of your existing lists (with (not found) fallback for legacy values). Save validates client-side first — Save button stays disabled until all steps are well-formed.

Triggering by event

Your application POSTs events to Mailazy whenever business actions happen. Each event includes a contact reference (id or email):

POST /api/v1/events
{
  "event":   "signup_completed",
  "email":   "alice@example.com",       // or "contactId": "contact_..."
  "data":    { "plan": "pro" }          // optional context, accessible in templates
}

Any automation step whose trigger.event matches and whose contact is in the source list fires. Event payload data is merged into the template variable set, so a step can reference {{plan}} in subject or body.

Naming conventions

Event names are arbitrary, but stick to lowercase snake_case for hygiene: signup_completed, first_payment_succeeded, plan_downgraded, usage_threshold_80. You'll thank yourself when the list grows past 30.

Suppression and unsubscribe

Automations respect both per-list unsubscribes (the contact left the source list) and global suppressions. A suppressed contact has all pending steps cancelled the moment the suppression is recorded.

Editing live automations

The structured editor is safe to use on live automations — but understand the semantics:

• Editing a step's template or subject affects only future sends. Already-queued sends use the version pinned at queue time.
• Deleting a step removes it from future flow runs. In-flight contacts mid-flow continue to the next remaining step.
• Reordering steps doesn't reshuffle in-flight contacts — they continue from their current position in the original order.

Observability

Per-automation analytics are surfaced in the dashboard:

• Active contacts at each step.
• Send / open / click / unsubscribe rates per step.
• Drop-off chart across the flow.

Raw event data is in /api/v1/logs filterable by configFile=automation:{slug}.

Related

• Templates — what each step sends.
• Contacts & lists — the source list drives membership-based triggers.
• Webhooks — handle delivery events from automation sends.