Flows API

Endpoints

A flow in one object

A flow is a trigger — who enters — and steps — what happens to them, in order. That's the whole model. Steps run top to bottom until the list ends or the contact exits.

curl -X POST https://emailbump.com/api/v1/flows \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series",
    "trigger": { "type": "contact_created" },
    "steps": [
      { "type": "send", "subject": "Welcome to Acme",
        "html": "<p>Hi {{ contact.first_name | default: \"there\" }}, thanks for joining.</p>" },
      { "type": "wait", "days": 3 },
      { "type": "send", "subject": "Three things to try",
        "html": "<p>Here is where most people start…</p>" }
    ]
  }'

A new flow is active and enrolling immediately. Pass "status": "draft" to build it without starting it, then test it and POST …/activate when the output looks right.

{
  "id": "c4d5e6f7-…",
  "name": "Welcome series",
  "status": "active",
  "trigger": { "type": "contact_created" },
  "reenrollment": "not_while_active",
  "steps": [ … ],
  "created_at": "2026-08-01T09:12:44Z",
  "updated_at": "2026-08-01T09:12:44Z"
}

GET /v1/flows/{id} gives back the same shape, steps included. A flow drawn on the dashboard canvas can have paths that rejoin, which no step list can express — those come back with "steps": null and are edited in the dashboard.

Triggers

The trigger decides who enters and when. Its fields sit alongside type:

A supplied list_id, segment_id, campaign_id, or form_id must belong to this project; an unknown or cross-project reference is a 400.

For form-driven welcome sequences, use { "type": "form_submit" }. It also covers existing contacts submitting a form. Double-opt-in submissions wait for confirmation before firing the form trigger.

Before you build one

Start with GET /v1/me using either key scope to see the selected project, email confirmation, verified domains and footer. The account-level project endpoints below require an all-access key. These setup checks do not bypass quota, suspension, consent or abuse checks at send time.

Create with {"status":"draft"} until the content is approved: omitting status creates an active flow. Test sends go to real recipients; use only a mailbox you control, then activate deliberately.

A flow sends real email to real people, repeatedly, with nobody watching. Four checks first — one request each, and skipping them is how a welcome series goes out from the wrong address with no way to unsubscribe.

1. Know which project you're in. GET /v1/projects lists them flat with the workspace each belongs to. A workspace and its first project share a name by default, so read the object field rather than guessing.
2. Give the project a real postal address. GET /v1/projects/{id} returns email_footer. If is_your_own_address is false, every email prints Email Bump's address as the sender's. Set yours with PATCH /v1/projects/{id}.
3. Have a verified sending domain. Mail from an unverified domain doesn't land anywhere good.
4. Set the sender on every send step. from_email and from_name are optional in the schema, but set them explicitly in your request — without them the email goes from the project's verified domain with no display name, or from the shared domain if it has verified none.

Steps

Every step is an object with a type:

Personalize subjects and bodies with Liquid — {{ contact.first_name }}, with {{ contact.first_name | default: "there" }} for a fallback. Contacts who are unsubscribed or bounced are skipped at send steps automatically. A field a step doesn't take is a 400 naming the valid ones — same contract as the flow's root, so a typo'd preheader can't silently vanish.

A/B test an email

Give a send step two or more variants and it becomes a test: each contact is assigned one as they reach the step, and the flow report breaks that step down by variation. Every field is an override — leave it out and the base step's value stands, so a subject-line test is two variations that differ only in subject.

{
  "type": "send",
  "subject": "Your Acme trial",
  "html": "<p>Here's what to try first…</p>",
  "variants": [
    { "label": "A", "subject": "Your Acme trial starts now", "split_percent": 60 },
    { "label": "B", "subject": "3 things to try in Acme", "split_percent": 40 }
  ]
}

Branching and waiting

A branch asks a question about the contact and carries on down yes or no. Each path is its own list of steps, nested as deep as you like — so a branch ends the list it's in, and anything that should happen afterwards goes inside the paths.

{
  "type": "branch",
  "condition": {
    "match": "all",
    "conditions": [
      { "type": "attribute", "key": "plan", "op": "eq", "value": "pro" }
    ]
  },
  "yes": [
    { "type": "send", "subject": "Your Pro features", "html": "<p>…</p>" }
  ],
  "no": [
    { "type": "wait", "days": 2 },
    { "type": "send", "subject": "What Pro adds", "html": "<p>…</p>" }
  ]
}

