Flows: Automation Triggers & Steps

A flow enrolls contacts automatically and runs them through a sequence of steps — send an email, wait, branch, update the contact, call a webhook — based on a trigger you define. Flows live under a tenant, run entirely server-side, and don't require polling: enrollment and every step are event-driven.

How It Works

A flow has three parts: a trigger (what starts enrollment), a steps array (what happens to an enrolled contact, in order), and a status (draft, active, inactive).

Something happens (e.g. a tag is added to a contact)
  ↓
Every active flow whose trigger matches is found
  ↓
Contact is enrolled (idempotent — same event never double-enrolls)
  ↓
Step 0 runs
  ↓
Step 1 runs (immediately, or after a wait step's delay)
  ↓
...
  ↓
Enrollment completes

Under the hood, this is two Cloud Functions talking through Pub/Sub and Cloud Tasks:

1. Trigger evaluation — whatever action fires a trigger (e.g. a tag change) publishes a message. A function queries every active flow whose trigger.type matches, checks the trigger's own config against the event, and creates an enrollment for each match. Enrollment IDs are deterministic (a hash of tenant + flow + contact + trigger context), so the same event can never enroll a contact twice.
2. Step execution — each step runs as its own Cloud Task. A wait step doesn't hold a function open; it schedules the next step's task with a delay and returns immediately. This means a flow with a 14-day wait costs nothing while it waits, and survives deploys, restarts, everything.

A contact is skipped (not failed) if their status is unsubscribed, bounced, or complained at send time — checked fresh on every send_email step, not just at enrollment.

Trigger Types

Trigger config

Trigger config is a flat { key: value } object, string values only. An empty/missing config key means "match any", not "match nothing" — omit it deliberately.

{
  "type": "contact_tag_added",
  "config": { "tagName": "waitlist-confirmed" }
}

Creating a Flow

Creating is two steps: the API only lets you name a flow on creation — trigger and steps are set afterward with PATCH. This mirrors the dashboard builder, which creates an empty draft the moment you click "New flow" and lets you wire it up on the canvas.

1. Create

curl -X POST https://api.tratto.email/v1/flows \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Waitlist nurturing"}'

{ "data": { "id": "flow_8f3ZqXnryVtC5k2Wm7B9e4" } }

2. Configure trigger + steps

curl -X PATCH https://api.tratto.email/v1/flows/flow_8f3ZqXnryVtC5k2Wm7B9e4 \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": {
      "type": "contact_tag_added",
      "config": { "tagName": "waitlist-confirmed" }
    },
    "steps": [
      { "id": "s0", "type": "send_email", "config": { "templateId": "tmpl_welcome", "subject": "You are in", "from": "[email protected]", "fromName": "Your Company" } },
      { "id": "s1", "type": "wait", "config": { "delay": "2", "unit": "hours" } },
      { "id": "s2", "type": "send_email", "config": { "templateId": "tmpl_nurture_1", "subject": "What we are building", "from": "[email protected]", "fromName": "Your Company" } }
    ]
  }'

A flow is created in draft and stays there — enrolling nobody — until you activate it. Max 20 steps per flow. Step ids are your own strings; they only need to be unique within the flow.

Step Types

Every step's config is { key: string }, same as triggers — the API doesn't coerce types, so numbers and booleans go in as strings.

send_email

{ "id": "s0", "type": "send_email", "config": { "templateId": "tmpl_abc123", "subject": "Welcome", "from": "[email protected]", "fromName": "Your Company" } }

Variables available in the template: the contact's email, firstName, lastName, and every key in the contact's customFields are automatically passed in as {{tokens}} — no need to declare them on the step. If a contact has customFields: { "position": "42" }, a template containing {{position}} renders 42 for that send, no extra config required.

wait

{ "id": "s1", "type": "wait", "config": { "delay": "14", "unit": "days" } }

The enrollment's step pointer advances immediately; the next step's task is what's delayed. Checking an enrollment mid-wait correctly shows it's already on the following step index, just not due to run yet.

branch

Evaluates one condition against the contact's own fields (not customFields — top-level fields like status) and jumps to a different step index depending on the result.

