Automations

Automations are created and configured in the TopMail dashboard. The API provides programmatic control over activation, triggering, and monitoring.

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"}'

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: "running", "completed", or "failed".
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"