Automations

Create, manage, and trigger automations programmatically. Build complete workflows with steps via the API or manage them individually.

POST

/automations

Create a new automation with optional inline steps.

Request Body

Name	Type	Required	Description
name	string	Required	Name for the automation.
trigger_type	string	Required	Trigger type (e.g. "signup", "purchase", "tag_added", "custom"). See trigger types table below.
trigger_config	object	Optional	Configuration for the trigger (e.g. list ID, tag name). Defaults to {}.
steps	array	Optional	Array of steps to create inline. Each step has step_type, optional config, and optional position.

Inline Steps

Steps can be provided inline during creation or added separately via the POST /automations/:id/steps endpoint. New automations always start in draft status.

curl -X POST https://api.topmail.so/api/v1/automations \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Series",
    "trigger_type": "signup",
    "steps": [
      { "step_type": "email", "config": { "templateId": "tpl_abc", "subject": "Welcome!" } },
      { "step_type": "delay", "config": { "duration": 2, "unit": "days" } },
      { "step_type": "email", "config": { "templateId": "tpl_def", "subject": "Getting Started" } }
    ]
  }'

GET

/automations

List all automations with optional status filtering.

Query Parameters

Name	Type	Required	Description
status	string	Optional	Filter by status: "draft", "active", or "paused".
limit	integer	Optional	Number of automations to return (default: 100, max: 1000).
offset	integer	Optional	Number of automations to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/automations?status=active&limit=10" \
  -H "Authorization: Bearer tm_live_abc123"

GET

/automations/:id

Retrieve a single automation with steps and run count.

curl https://api.topmail.so/api/v1/automations/AUTOMATION_ID \
  -H "Authorization: Bearer tm_live_abc123"

PATCH

/automations/:id

Update an automation name or status.

Request Body

Name	Type	Required	Description
name	string	Optional	Updated automation name.
status	string	Optional	Set to "active" or "paused". See status lifecycle below.

Status Lifecycle

Automations follow a strict status lifecycle: draft → active (requires at least one step). Active automations can be toggled: active ↔ paused.

curl -X PATCH https://api.topmail.so/api/v1/automations/AUTOMATION_ID \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

DELETE

/automations/:id

Delete an automation (soft delete).

curl -X DELETE https://api.topmail.so/api/v1/automations/AUTOMATION_ID \
  -H "Authorization: Bearer tm_live_abc123"

POST

/automations/:id/steps

Add a step to an automation.

Request Body

Name	Type	Required	Description
step_type	string	Required	Type of step to add. See step types below.
config	object	Optional	Step configuration. Defaults are provided if omitted.
position	integer	Optional	Position to insert the step (0-indexed). Appends to end if omitted.

Step Types

Type	Description
`email`	Send an email using a template
`sms`	Send an SMS message
`push`	Send a push notification
`delay`	Wait for a specified duration
`condition`	Branch based on a contact field condition
`action`	Perform an action (add/remove from list, update attribute, webhook)
`tag`	Add or remove a tag from the contact
`trigger_split`	Split contacts into branches based on a field
`add_to_list`	Add the contact to a list
`remove_from_list`	Remove the contact from a list
`update_attribute`	Update a contact attribute
`webhook`	Send a webhook to an external URL
`wait_for_event`	Wait for a specific event before continuing
`move_to_flow`	Move the contact to another automation

Step Config Reference

Each step type accepts specific config fields. Defaults are provided if config is omitted.

emaildefault: { templateId: null, subject: "", previewText: "" }

templateId	string \| null	Template ID to use for the email content.
subject	string	Email subject line (required).
previewText	string	Preview text shown in inbox.

delaydefault: { duration: 1, unit: "days" }

duration	number	How long to wait.
unit	string	"minutes", "hours", "days", or "weeks".

conditiondefault: { field: "", operator: "equals", value: "" }

field	string	Contact field to evaluate (e.g. "email", "first_name", or a custom attribute).
operator	string	"equals", "not_equals", "contains", "gt", "lt", "gte", or "lte".
value	string \| number \| boolean	Value to compare against.
trueBranchStepId	string \| null	Step ID to jump to if condition is true.
falseBranchStepId	string \| null	Step ID to jump to if condition is false.

tagdefault: { action: "add", tagName: "" }

action	string	"add" or "remove".
tagName	string	Name of the tag.

add_to_list / remove_from_listdefault: { listId: null }

listId

string

The list ID to add/remove the contact from.

update_attributedefault: { attributeName: "", attributeValue: "" }

attributeName	string	Contact attribute name to update.
attributeValue	string	Value to set.

webhookdefault: { url: "", method: "POST", headers: {} }

url	string	Webhook URL (required).
method	string	"GET", "POST", "PUT", or "PATCH".
headers	object	Custom headers as key-value pairs.
body	object \| string	Request body.

wait_for_eventdefault: { eventType: "email_opened", timeoutDays: 7, timeoutAction: "continue" }

eventType	string	"email_opened", "email_clicked", "purchase", or "page_viewed".
timeoutDays	number	Days to wait before timing out.
timeoutAction	string	"continue" (proceed to next step), "skip" (skip next step), or "branch" (jump to timeoutBranch).

move_to_flowdefault: { targetFlowId: "", exitCurrentFlow: true }

targetFlowId	string	Target automation ID to move the contact to.
exitCurrentFlow	boolean	If true, exit current automation. If false, run both in parallel.

curl -X POST https://api.topmail.so/api/v1/automations/AUTOMATION_ID/steps \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "step_type": "delay",
    "config": { "duration": 3, "unit": "days" },
    "position": 1
  }'

PATCH

/automations/:id/steps/:stepId

Update a step's type or configuration.

Request Body

Name	Type	Required	Description
step_type	string	Optional	New step type.
config	object	Optional	Updated step configuration.

curl -X PATCH https://api.topmail.so/api/v1/automations/AUTOMATION_ID/steps/STEP_ID \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "duration": 5, "unit": "days" } }'

DELETE

/automations/:id/steps/:stepId

Remove a step from an automation.

curl -X DELETE https://api.topmail.so/api/v1/automations/AUTOMATION_ID/steps/STEP_ID \
  -H "Authorization: Bearer tm_live_abc123"

POST

/automations/:id/trigger

Manually trigger an automation for a specific contact.

Request Body

Name	Type	Required	Description
contact_id	string (UUID)	Optional	Contact ID to trigger for. Provide either contact_id or email.
email	string	Optional	Contact email to trigger for. Provide either contact_id or email.
trigger_data	object	Optional	Additional data to pass to the automation run.

curl -X POST https://api.topmail.so/api/v1/automations/AUTOMATION_ID/trigger \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "trigger_data": {"source": "api", "plan": "pro"}
  }'

Trigger Types

Automations support the following trigger types. The API trigger endpoint works with any automation regardless of its configured trigger type.

Type	Description
`signup`	Contact signs up or is created
`tag_added`	Tag is assigned to a contact
`added_to_list`	Contact is added to a list
`email_open`	Contact opens an email
`email_click`	Contact clicks a link in an email
`product_viewed`	Contact views a product (tracking)
`purchase`	Contact completes a purchase
`custom`	Custom event triggered via API

GET

/automations/:id/runs

List runs for an automation with optional status filtering.

Query Parameters

Name	Type	Required	Description
status	string	Optional	Filter by run status: "active", "completed", "failed", or "paused".
limit	integer	Optional	Number of runs to return (default: 100, max: 1000).
offset	integer	Optional	Number of runs to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/automations/AUTOMATION_ID/runs?status=completed&limit=20" \
  -H "Authorization: Bearer tm_live_abc123"