{
  "id": "s2",
  "type": "branch",
  "config": {
    "conditionField": "status",
    "conditionOperator": "equals",
    "conditionValue": "subscribed",
    "trueNextStep": "3",
    "falseNextStep": "5"
  }
}

trueNextStep/falseNextStep are step indices into the steps array (as strings), not step IDs — plan the array order before wiring branches.

update_contact

{ "id": "s3", "type": "update_contact", "config": { "action": "add_tag", "tag": "nurtured" } }

webhook_call

Notifies an external URL. The request body is fixed — { "tenantId", "enrollmentId", "stepId" } — it isn't a template you fill in.

{ "id": "s4", "type": "webhook_call", "config": { "url": "https://yourapi.com/hooks/flow-completed", "secret": "whsec_..." } }

10-second timeout; failures are logged but don't stop the flow.

Activating, Deactivating, Editing

# Activate — starts enrolling
curl -X POST https://api.tratto.email/v1/flows/flow_abc123/activate \
  -H "Authorization: Bearer tratto_live_..."

# Deactivate — stops new enrollments, in-progress ones keep running
curl -X POST https://api.tratto.email/v1/flows/flow_abc123/deactivate \
  -H "Authorization: Bearer tratto_live_..."

List, Get, Delete

curl https://api.tratto.email/v1/flows \
  -H "Authorization: Bearer tratto_live_..."

curl https://api.tratto.email/v1/flows/flow_abc123 \
  -H "Authorization: Bearer tratto_live_..."

curl -X DELETE https://api.tratto.email/v1/flows/flow_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Deleting an active flow is blocked the same way editing its steps is — deactivate first.

Testing a Flow

There's no manual enroll-via-API shortcut today (see Trigger Types). To test a contact_tag_added/contact_tag_removed flow end to end:

1. Activate the flow.
2. Create or reuse a throwaway test contact.
3. Add the exact tag the trigger is configured for, via PATCH /v1/contacts/:id.
4. Check GET /v1/flows/flow_abc123 — enrollments should increment, and the test contact should receive the first send_email step within seconds.

Why Build a Flow

Anything that's "when X happens to a contact, do Y over time" — without you writing and hosting the scheduling logic yourself.

Signup / waitlist nurturing. Tag a contact waitlist-confirmed the moment they double-opt-in, and let a flow run a welcome email immediately, then a short drip (what you're building, why it's priced the way it is, a product preview, an early-access offer) spaced days or weeks apart — this exact pattern is what Tratto's own waitlist runs on.

Re-engagement / win-back. Run your own inactivity check (last email open date, last login, whatever signals "gone quiet") on a schedule, tag matching contacts inactive-30d, and let a flow send a win-back sequence — one nudge, then a discount or feature update, then a final "we'll stop emailing you" notice paired with an update_contact step that unsubscribes them if they still haven't engaged.

Onboarding checklist. Tag a contact when they sign up for your product; drip a few days of "have you tried X yet" emails, each pointing at a different feature, with wait steps giving them time to actually go try it before the next nudge.

Sales handoff on high intent. Tag a contact pricing-page-viewed-3x (from your own tracking) and use a webhook_call step to ping a Slack channel or CRM the moment it happens — the flow becomes the trigger for a human process, not just more email.

Data hygiene. Tag contacts entering a specific state (trial-expired, payment-failed) and use update_contact steps to normalize a lifecycle_stage field, so segmentation elsewhere in the product (audiences, campaigns) stays consistent without a manual cleanup pass.

Best Practices

Design around the one live trigger. Until contact_joins_audience/email_event/manual are wired up, every flow effectively starts from a tag change. Get comfortable tagging contacts from your own application code at the moments that matter — that's the real entry point.

Set tagName explicitly. An empty tag trigger matches every tag change on every contact. Always fill it in.

Name flows for what they do, not what they are. Post-purchase 7-day follow-up, not Flow 3.

Deactivate before editing steps. You can't avoid this — the API enforces it — so build the habit early rather than hitting the error mid-edit.

Space sends deliberately. wait steps are free and asynchronous — there's no cost pressure to compress a sequence. Give contacts time to actually read and act on one email before the next arrives.

Next Steps

• Track flow-sent emails? Set up Webhooks
• Send via API directly? See Send Email
• Build the templates a flow sends? Go to Templates
• Manage contact tags? See Contacts