The condition is a segment definition — the same shape segments use, so anything you can target you can branch on:

{
  "type": "branch",
  "condition": {
    "match": "all",
    "conditions": [
      { "type": "email", "event": "open", "performed": true, "scope": "flow_last" }
    ]
  },
  "yes": [ { "type": "exit" } ],
  "no":  [ { "type": "send", "subject": "One more thing", "html": "<p>…</p>" } ]
}

A wait_event step waits for something to happen instead of asking whether it already has. The contact carries on with the following steps the moment the event arrives; if it never does, the timeout steps run instead.

curl -X POST https://emailbump.com/api/v1/flows \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Abandoned checkout",
    "trigger": { "type": "event", "event_key": "Checkout started" },
    "steps": [
      { "type": "wait", "hours": 4 },
      { "type": "wait_event", "event": "Purchased", "timeout_days": 2,
        "timeout": [
          { "type": "send", "subject": "Still thinking it over?", "html": "<p>…</p>" },
          { "type": "wait", "days": 3 },
          { "type": "send", "subject": "10% off, until Friday", "html": "<p>…</p>" }
        ] },
      { "type": "set_attribute", "key": "converted_from", "value": "checkout_flow" },
      { "type": "exit" }
    ]
  }'

Test a flow

POST /v1/flows/{id}/test sends each of the flow's send steps to one address — without activating the flow or enrolling anyone, so it works on a draft. Rendering goes through the real flow pipeline: Liquid, preview text, the marketing footer with its unsubscribe link, and the generated text part. That's what a subscriber receives, which sending the same HTML through POST /v1/emails (transactional, no footer) can't show you.

curl -X POST https://emailbump.com/api/v1/flows/FLOW_ID/test \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "[email protected]" }'

Test sends are tagged stream: test, so they stay out of the flow's metrics. They do count toward your plan's monthly email allowance.

Activate, pause, delete

A flow is active, paused, or draft. Pausing stops new enrollments; contacts already inside carry on to the end.

curl -X POST https://emailbump.com/api/v1/flows/FLOW_ID/pause \
  -H "Authorization: Bearer ebk_your_key"

curl -X POST https://emailbump.com/api/v1/flows/FLOW_ID/activate \
  -H "Authorization: Bearer ebk_your_key"

PATCH edits any of the create fields, steps included — a new step list replaces the old one wholesale. Editing a live flow publishes the change immediately; contacts already partway through finish on the version they entered on, so nobody gets a step twice or skips one mid-journey.

curl -X PATCH https://emailbump.com/api/v1/flows/FLOW_ID \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series v2",
    "steps": [
      { "type": "wait", "hours": 2 },
      { "type": "send", "subject": "Welcome to Acme", "html": "<p>…</p>" }
    ]
  }'

DELETE /v1/flows/{id} removes the flow and its steps and returns 204 — but only if nobody has ever been through it. Once a single contact has been enrolled the flow is permanent, and the call returns 409.

curl -X DELETE https://emailbump.com/api/v1/flows/FLOW_ID \
  -H "Authorization: Bearer ebk_your_key"

Enroll and observe

Put one contact into an active flow yourself — the way to drive a manual flow, and the quickest way to test any other:

curl -X POST https://emailbump.com/api/v1/flows/FLOW_ID/enroll \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

{ "enrolled": true, "flow_id": "c4d5…", "contact_id": "5fef…" }

enrolled: false means the re-enrollment policy or the entry filter turned them away — not an error.

GET /v1/flows/{id}/enrollments shows who is in the flow and where they are, newest first. Filter with ?status= (active, processing, completed, exited, failed) and page with ?limit= and ?offset=.

{
  "data": [
    {
      "id": "0f1e…",
      "contact_id": "5fef…",
      "email": "[email protected]",
      "status": "active",
      "steps_run": 2,
      "next_run_at": "2026-08-04T09:12:44Z",
      "last_error": null,
      "enrolled_at": "2026-08-01T09:12:44Z",
      "completed_at": null
    }
  ],
  "total": 1240,
  "limit": 25,
  "offset": 0
}

Per-step performance — sends, opens, clicks, and which way contacts went at each branch — is on the flow's report in the dashboard.