Campaigns

Where an event went

GET/v1/events/journey

Scope: campaigns:read. MCP tool: get_event_journey.

Follow one event through every campaign: pass exactly one of custom_event_id, checkout_id, order_id or subscription_event_id. Returns the event, each campaign that picked it up with its run steps (entered, skipped with the reason, sent; for legacy v1 campaigns, the lifecycle states of each conversation), the conversations it produced and any recovered order. Use it to check that a new custom event reached the right campaign, or why a checkout was not texted.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

custom_event_id?string

checkout_id?string

order_id?string

subscription_event_id?string

Response Body

`application/json`

curl -X GET "https://example.com/v1/events/journey"

{  "source": {    "kind": "custom_event",    "custom_event": {      "id": "string",      "type": "string",      "name": "string",      "source": "string",      "external_event_id": "string",      "received_at": "string"    },    "checkout": {      "id": "string",      "state": "string",      "total": {        "amount": 0,        "currency": "string"      },      "created_at": "string",      "abandoned_at": "string",      "completed_at": "string"    },    "order": {      "id": "string",      "number": "string",      "total": {        "amount": 0,        "currency": "string"      },      "created_at": "string"    },    "subscription_event": {      "id": "string",      "type": "string",      "triggered_at": "string"    }  },  "campaigns": [    {      "campaign_id": "string",      "campaign_name": "string",      "outcome": "string",      "run": [        {          "at": "string",          "state": "string",          "step": "string",          "step_id": "string",          "event_type": "string",          "event_id": "string",          "campaign_id": "string",          "campaign_name": "string",          "conversation_id": "string",          "contact_id": "string",          "reason": {            "code": "string",            "label": "string",            "level": "string",            "rule": "string"          },          "error": "string"        }      ]    }  ],  "conversations": [    {      "conversation_id": "string",      "created_at": "string",      "campaign_id": "string",      "campaign_name": "string"    }  ],  "outcome": {    "recovered": true,    "recovered_amount": {      "amount": 0,      "currency": "string"    },    "goals": [      {        "at": "string",        "conversation_id": "string",        "campaign_id": "string",        "order_id": "string",        "order_number": "string",        "amount": {          "amount": 0,          "currency": "string"        },        "attribution": "string",        "billing_status": "string",        "recovered": true      }    ]  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Performance stats

GET/v1/stats

Scope: stats:read. MCP tool: get_performance_stats.

View performance for a date range or campaign, and compare periods. Pass stats as repeated or comma-separated query parameters. Unrecognized metrics are listed in errors.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

stats*array<string>

from?string

to?string

compare_from?string

compare_to?string

campaign_id?string

timezone?string

Response Body

`application/json`

curl -X GET "https://example.com/v1/stats?stats=string"

{  "stats": [    {      "name": "string",      "title": "string",      "description": "string",      "current_value": "string",      "previous_value": "string",      "progress": 0,      "chart": {        "dates": [          "string"        ],        "values": [          0        ]      },      "comparison_chart": {        "dates": [          "string"        ],        "values": [          0        ]      }    }  ],  "errors": [    "string"  ],  "date_range": {    "from": "string",    "to": "string",    "compare_from": "string",    "compare_to": "string"  },  "brand_id": "string",  "query": {    "stats": [      "string"    ],    "campaign_id": "string",    "timezone": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

List campaigns

GET/v1/campaigns

Scope: campaigns:read. MCP tool: list_campaigns.

View campaigns and their status. Use the returned IDs to open a campaign or compare performance.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

status?string

include_historical?boolean

Response Body

`application/json`

curl -X GET "https://example.com/v1/campaigns"

{  "data": [    {      "id": "string",      "name": "string",      "type": "string",      "is_paused": true,      "status": "string"    }  ],  "next_cursor": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Create a campaign

POST/v1/campaigns

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: create_campaign.

Create a campaign draft with a trigger, messages and optional timing and discount settings. Use get_campaign_composer_options to choose supported options. New campaigns are paused; review them with the user, then turn one on with set_campaign_status (needs explicit confirmation) or in the vyg.ai app.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Optional campaign name. When omitted, an incremental name is generated (e.g. "Checkout Abandoned 1").

trigger_event*string

The trigger event id. Predefined: checkout/abandoned, order/delivered (Order Placed). Or a brand custom-event slug. An unknown value is rejected with the list of valid options for this brand.

wait?|

Optional delay between the trigger and the first action. Suggested starting point: 30 minutes when no delay has been specified. For orders, this delays new orders received after campaign activation. Use trigger_delay to include earlier qualifying orders.

trigger_delay?|

Optional delay from an order or subscription event before a campaign starts. For example, { amount: 15, unit: "days" } can include qualifying orders placed 15 days before activation. A wait step instead delays events received after activation. Checkout and custom-event triggers require wait rather than trigger_delay.

action_type*string

"agent" = a two-way conversation handled by a real human live agent (initial + live-agent reply). "sms" = a single one-way SMS.

initial_message?string

agent only: the first outbound message template. Required when action_type is "agent". Include opt-out language, such as "Reply STOP to opt out." (a first message without it is rejected).

agent_reply_message?string

Reply text sent to the customer by a live agent, not instructions for the agent. Required for action_type "agent". Checkout campaigns require ${event.abandoned_checkout_url}. Use ${generated.discount_code} only when a discount is attached, and describe its configured validity period. Omit the checkout link for other triggers.

sms_message?string

sms only: the one-way SMS body template. Required when action_type is "sms". Include opt-out language, such as "Reply STOP to opt out." (rejected without it).

split?|

Optional A/B split that sends each contact down one of two weighted paths. Supply messages on each branch and omit top-level message fields. Both branches use the same action_type and their weights must sum to 100. For alternative copy within a single message, use add_message_variant.

discount_rule_id?|

ID of an existing rule from your discount library to attach to the campaign.

cart_link?|

agent only: the Live Agent step's Cart Link setting — what ${generated.cart_link} resolves to in the messages. DEFAULT on an order/delivered agent campaign: { type: "previous_order" } (the flow builder's default), so a post-purchase draft always carries a cart link. Pass { type: "url", url } for a fixed link. Pass null to create the step with NO cart link. Not applicable to sms campaigns or checkout triggers (their cart link is the checkout recovery link, ${event.abandoned_checkout_url}). "Specific items" carts are set in the flow builder.

filters?array<>|

Optional audience filters; all conditions must match. Each { field, operator, value } must use options returned by get_campaign_composer_options for this trigger_event. Invalid filters reject the request. Omit for an untargeted campaign.

Response Body

`application/json`

curl -X POST "https://example.com/v1/campaigns" \  -H "Content-Type: application/json" \  -d '{    "trigger_event": "string",    "action_type": "agent"  }'

{  "id": "string",  "status": "string",  "is_paused": true,  "note": "string",  "name": "string",  "type": "string",  "trigger": {    "kind": "string",    "event": "string",    "label": "string"  },  "wait": {    "amount": 0,    "unit": "string"  },  "trigger_delay": {    "amount": 0,    "unit": "string",    "minutes": 0  },  "action_type": "string",  "cart_link": {    "type": "string",    "url": "string"  },  "discount": {    "id": "string"  },  "editor_url": "string",  "starts_at": "string",  "ends_at": "string",  "draft": true,  "messages": {    "initial": "string",    "agent_reply": "string",    "sms": "string"  },  "split": {    "branches": [      {        "name": "string",        "weight": 0,        "messages": {          "initial": "string",          "agent_reply": "string",          "sms": "string"        }      }    ]  },  "variables": [    {      "token": "string",      "label": "string",      "hint": "string"    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Compare campaigns

GET/v1/campaigns/compare

Scope: campaigns:read. MCP tool: compare_campaigns.

Compare campaign performance side by side. Omit campaign_ids to compare active campaigns. Pass campaign_ids and stats as repeated or comma-separated query parameters.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

campaign_ids?array<string>

stats?array<string>

from?string

to?string

timezone?string

Response Body

`application/json`

curl -X GET "https://example.com/v1/campaigns/compare"

{  "brand_id": "string",  "date_range": {    "from": "string",    "to": "string"  },  "stats": [    "string"  ],  "campaigns": [    {      "id": "string",      "name": "string",      "type": "string",      "status": "string",      "is_paused": true,      "stats": [        {          "name": "string",          "title": "string",          "current_value": "string",          "previous_value": "string",          "progress": 0        }      ],      "errors": [        "string"      ]    }  ],  "errors": [    "string"  ],  "notes": [    "string"  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Campaign building options

GET/v1/campaigns/composer-options

Scope: one of campaigns:read, campaigns:write. MCP tool: get_campaign_composer_options.

View the triggers, discounts, message variables and audience filters available for a campaign. Use these options when creating a draft.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

trigger_event?string

Response Body

`application/json`

curl -X GET "https://example.com/v1/campaigns/composer-options"

{  "trigger_events": {    "predefined": [      {        "id": "string",        "label": "string"      }    ],    "custom": [      {        "slug": "string",        "label": "string",        "provider_id": "string",        "provider": "string"      }    ]  },  "discount_rules": [    {      "id": "string",      "name": "string",      "type": "string",      "value": "string",      "minimum": {        "type": "string",        "value": 0      },      "duration_days": 0,      "is_static": true    }  ],  "message_variables": {    "max_length": 0,    "namespaces": [      {        "namespace": "string",        "usage": "string",        "examples": [          "string"        ]      }    ],    "note": "string"  },  "message_rules": {    "rules": [      "string"    ],    "opt_out_example": "string",    "agent_reply_example": "string",    "agent_reply_example_note": "string",    "checkout_url_token": "string",    "checkout_trigger_events": [      "string"    ],    "default_wait_minutes": 0  },  "message_variants": {    "explainer": "string",    "tools": [      "string"    ],    "note": "string"  },  "filters": {    "trigger_event": "string",    "fields": [      {        "field": "string",        "fact": "string",        "path": "string",        "label": "string",        "group": "string",        "description": "string",        "value_type": "number",        "operators": [          {            "operator": "string",            "label": "string"          }        ],        "values": [          {            "label": "string",            "value": "string"          }        ],        "values_are_open": true      }    ],    "note": "string"  },  "note": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Campaign setup

GET/v1/campaigns/{campaign_id}

Scope: campaigns:read. MCP tool: get_campaign.

View a campaign’s trigger, timing, messages and status. Use an ID from list_campaigns.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/campaigns/string"

{  "id": "string",  "name": "string",  "type": "string",  "is_paused": true,  "status": "string",  "starts_at": "string",  "ends_at": "string",  "delay_minutes": 0,  "wait": {    "amount": 0,    "unit": "string",    "minutes": 0,    "delay_type": "string",    "week_days": [      "string"    ],    "specific_time": "string"  },  "waits": [    {      "node_id": "string",      "amount": 0,      "unit": "string",      "minutes": 0,      "delay_type": "string",      "week_days": [        "string"      ],      "specific_time": "string"    }  ],  "goal": null,  "action": {    "type": "string",    "discount": {      "type": "string",      "value": "string",      "duration": "string",      "id": "string",      "name": "string"    },    "discounts": [      {        "node_id": "string",        "external_id": "string",        "discount": {          "type": "string",          "value": "string",          "duration": "string",          "id": "string",          "name": "string"        }      }    ],    "agent_reply": {      "reply_with_message": true,      "contact_support": true,      "support_email": "string"    }  },  "messages": [    {      "type": "string",      "template": "string"    }  ],  "flow_messages": [    {      "id": "string",      "node_id": "string",      "step_id": "string",      "type": "string",      "template": "string",      "cart": {        "type": "string",        "url": "string",        "rules": [          null        ]      }    }  ],  "steps": [    {      "id": "string",      "type": "string",      "next": [        {          "id": "string",          "branch": "string"        }      ],      "wait": {        "amount": 0,        "unit": "string"      },      "split": {        "branches": [          {            "name": "string",            "weight": 0          }        ]      },      "re_entry": {        "type": "string",        "amount": 0,        "unit": "string"      }    }  ],  "knowledge_base": [    {      "id": "string",      "title": "string",      "content": "string"    }  ],  "filters": [    {      "id": "string",      "filter": {        "id": "string",        "name": "string",        "rule": null      }    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Rename a campaign

PATCH/v1/campaigns/{campaign_id}

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: rename_campaign.

Rename a campaign draft. The campaign stays paused.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

The campaign id to rename — from list_campaigns.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

The new campaign name.

confirm_live_change?boolean

Set to true only after the user confirmed this change to a LIVE campaign. Without it, edits to a live campaign are refused. Not needed for paused drafts.

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/campaigns/string" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "id": "string",  "status": "string",  "is_paused": true,  "note": "string",  "name": "string",  "previous_name": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Campaign run activity

GET/v1/campaigns/{campaign_id}/activity

Scope: campaigns:read. MCP tool: list_campaign_activity.

One campaign's run activity, newest first: every event that entered it, each step it ran or skipped (with the skip reason, such as a filter, the re-entry limit, quiet hours or holdout), failures, and the conversation each run produced, plus counts by step state and skip reason for the window. Defaults to the last 24 hours; at most 7 days. Longer windows on a busy campaign are slower. Filter with state (e.g. filtered_out to see who was skipped and why).

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Query Parameters

state?array<>

from?string

Start of the window (ISO 8601). Default: 24 hours before to.

to?string

End of the window (ISO 8601). Default: now.

limit?integer

cursor?string

Response Body

`application/json`

curl -X GET "https://example.com/v1/campaigns/string/activity"

{  "data": [    {      "at": "string",      "state": "string",      "step": "string",      "step_id": "string",      "event_type": "string",      "event_id": "string",      "campaign_id": "string",      "campaign_name": "string",      "conversation_id": "string",      "contact_id": "string",      "reason": {        "code": "string",        "label": "string",        "level": "string",        "rule": "string"      },      "error": "string",      "recovered": true    }  ],  "next_cursor": "string",  "summary": [    {      "state": "string",      "reason": {        "code": "string",        "label": "string",        "level": "string",        "rule": "string"      },      "count": 0    }  ],  "window": {    "from": "string",    "to": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Change campaign dates

PUT/v1/campaigns/{campaign_id}/schedule

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: update_campaign_schedule.

Change the start or end date of a campaign draft. Use ISO 8601 dates, null to clear a date, or omit it to keep the current value. The end date must follow the start date.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

The campaign id to reschedule — from list_campaigns.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

starts_at?|

ISO-8601 date-time the campaign should start (e.g. 2026-01-15T09:00:00Z). Pass null to clear the start. Omit to leave it unchanged.

ends_at?|

ISO-8601 date-time the campaign should end. Must be after starts_at. Pass null to clear the end. Omit to leave it unchanged.

confirm_live_change?boolean

Set to true only after the user confirmed this change to a LIVE campaign. Without it, edits to a live campaign are refused. Not needed for paused drafts.

Response Body

`application/json`

curl -X PUT "https://example.com/v1/campaigns/string/schedule" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "status": "string",  "is_paused": true,  "note": "string",  "name": "string",  "starts_at": "string",  "ends_at": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Edit campaign messages

PUT/v1/campaigns/{campaign_id}/messages

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: update_campaign_messages.

Edit the main messages in a campaign draft. Messages must follow your message rules. Variants are unchanged.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

The campaign id whose messages to edit — from list_campaigns.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

initial_message?

agent campaigns: replace the first outbound (initial) message. Retain opt-out language, such as "Reply STOP to opt out." (rejected without it).

agent_reply_message?

Replacement reply text sent to the customer by a live agent. Checkout campaigns require ${event.abandoned_checkout_url}. Use ${generated.discount_code} only when a discount is attached, with its configured validity period. Omit the checkout link for other triggers.

sms_message?

sms campaigns: replace the one-way SMS body. Retain opt-out language, such as "Reply STOP to opt out." (rejected without it).

confirm_live_change?boolean

Set to true only after the user confirmed this change to a LIVE campaign. Without it, edits to a live campaign are refused. Not needed for paused drafts.

Response Body

`application/json`

curl -X PUT "https://example.com/v1/campaigns/string/messages" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "status": "string",  "is_paused": true,  "note": "string",  "name": "string",  "updated_messages": [    {      "target": "string",      "preview": "string"    }  ],  "discount_rule_id": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Change a campaign

PATCH/v1/campaigns/{campaign_id}/flow

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: update_campaign.

Change a campaign’s steps (waits, split weights, re-entry, added or removed text and AI agent steps), the text of any step, or its holdout group, and update the running flow to match. Read step ids with get_campaign first. A live campaign needs confirm_live_change after the user agrees.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

The campaign to change, from list_campaigns.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

steps?array<||||>

Changes to the campaign steps, applied in order. Read the step ids with get_campaign first.

messages?array<>

New message text for existing steps. Same rules as create_campaign. Text for a step added in this call goes in its add_step instead.

holdout?

The holdout group: customers held back from the campaign to measure its effect.

republish?boolean

Push the saved steps to the running flow again without other changes. Use after a result reported that the running flow was not updated.

confirm_live_change?boolean

Set to true only after the user confirmed this change to a LIVE campaign. Without it, edits to a live campaign are refused. Not needed for paused drafts.

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/campaigns/string/flow" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "status": "string",  "is_paused": true,  "note": "string",  "name": "string",  "changes": [    "string"  ],  "updated_messages": [    {      "target": "string",      "preview": "string"    }  ],  "holdout": {    "enabled": true,    "percentage": 0,    "enabled_at": "string"  },  "published": true,  "steps": [    {      "id": "string",      "type": "string",      "next": [        {          "id": "string",          "branch": "string"        }      ],      "wait": {        "amount": 0,        "unit": "string"      },      "split": {        "branches": [          {            "name": "string",            "weight": 0          }        ]      },      "re_entry": {        "type": "string",        "amount": 0,        "unit": "string"      }    }  ],  "warning": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Turn a campaign on or off

POST/v1/campaigns/{campaign_id}/status

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: set_campaign_status.

Turn a campaign on (active) or off (paused). Turning it on texts real customers, so it needs confirm_activation after the user agrees.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

The campaign to turn on or off, from list_campaigns.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status*string

active turns the campaign on; paused turns it off.

confirm_activation?boolean

Required (true) to turn a campaign on, after the user confirmed: an active campaign starts texting real customers.

Response Body

`application/json`

curl -X POST "https://example.com/v1/campaigns/string/status" \  -H "Content-Type: application/json" \  -d '{    "status": "active"  }'

{  "id": "string",  "name": "string",  "status": "string",  "is_paused": true,  "changed": true,  "previous": {    "status": "string",    "is_paused": true  },  "warning": "string",  "note": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Message variants

GET/v1/campaigns/{campaign_id}/variants

Scope: campaigns:read. MCP tool: list_message_variants.

View a campaign’s message alternatives and current test.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

Query Parameters

node_external_id?string

Response Body

`application/json`

curl -X GET "https://example.com/v1/campaigns/string/variants"

{  "campaign_id": "string",  "node_external_id": "string",  "arms": [    {      "id": "string",      "variant_id": "string",      "message_type": "string",      "template": "string",      "status": "string",      "current_weight": "string",      "updated_at": "string"    }  ],  "running_test": {    "id": "string",    "auto_optimize": true,    "winner_variant_id": "string",    "ended_at": "string",    "updated_at": "string"  },  "variants_send_live": true,  "note": "string",  "explainer": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Add a message variant

POST/v1/campaigns/{campaign_id}/variants

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: add_message_variant.

Add alternative wording for a campaign message. The first alternative starts a test using the existing message as the control. Changes can affect future sends on active campaigns when variant sending is enabled. Message rules still apply.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

The campaign id, e.g. from list_campaigns.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

message_type*string

Which message slot the variant belongs to: "initial" = the first outbound message (SMS campaigns use "initial" too), "agent" = the live-agent reply, "email" = an email-node arm pointing at a live email_templates row via email_template_id.

template?string

The variant copy (SMS) or subject/label snapshot (email). Required for initial/agent; for email defaults to email_template_id when omitted. SMS copy follows get_campaign_composer_options.message_rules — opt-out language on first messages, ${namespace.field} variables only.

email_template_id?string

Required when message_type is "email": the live email_templates.id this arm should send. Ignored for SMS slots.

control_email_template_id?string

Email only — the node's current live template id, used to seed the control arm on the first add. Required when no email control arm exists yet.

control_template_label?string

Email only — optional subject/label snapshot for the seeded control arm.

variant_id?string

Optional stable id for the new arm ("control" is reserved). Omit to auto-generate.

node_external_id?string

Only needed on branched campaigns with MULTIPLE message nodes: the action node's external id (the tool lists the options when ambiguous). Omit for the usual single-message campaign.

Response Body

`application/json`

curl -X POST "https://example.com/v1/campaigns/string/variants" \  -H "Content-Type: application/json" \  -d '{    "message_type": "initial"  }'

{  "ok": true,  "action": "string",  "test_id": "string",  "test_updated_at": "string",  "auto_optimize": true,  "arm": {    "id": "string",    "variant_id": "string",    "status": "string",    "template": "string",    "current_weight": 0,    "message_type": "string"  },  "arms": [    {      "id": "string",      "variant_id": "string",      "status": "string",      "template": "string",      "current_weight": 0,      "message_type": "string"    }  ],  "campaign_id": "string",  "node_external_id": "string",  "variants_send_live": true,  "note": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Update a message variant

PATCH/v1/campaigns/{campaign_id}/variants/{variant_id}

Requires sign-in (OAuth). Scope: campaigns:write. MCP tool: update_message_variant.

Edit wording in a running message test. Use a variant_id from list_message_variants, or control to edit the original version in the test. Changes can affect future sends on active campaigns when variant sending is enabled.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

campaign_id*string

The campaign id, e.g. from list_campaigns.

variant_id*string

The arm to edit — a variant_id from list_message_variants. "control" edits the RUNNING test's stored control snapshot (what the test actually sends); the base template itself is edited with update_campaign_messages.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

message_type*string

template?string

The replacement copy (SMS) or subject/label snapshot (email). Required for initial/agent; for email defaults to email_template_id when omitted.

email_template_id?string

Required when message_type is "email": the live email_templates.id this arm should send. Ignored for SMS slots.

node_external_id?string

Only needed on branched campaigns with MULTIPLE message nodes: the action node's external id (the tool lists the options when ambiguous). Omit for the usual single-message campaign.

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/campaigns/string/variants/string" \  -H "Content-Type: application/json" \  -d '{    "message_type": "initial"  }'

{  "ok": true,  "action": "string",  "test_id": "string",  "test_updated_at": "string",  "auto_optimize": true,  "arm": {    "id": "string",    "variant_id": "string",    "status": "string",    "template": "string",    "current_weight": 0,    "message_type": "string"  },  "arms": [    {      "id": "string",      "variant_id": "string",      "status": "string",      "template": "string",      "current_weight": 0,      "message_type": "string"    }  ],  "campaign_id": "string",  "node_external_id": "string",  "variants_send_live": true,  "note": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`