Automating Emails with Workflows | Cakemail Documentation

Feature in development

The Automation API is being updated. Some details on this page may change. Contact support for the latest status.

The Automation API lets you build email sequences triggered by subscriber actions. When someone subscribes to a list, you can automatically send a welcome email, follow up three days later, and continue based on engagement.

Concepts

Workflows

A workflow is an ordered sequence of actions triggered by an event on a contact list. Workflows start with a trigger (e.g., a new subscription) and execute actions over time.

Actions

An action performs a task — currently, sending an email. Actions can be chained: each action references a parent and executes after a delay and/or condition (e.g., parent email was opened or clicked).

Create a workflow

Create a workflow by specifying a target audience (list) and a trigger event:

curl -X POST https://api.cakemail.dev/workflows \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series",
    "goal": "Onboard new subscribers",
    "trigger": "subscribed",
    "audience": { "list_id": LIST_ID }
  }'

The response includes a workflow ID. Workflows are inactive by default so you can add actions before they start executing.

Add actions

First action (no parent)

The first action has no parent — it's triggered directly by the workflow:

curl -X POST https://api.cakemail.dev/workflows/WORKFLOW_ID/actions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome email",
    "type": "email",
    "condition": "none",
    "delay": 0,
    "email_settings": {
      "sender": { "id": SENDER_ID },
      "tracking": { "opens": true, "clicks_html": true, "clicks_text": true },
      "content": {
        "subject": "Welcome!",
        "html": "<html><body>Thanks for subscribing.</body></html>",
        "type": "html",
        "encoding": "utf-8"
      }
    }
  }'

Chained action (with parent and delay)

Subsequent actions reference their parent and specify a delay in seconds. This example sends a follow-up 3 days (259200 seconds) after the first email:

curl -X POST https://api.cakemail.dev/workflows/WORKFLOW_ID/actions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Follow-up email",
    "type": "email",
    "parent_id": FIRST_ACTION_ID,
    "condition": "none",
    "delay": 259200,
    "email_settings": {
      "sender": { "id": SENDER_ID },
      "tracking": { "opens": true, "clicks_html": true, "clicks_text": true },
      "content": {
        "subject": "How are you finding things?",
        "html": "<html><body>Just checking in.</body></html>",
        "type": "html",
        "encoding": "utf-8"
      }
    }
  }'

Action conditions

The condition field controls when a chained action executes relative to its parent:

Condition	Behavior
`none`	Execute after the delay regardless of parent outcome
`sent`	Execute only if the parent email was sent
`opened`	Execute only if the parent email was opened
`clicked`	Execute only if a link in the parent email was clicked

Activate the workflow

Once all actions are in place, activate the workflow:

curl -X POST https://api.cakemail.dev/workflows/WORKFLOW_ID/activate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Test it by subscribing to the target contact list.

List workflow actions

Review the actions in an existing workflow:

curl https://api.cakemail.dev/workflows/WORKFLOW_ID/actions?page=1&per_page=50 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Modifying workflows

To modify a workflow or its actions, you must deactivate it first. Make your changes, then re-activate.