Loops OpenAPI Spec

API key

Audience segments

View audience segments

Get an audience segment

GET /v1/audience-segments/{audienceSegmentId}

Requires apiKey — bearer

Retrieve a single audience segment by ID.

Path parameters

audienceSegmentId string

The ID of the audience segment.

Responses

200 400 401 404 405

Successful.

AudienceSegmentResponseused by 2 operations

id string

The ID of the audience segment.

name string

The name of the audience segment.

description string

nullable

An optional description of the audience segment.

createdAt string

ISO 8601 timestamp for when the audience segment was created.

updatedAt string

ISO 8601 timestamp for when the audience segment was last updated.

filter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

Invalid audienceSegmentId.

AudienceSegmentFailureResponseused by 3 operations

message string

Invalid API key or content API not enabled for this team.

Audience segment not found.

AudienceSegmentFailureResponseused by 3 operations

message string

Wrong HTTP request method.

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Contacts on the pro plan",
  "filter": {
    "conditions": [
      {
        "key": "plan",
        "operator": "equals",
        "type": "property",
        "value": "pro"
      }
    ],
    "match": "all"
  },
  "id": "cls6e8g0i2k4m6o8q0s2u4w6",
  "name": "Power users",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Audience segment not found."
}

404 Response

{
  "message": "Audience segment not found."
}

List audience segments

GET /v1/audience-segments

Requires apiKey — bearer

Retrieve a paginated list of audience segments, most recently created first.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListAudienceSegmentsResponse

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of AudienceSegment

1 field

items AudienceSegment

6 fields

id string

The ID of the audience segment.

name string

The name of the audience segment.

description string

nullable

An optional description of the audience segment.

createdAt string

ISO 8601 timestamp for when the audience segment was created.

updatedAt string

ISO 8601 timestamp for when the audience segment was last updated.

filter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

Invalid perPage value.

AudienceSegmentFailureResponseused by 3 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "createdAt": "2025-06-29T07:47:39.370Z",
      "description": "Contacts on the pro plan",
      "filter": {
        "conditions": [
          {
            "key": "plan",
            "operator": "equals",
            "type": "property",
            "value": "pro"
          }
        ],
        "match": "all"
      },
      "id": "cls6e8g0i2k4m6o8q0s2u4w6",
      "name": "Power users",
      "updatedAt": "2025-06-29T07:47:39.370Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

400 Response

{
  "message": "Audience segment not found."
}

Create an audience segment

POST /v1/audience-segments

Requires apiKey — bearer

Create a new audience segment.

Request body CreateAudienceSegmentRequest

name string

The name of the audience segment. Must be unique within the team.

rules max length 255

description string

An optional description of the audience segment.

rules max length 1000

filter object

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

Responses

200 400 401 404 405

Audience segment created.

AudienceSegmentResponseused by 2 operations

id string

The ID of the audience segment.

name string

The name of the audience segment.

description string

nullable

An optional description of the audience segment.

createdAt string

ISO 8601 timestamp for when the audience segment was created.

updatedAt string

ISO 8601 timestamp for when the audience segment was last updated.

filter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

Invalid request body, a name already used by another segment, or a filter with too many conditions.

AudienceSegmentFailureResponseused by 3 operations

message string

Invalid API key or content API not enabled for this team.

The filter references a campaign, workflow or workflow email that does not exist.

AudienceSegmentFailureResponseused by 3 operations

message string

Wrong HTTP request method.

POST /v1/audience-segments

{
  "name": "Active users",
  "description": "string",
  "filter": {
    "match": "all",
    "conditions": [
      {
        "type": "property",
        "key": "plan",
        "operator": "equals",
        "value": "pro"
      }
    ]
  }
}

Example generated from the schema

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Contacts on the pro plan",
  "filter": {
    "conditions": [
      {
        "key": "plan",
        "operator": "equals",
        "type": "property",
        "value": "pro"
      }
    ],
    "match": "all"
  },
  "id": "cls6e8g0i2k4m6o8q0s2u4w6",
  "name": "Power users",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Audience segment not found."
}

404 Response

{
  "message": "Audience segment not found."
}

Campaigns

Create and manage email campaigns

List campaigns

GET /v1/campaigns

Requires apiKey — bearer

Retrieve a paginated list of campaigns.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListCampaignsResponse

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of CampaignResponse

1 field

items CampaignResponse

12 fields

id string

The ID of the campaign.

url string · uri

The URL of the campaign in the Loops app.

name string

The name of the campaign.

status string

The status of the campaign.

enum DraftScheduledSendingSent

createdAt string · date-time

ISO 8601 timestamp for when the campaign was created.

updatedAt string · date-time

ISO 8601 timestamp for when the campaign was last updated.

emailMessageId string

nullable

The associated email message ID.

campaignGroupId string

nullable

The ID of the campaign group this campaign belongs to.

mailingListId string

nullable

The ID of the mailing list this campaign sends to, if set.

audienceSegmentId string

nullable

The ID of the audience segment this campaign targets, if set.

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

scheduling CampaignScheduling

When the campaign is scheduled to send.

2 fields

method string

enum nowschedule

timestamp string · date-time

nullable

ISO 8601 send time. Null when the method is now.

Invalid perPage value.

CampaignFailureResponseused by 5 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "audienceFilter": null,
      "audienceSegmentId": null,
      "campaignGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
      "createdAt": "2025-06-29T07:47:39.370Z",
      "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
      "id": "clc4m6n8p0q2r4s6t8u0v2x4",
      "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
      "name": "Spring announcement",
      "scheduling": {
        "method": "now",
        "timestamp": null
      },
      "status": "Draft",
      "updatedAt": "2025-06-29T07:47:39.370Z",
      "url": "https://app.loops.so/campaigns/clc4m6n8p0q2r4s6t8u0v2x4"
    }
  ],
  "pagination": {
    "nextCursor": "clp9k2m4n6p8q0r2s4t6u8v0",
    "nextPage": "https://app.loops.so/api/v1/campaigns?cursor=clp9k2m4n6p8q0r2s4t6u8v0&perPage=20",
    "perPage": 20,
    "returnedResults": 20,
    "totalPages": 3,
    "totalResults": 45
  }
}

400 Response

{
  "message": "Campaign not found."
}

Create a campaign

POST /v1/campaigns

Requires apiKey — bearer

Create a new draft campaign. An empty email message is created automatically and its emailMessageId is returned. Use the /email-messages/{emailMessageId} endpoint to set subject, sender, preview text, and LMX content. The audience (mailing list, segment, or filter), group, and scheduling can be set on create or later via update.

Request body CreateCampaignRequest

name string

The campaign name.

campaignGroupId string

The ID of the group to add this campaign to. Defaults to the team's Unsorted group when omitted.

mailingListId string

nullable

The ID of the mailing list to send to.

audienceSegmentId string

nullable

The ID of an audience segment. Setting this without also providing audienceFilter clears any existing audienceFilter. If both are provided, the filter is applied on top of the segment's filter.

audienceFilter AudienceFilterInRequest

nullable

A tree of audience conditions combined with match. Setting this without also providing audienceSegmentId clears any existing audienceSegmentId. When both are provided, this filter is applied on top of the segment's filter.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

scheduling CampaignSchedulingRequest

When the campaign should send. timestamp is required and must be in the future when method is schedule, and must be omitted when method is now.

2 fields

method string

enum nowschedule

timestamp string · date-time

Responses

201 400 401 404 405

Campaign created.

CreateCampaignResponse

id string

The ID of the campaign.

url string · uri

The URL of the campaign in the Loops app.

name string

The name of the campaign.

status string

The status of the campaign (always Draft for new campaigns).

enum Draft

createdAt string · date-time

ISO 8601 timestamp for when the campaign was created.

updatedAt string · date-time

ISO 8601 timestamp for when the campaign was last updated.

emailMessageId string

nullable

The ID of the empty email message created for this campaign. Use POST /v1/email-messages/{emailMessageId} to set its fields and LMX content.

emailMessageContentRevisionId string

nullable

The contentRevisionId of the newly created email message. Pass this as expectedRevisionId on your first update.

campaignGroupId string

nullable

The ID of the campaign group this campaign belongs to, if set.

mailingListId string

nullable

The ID of the mailing list this campaign sends to, if set.

audienceSegmentId string

nullable

The ID of the audience segment this campaign targets, if set.

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

scheduling CampaignScheduling

When the campaign is scheduled to send.

Invalid request body, campaign group not found, or no sending domain configured.

CampaignFailureResponseused by 5 operations

message string

Invalid API key or content API not enabled for this team.

Referenced mailing list or audience segment not found.

CampaignFailureResponseused by 5 operations

message string

Wrong HTTP request method.

POST /v1/campaigns

{
  "name": "Spring announcement",
  "campaignGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "audienceSegmentId": "cls6e8g0i2k4m6o8q0s2u4w6",
  "audienceFilter": {
    "match": "all",
    "conditions": [
      {
        "type": "property",
        "key": "plan",
        "operator": "equals",
        "value": "pro"
      }
    ]
  },
  "scheduling": {
    "method": "schedule",
    "timestamp": "2025-07-15T14:00:00.000Z"
  }
}

Example generated from the schema

201 Response

{
  "audienceFilter": null,
  "audienceSegmentId": null,
  "campaignGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "createdAt": "2025-06-29T07:47:39.370Z",
  "emailMessageContentRevisionId": "clrev1s10n2i3d4e5f6g7h8",
  "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "clc4m6n8p0q2r4s6t8u0v2x4",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "name": "Spring announcement",
  "scheduling": {
    "method": "now",
    "timestamp": null
  },
  "status": "Draft",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/campaigns/clc4m6n8p0q2r4s6t8u0v2x4"
}

400 Response

{
  "message": "Campaign not found."
}

404 Response

{
  "message": "Campaign not found."
}

Get a campaign

GET /v1/campaigns/{campaignId}

Requires apiKey — bearer

Retrieve a single campaign by ID.

Path parameters

campaignId string

The ID of the campaign.

Responses

200 400 401 404 405

Successful.

CampaignResponseused by 3 operations

id string

The ID of the campaign.

url string · uri

The URL of the campaign in the Loops app.

name string

The name of the campaign.

status string

The status of the campaign.

enum DraftScheduledSendingSent

createdAt string · date-time

ISO 8601 timestamp for when the campaign was created.

updatedAt string · date-time

ISO 8601 timestamp for when the campaign was last updated.

emailMessageId string

nullable

The associated email message ID.

campaignGroupId string

nullable

The ID of the campaign group this campaign belongs to.

mailingListId string

nullable

The ID of the mailing list this campaign sends to, if set.

audienceSegmentId string

nullable

The ID of the audience segment this campaign targets, if set.

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

scheduling CampaignScheduling

When the campaign is scheduled to send.

Invalid campaignId.

CampaignFailureResponseused by 5 operations

message string

Invalid API key or content API not enabled for this team.

Campaign not found.

CampaignFailureResponseused by 5 operations

message string

Wrong HTTP request method.

200 Response

{
  "audienceFilter": null,
  "audienceSegmentId": null,
  "campaignGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "createdAt": "2025-06-29T07:47:39.370Z",
  "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "clc4m6n8p0q2r4s6t8u0v2x4",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "name": "Spring announcement",
  "scheduling": {
    "method": "now",
    "timestamp": null
  },
  "status": "Draft",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/campaigns/clc4m6n8p0q2r4s6t8u0v2x4"
}

400 Response

{
  "message": "Campaign not found."
}

404 Response

{
  "message": "Campaign not found."
}

Update a campaign

POST /v1/campaigns/{campaignId}

Requires apiKey — bearer

Update a draft campaign's name, group, audience (mailing list, segment, or filter), or scheduling. At least one field must be provided. Once a campaign has been sent, only its name and campaignGroupId can be updated.

Path parameters

campaignId string

The ID of the campaign.

Request body UpdateCampaignRequest

At least one field must be provided.

name string

The updated campaign name.

campaignGroupId string

The ID of the group to move this campaign to.

mailingListId string

nullable

The ID of the mailing list to send to.

audienceSegmentId string

nullable

The ID of an audience segment. Setting this without also providing audienceFilter clears any existing audienceFilter. If both are provided, the filter is applied on top of the segment's filter.

audienceFilter AudienceFilterInRequest

nullable

A tree of audience conditions combined with match. Setting this without also providing audienceSegmentId clears any existing audienceSegmentId. When both are provided, this filter is applied on top of the segment's filter.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

scheduling CampaignSchedulingRequest

When the campaign should send. timestamp is required and must be in the future when method is schedule, and must be omitted when method is now.

2 fields

method string

enum nowschedule

timestamp string · date-time

Responses

200 400 401 404 405 409

Campaign updated.

CampaignResponseused by 3 operations

id string

The ID of the campaign.

url string · uri

The URL of the campaign in the Loops app.

name string

The name of the campaign.

status string

The status of the campaign.

enum DraftScheduledSendingSent

createdAt string · date-time

ISO 8601 timestamp for when the campaign was created.

updatedAt string · date-time

ISO 8601 timestamp for when the campaign was last updated.

emailMessageId string

nullable

The associated email message ID.

campaignGroupId string

nullable

The ID of the campaign group this campaign belongs to.

mailingListId string

nullable

The ID of the mailing list this campaign sends to, if set.

audienceSegmentId string

nullable

The ID of the audience segment this campaign targets, if set.

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

scheduling CampaignScheduling

When the campaign is scheduled to send.

Invalid request body or campaign group not found.

CampaignFailureResponseused by 5 operations

message string

Invalid API key or content API not enabled for this team.

Campaign, mailing list, or audience segment not found.

CampaignFailureResponseused by 5 operations

message string

Wrong HTTP request method.

Campaign has been sent and the request updates a field other than name or campaignGroupId.

CampaignFailureResponseused by 5 operations

message string

POST /v1/campaigns/{campaignId}

{
  "name": "Spring announcement",
  "campaignGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "audienceSegmentId": "cls6e8g0i2k4m6o8q0s2u4w6",
  "audienceFilter": {
    "match": "all",
    "conditions": [
      {
        "type": "property",
        "key": "plan",
        "operator": "equals",
        "value": "pro"
      }
    ]
  },
  "scheduling": {
    "method": "schedule",
    "timestamp": "2025-07-15T14:00:00.000Z"
  }
}

Example generated from the schema

200 Response

{
  "audienceFilter": null,
  "audienceSegmentId": null,
  "campaignGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "createdAt": "2025-06-29T07:47:39.370Z",
  "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "clc4m6n8p0q2r4s6t8u0v2x4",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "name": "Spring announcement",
  "scheduling": {
    "method": "now",
    "timestamp": null
  },
  "status": "Draft",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/campaigns/clc4m6n8p0q2r4s6t8u0v2x4"
}

400 Response

{
  "message": "Campaign not found."
}

404 Response

{
  "message": "Campaign not found."
}

409 Response

{
  "message": "Campaign not found."
}

Get campaign metrics

GET /v1/campaigns/{campaignId}/metrics

Requires apiKey — bearer

Retrieve all-time email engagement metrics for a campaign.

Path parameters

campaignId string

The ID of the campaign.

Responses

200 400 401 404 405

Successful.

EmailMetricsResponseused by 2 operations

All-time email engagement counters. Opens and clicks count sends, not events: a send opened five times counts once. A recipient who received the email twice is counted once per send, not once per person.

sends integer

Number of sends.

opens integer

Number of sends that were opened at least once.

clicks integer

Number of sends where at least one link was clicked.

unsubscribes integer

Number of unsubscribes.

spamReports integer

Number of sends reported as spam.

hardBounces integer

Number of sends that hard bounced.

softBounces integer

Number of sends that soft bounced.

Invalid campaignId, the campaign has not been sent yet, or the campaign has no email message.

CampaignFailureResponseused by 5 operations

message string

Invalid API key.

Campaign not found.

CampaignFailureResponseused by 5 operations

message string

Wrong HTTP request method.

200 Response

{
  "clicks": 301,
  "hardBounces": 9,
  "opens": 1922,
  "sends": 4210,
  "softBounces": 13,
  "spamReports": 1,
  "unsubscribes": 12
}

400 Response

{
  "message": "Campaign not found."
}

404 Response

{
  "message": "Campaign not found."
}

Campaign groups

Organize campaigns into groups

List campaign groups

GET /v1/campaign-groups

Requires apiKey — bearer

Retrieve a paginated list of campaign groups, most recently created first.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListGroupsResponseused by 3 operations

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of GroupResponse

1 field

items GroupResponse

5 fields

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid perPage value.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "createdAt": "2025-06-29T07:47:39.370Z",
      "description": "Top of funnel campaigns",
      "id": "clg7n5p3q1r9s7t5u3v1w9y7",
      "name": "Onboarding",
      "updatedAt": "2025-06-29T07:47:39.370Z"
    },
    {
      "createdAt": "2025-06-30T12:00:00.000Z",
      "description": "",
      "id": "clg8m4n6p8q0r2s4t6u8v0w2",
      "name": "Retention",
      "updatedAt": "2025-06-30T12:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

400 Response

{
  "message": "Group not found."
}

Create a campaign group

POST /v1/campaign-groups

Requires apiKey — bearer

Create a new campaign group.

Request body CreateGroupRequestused by 3 operations

name string

The group name. Cannot be the reserved name "Unsorted".

description string

An optional description for the group.

Responses

200 400 401 405

Campaign group created.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid request body or reserved group name.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

POST /v1/campaign-groups

{
  "description": "Monthly newsletter campaigns",
  "name": "Newsletters"
}

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

Get a campaign group

GET /v1/campaign-groups/{campaignGroupId}

Requires apiKey — bearer

Retrieve a single campaign group by ID.

Path parameters

campaignGroupId string

The ID of the campaign group.

Responses

200 400 401 404 405

Successful.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid campaignGroupId.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Campaign group not found.

GroupFailureResponseused by 12 operations

message string

Wrong HTTP request method.

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

404 Response

{
  "message": "Group not found."
}

Update a campaign group

POST /v1/campaign-groups/{campaignGroupId}

Requires apiKey — bearer

Update a campaign group's name or description. At least one field must be provided. The reserved "Unsorted" group cannot be edited.

Path parameters

campaignGroupId string

The ID of the campaign group.

Request body UpdateGroupRequestused by 3 operations

At least one field must be provided.

name string

The group name. Cannot be the reserved name "Unsorted".

description string

A description for the group.

Responses

200 400 401 404 405

Campaign group updated.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid request body, reserved group name, or the Unsorted group cannot be edited.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Campaign group not found.

GroupFailureResponseused by 12 operations

message string

Wrong HTTP request method.

POST /v1/campaign-groups/{campaignGroupId}

{
  "name": "string",
  "description": "string"
}

Example generated from the schema

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

404 Response

{
  "message": "Group not found."
}

Configuration

View configuration settings

List dedicated sending IP addresses

GET /v1/dedicated-sending-ips

Requires apiKey — bearer

Retrieve a list of Loops' dedicated sending IP addresses.

This endpoint is provided for the rare instances where you may need to whitelist our sending IPs. Please note that this list is subject to change and will not include shared IPs used for sending mail.

Unless you are sure you need this and are comfortable watching for changes, we strongly recommend you do not whitelist these IPs.

Responses

200 405

Successful.

Returns an array of IP address strings.

items string

IP address

Wrong HTTP request method.

Contacts

Manage contacts in your audience

Create a contact

POST /v1/contacts/create

Requires apiKey — bearer

Add a contact to your audience.

Request body ContactRequest

You can add custom contact properties as keys in this request (of type string, number, boolean or date. See available date formats). Make sure to create the properties in Loops before using them in API calls.

email string

The contact's email address.

firstName string

The contact's first name.

lastName string

The contact's last name.

source string

A custom source value to replace the default “API”.

subscribed boolean

Whether the contact will receive campaign and workflow emails. All new contacts are subscribed by default.

userGroup string

The contact's user group.

userId string

A unique user ID (for example, from an external application).

mailingLists MailingListSubscriptions

Manage mailing list subscriptions.

Include key-value pairs of mailing list IDs and a boolean denoting if the contact should be added (true) or removed (false) from the list.

all of object

Responses

200 400 405 409

Successful create.

ContactSuccessResponseused by 2 operations

success boolean

id string

Bad request (e.g. invalid email address).

ContactFailureResponseused by 6 operations

success boolean

message string

Wrong HTTP request method.

Email or userId already exists.

ContactFailureResponseused by 6 operations

success boolean

message string

POST /v1/contacts/create

{
  "email": "alex@company.com",
  "firstName": "Alex",
  "lastName": "Rivera",
  "source": "API",
  "subscribed": false,
  "userGroup": "customers",
  "userId": "usr_7f8e9d0c1b2a",
  "mailingLists": {
    "cm06f5v0e45nf0ml5754o9cix": true,
    "cm16k73gq014h0mmj5b6jdi9r": false
  }
}

Example generated from the schema

200 Response

{
  "id": "clh3k9m2p4q6r8s0t2v4x6z8",
  "success": true
}

400 Response

{
  "message": "Invalid email address.",
  "success": false
}

409 Response

{
  "message": "Invalid email address.",
  "success": false
}

Update a contact

PUT /v1/contacts/update

Requires apiKey — bearer

Update a contact by email or userId. You must provide one of these parameters.

If you want to update a contact's email address, the contact will first need a userId value. You can then make a request containing the userId field along with an updated email address.

This endpoint will create a contact if a matching contact does not already exist in your audience.

Provide either email or userId to identify the contact you want to update. If both are provided, the system will look for a contact with either a matching email or userId value. If a contact is found for one of the values (e.g. email), the other value (e.g. userId) will be updated. If a contact is not found, a new contact will be created using both email and userId values.

Request body ContactUpdateRequest

You can add custom contact properties as keys in this request (of type string, number, boolean or date. See available date formats). Make sure to create the properties in Loops before using them in API calls.

email string

The contact's email address.

firstName string

The contact's first name.

lastName string

The contact's last name.

source string

A custom source value to replace the default “API”.

subscribed boolean

Whether the contact will receive campaign and workflow emails. All new contacts are subscribed by default.

userGroup string

The contact's user group.

userId string

A unique user ID (for example, from an external application).

mailingLists MailingListSubscriptions

Manage mailing list subscriptions.

Include key-value pairs of mailing list IDs and a boolean denoting if the contact should be added (true) or removed (false) from the list.

additional properties one of

3 fields

one of · 1 string

one of · 2 number

one of · 3 boolean

Responses

200 400 405

Successful update.

ContactSuccessResponseused by 2 operations

success boolean

id string

Bad request (e.g. email or userId are missing).

ContactFailureResponseused by 6 operations

success boolean

message string

Wrong HTTP request method.

PUT /v1/contacts/update

{
  "email": "alex@company.com",
  "favoriteColor": "blue",
  "firstName": "Alex",
  "lastName": "Rivera",
  "mailingLists": {
    "clm2k8j4h6g0f8d6s4a2b0z8": true
  },
  "subscribed": true,
  "userGroup": "customers",
  "userId": "usr_7f8e9d0c1b2a"
}

200 Response

{
  "id": "clh3k9m2p4q6r8s0t2v4x6z8",
  "success": true
}

400 Response

{
  "message": "Invalid email address.",
  "success": false
}

Find a contact

GET /v1/contacts/find

Requires apiKey — bearer

Search for a contact by email or userId. Only one parameter is allowed.

Query parameters

email string

Email address (URI-encoded)

userId string

Responses

200 400 405

List of contacts (or an empty array if no contact was found). Contact objects will include any custom properties.

items Contact

10 fields

id string

The contact's Loops ID.

email string

The contact's email address.

firstName string

nullable

The contact's first name.

lastName string

nullable

The contact's last name.

source string

The source the contact was created from.

subscribed boolean

Whether the contact will receive campaign and workflow emails.

userGroup string

The contact's user group.

userId string

nullable

The contact's unique user ID.

mailingLists object

Mailing lists the contact is subscribed to, represented by key-value pairs of mailing list IDs and true.

optInStatus string

nullable

Double opt-in status. This will be null for contacts unless they are created via a form while double opt-in is enabled.

enum acceptedpendingrejectednull

Bad request (e.g. invalid email address).

ContactFailureResponseused by 6 operations

success boolean

message string

Wrong HTTP request method.

200 Response

[
  {
    "id": "clh3k9m2p4q6r8s0t2v4x6z8",
    "email": "alex@company.com",
    "firstName": "Alex",
    "lastName": "Rivera",
    "source": "API",
    "subscribed": true,
    "userGroup": "customers",
    "userId": "usr_7f8e9d0c1b2a",
    "mailingLists": {
      "clm2k8j4h6g0f8d6s4a2b0z8": true
    },
    "optInStatus": "accepted"
  }
]

Example generated from the schema

400 Response

{
  "message": "Invalid email address.",
  "success": false
}

Delete a contact

POST /v1/contacts/delete

Requires apiKey — bearer

Delete a contact by email or userId.

Request body ContactDeleteRequest

Include only one of email or userId.

email string

The contact's email address. Provide this or userId, not both.

userId string

The contact's unique user ID. Provide this or email, not both.

one of · 1

one of · 2

Responses

200 400 404 405

Successful delete.

ContactDeleteResponse

success boolean

message string

Bad request (e.g. email and userId are both provided).

ContactFailureResponseused by 6 operations

success boolean

message string

Contact not found.

ContactFailureResponseused by 6 operations

success boolean

message string

Wrong HTTP request method.

POST /v1/contacts/delete

{
  "email": "alex@company.com"
}

200 Response

{
  "success": true,
  "message": "Contact deleted."
}

Example generated from the schema

400 Response

{
  "message": "Invalid email address.",
  "success": false
}

404 Response

{
  "message": "Invalid email address.",
  "success": false
}

Get suppression status for a contact

GET /v1/contacts/suppression

Requires apiKey — bearer

Retrieve suppression status and removal quota for a contact by email or userId. Include only one query parameter.

Query parameters

email string

Email address (URI-encoded)

userId string

Responses

200 400 404 405

Successful.

ContactSuppressionStatusResponse

contact object

3 fields

id string

The contact's Loops ID.

email string

The contact's email address.

userId string

nullable

The contact's unique user ID.

isSuppressed boolean

Whether the contact is suppressed.

removalQuota ContactSuppressionRemovalQuota

The removal quota for the contact.

Bad request (e.g. invalid email address).

ContactFailureResponseused by 6 operations

success boolean

message string

Contact not found.

ContactFailureResponseused by 6 operations

success boolean

message string

Wrong HTTP request method.

200 Response

{
  "contact": {
    "email": "alex@company.com",
    "id": "clh3k9m2p4q6r8s0t2v4x6z8",
    "userId": "usr_7f8e9d0c1b2a"
  },
  "isSuppressed": false,
  "removalQuota": {
    "limit": 5,
    "remaining": 5
  }
}

400 Response

{
  "message": "Invalid email address.",
  "success": false
}

404 Response

{
  "message": "Invalid email address.",
  "success": false
}

Remove a contact from suppression list

DELETE /v1/contacts/suppression

Requires apiKey — bearer

Remove a suppressed contact from the suppression list by email or userId. Include only one query parameter.

Query parameters

email string

Email address (URI-encoded)

userId string

Responses

200 400 404 405

Successful removal.

ContactSuppressionRemoveResponse

success boolean

Whether the suppression removal was successful.

message string

removalQuota ContactSuppressionRemovalQuota

The removal quota for the contact.

Bad request (e.g. contact is not suppressed).

ContactFailureResponseused by 6 operations

success boolean

message string

Contact not found.

ContactFailureResponseused by 6 operations

success boolean

message string

Wrong HTTP request method.

200 Response

{
  "success": true,
  "message": "Email removed from suppression list.",
  "removalQuota": {
    "limit": 100,
    "remaining": 10
  }
}

Example generated from the schema

400 Response

{
  "message": "Invalid email address.",
  "success": false
}

404 Response

{
  "message": "Invalid email address.",
  "success": false
}

Contact properties

Manage contact properties

List contact properties

GET /v1/contacts/properties

Requires apiKey — bearer

Retrieve a list of your account's contact properties.Use the list parameter to query "all" or "custom" properties.

Query parameters

list string

all (default) or custom (only custom contact properties)

Responses

200 405

Successful.

items ContactProperty

3 fields

key string

The key of the contact property.

label string

The human-friendly label for this property.

type string

The type of property.

enum stringnumberbooleandate

Wrong HTTP request method.

200 Response

[
  {
    "key": "favoriteColor",
    "label": "Favorite color",
    "type": "string"
  }
]

Example generated from the schema

Create a contact property

POST /v1/contacts/properties

Requires apiKey — bearer

Create a custom contact property.

Request body ContactPropertyCreateRequest

There are a few reserved names that you cannot use for contact properties.

name string

The name of the property. This should be in camelCase, like planName or importDate.

type string

The type of property.

enum stringnumberbooleandate

Responses

200 400 405

Successful create.

ContactPropertySuccessResponse

success boolean

Bad request (e.g. invalid type).

ContactPropertyFailureResponse

success boolean

message string

Wrong HTTP request method.

POST /v1/contacts/properties

{
  "name": "favoriteColor",
  "type": "string"
}

200 Response

{
  "success": true
}

Example generated from the schema

400 Response

{
  "message": "Property already exists.",
  "success": false
}

Components

View email components

Get a component

GET /v1/components/{componentId}

Requires apiKey — bearer

Retrieve a single component by ID.

Path parameters

componentId string

The ID of the component.

Responses

200 400 401 404 405

Successful.

ComponentResponseused by 2 operations

id string

The ID of the component.

name string

The name of the component.

lmx string

The component body serialized as LMX.

Invalid componentId.

ComponentFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Component not found.

ComponentFailureResponseused by 4 operations

message string

Wrong HTTP request method.

200 Response

{
  "id": "clp2o4i6u8y0t5r3e1w7q9s1",
  "lmx": "<Paragraph>Welcome to Acme</Paragraph>",
  "name": "Header"
}

400 Response

{
  "message": "Component not found."
}

404 Response

{
  "message": "Component not found."
}

Update a component

POST /v1/components/{componentId}

Requires apiKey — bearer

Update a component's name and/or body. When the lmx body changes, the update cascades to every email using this component, and affectedEmailCount reports how many were affected. A change that would introduce a dynamic variable an email using the component cannot use is rejected.

Path parameters

componentId string

The ID of the component.

Request body UpdateComponentBody

At least one of name or lmx must be provided.

name string

lmx string

The component body as an LMX string.

Responses

200 400 401 404 405 413 422

Successful.

UpdateComponentResponse

id string

The ID of the component.

name string

The name of the component.

lmx string

The component body serialized as LMX.

affectedEmailCount number

The number of emails using this component that were updated by the body change. 0 when only the name changed.

Invalid componentId or request body.

ComponentFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Component not found.

ComponentFailureResponseused by 4 operations

message string

Wrong HTTP request method.

LMX body exceeds the size limit.

ComponentFailureResponseused by 4 operations

message string

Invalid LMX, or a body change that would break emails using the component.

ComponentValidationFailureResponse

message string

invalidTags array of string

The dynamic variables that the change would push into an email that cannot use them. Present only when the update was rejected for that reason.

1 field

items string

POST /v1/components/{componentId}

{
  "name": "string",
  "lmx": "string"
}

Example generated from the schema

200 Response

{
  "affectedEmailCount": 3,
  "id": "clp2o4i6u8y0t5r3e1w7q9s1",
  "lmx": "<Paragraph>Welcome to Acme</Paragraph>",
  "name": "Header"
}

400 Response

{
  "message": "Component not found."
}

404 Response

{
  "message": "Component not found."
}

413 Response

{
  "message": "Component not found."
}

422 Response

{
  "invalidTags": [
    "companyName"
  ],
  "message": "Component uses unsupported contact properties."
}

List components

GET /v1/components

Requires apiKey — bearer

Retrieve a paginated list of email components.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListComponentsResponse

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of Component

1 field

items Component

3 fields

id string

name string

lmx string

The component body serialized as LMX.

Invalid perPage value.

ComponentFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "id": "clp2o4i6u8y0t5r3e1w7q9s1",
      "lmx": "<Paragraph>Welcome to Acme</Paragraph>",
      "name": "Header"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

400 Response

{
  "message": "Component not found."
}

Create a component

POST /v1/components

Requires apiKey — bearer

Create a new email component from an LMX body.

Request body CreateComponentBody

name string

The component name.

lmx string

The component body as an LMX string.

Responses

201 400 401 405 413 422

Component created.

ComponentResponseused by 2 operations

id string

The ID of the component.

name string

The name of the component.

lmx string

The component body serialized as LMX.

Invalid request body.

ComponentFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

LMX body exceeds the size limit.

ComponentFailureResponseused by 4 operations

message string

Invalid LMX.

ComponentFailureResponseused by 4 operations

message string

POST /v1/components

{
  "lmx": "<Paragraph>Welcome to Acme</Paragraph>",
  "name": "Header"
}

201 Response

{
  "id": "clp2o4i6u8y0t5r3e1w7q9s1",
  "lmx": "<Paragraph>Welcome to Acme</Paragraph>",
  "name": "Header"
}

400 Response

{
  "message": "Component not found."
}

413 Response

{
  "message": "Component not found."
}

422 Response

{
  "message": "Component not found."
}

Email messages

Manage email message content for campaigns

Get an email message

GET /v1/email-messages/{emailMessageId}

Requires apiKey — bearer

Retrieve an email message, including its compiled LMX content.

Path parameters

emailMessageId string

The ID of the email message.

Responses

200 400 401 404 405 409

Successful.

EmailMessageResponseused by 2 operations

id string

The ID of the email message.

campaignId string

The campaign this email message belongs to. Present only when the message belongs to a campaign (mutually exclusive with transactionalId).

transactionalId string

The transactional email this email message belongs to. Present only when the message belongs to a transactional email (mutually exclusive with campaignId).

subject string

The email subject.

previewText string

The email preview text.

fromName string

The email sender name.

fromEmail string

The email sender email address, without the team's sending domain.

replyToEmail string

The email reply-to address.

ccEmail string

The email CC address. Only present when set.

bccEmail string

The email BCC address. Only present when set.

languageCode string

ISO 639-1 language code for the email, e.g. en or fr. Only present when set.

emailFormat string

The rendering format of the email.

enum styledplain

lmx string

The email body serialized as LMX.

contentRevisionId string

nullable

The current content revision. Pass this as expectedRevisionId on your next update.

updatedAt string · date-time

contactPropertiesFallbacks object

Fallback values for contact properties. Only present when set.

1 field

additional properties string

eventPropertiesFallbacks object

Fallback values for event properties. Only present when set.

1 field

additional properties string

dataVariablesFallbacks object

Fallback values for data variables. Only present when set.

1 field

additional properties string

warnings array of object

Non-fatal issues raised while compiling the submitted LMX. Only present on update responses when warnings were produced.

1 field

items object

4 fields

rule string

severity string

enum warning

message string

path string

Invalid emailMessageId or no sending domain configured.

EmailMessageFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Email message not found.

EmailMessageFailureResponseused by 4 operations

message string

Wrong HTTP request method.

Email message uses MJML format or content cannot be parsed.

EmailMessageFailureResponseused by 4 operations

message string

200 Response

{
  "campaignId": "clc4m6n8p0q2r4s6t8u0v2x4",
  "contentRevisionId": "clrev1s10n2i3d4e5f6g7h8",
  "emailFormat": "styled",
  "fromEmail": "hello",
  "fromName": "Acme Team",
  "id": "cle5f7g9h1i3j5k7l9m1n3p5",
  "lmx": "<Paragraph>Hello, {firstName}!</Paragraph>",
  "previewText": "See what's new this season",
  "replyToEmail": "support@company.com",
  "subject": "Spring product updates",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Email message not found."
}

404 Response

{
  "message": "Email message not found."
}

409 Response

{
  "message": "Email message not found."
}

Update an email message

POST /v1/email-messages/{emailMessageId}

Requires apiKey — bearer

Update fields on an email message (subject, preview text, sender, LMX content). The campaign must be in draft status. Supply expectedRevisionId matching the current contentRevisionId — the server rejects mismatched revisions with 409.

Path parameters

emailMessageId string

The ID of the email message.

Request body UpdateEmailMessageRequest

expectedRevisionId string

The contentRevisionId you last fetched, or the emailMessageContentRevisionId you received when creating the campaign.

subject string

previewText string

fromName string

fromEmail string

The email sender email address, without the team's sending domain.

replyToEmail string

Reply-to email. Must be empty or a valid email address.

ccEmail string

CC email address. Requires the team to have CC/BCC enabled. Not supported for campaign emails.

bccEmail string

BCC email address. Requires the team to have CC/BCC enabled. Not supported for campaign emails.

languageCode string

ISO 639-1 language code for the email, e.g. en or fr.

emailFormat string

The rendering format of the email.

enum styledplain

lmx string

The email body serialized as LMX. Styles must be embedded in the LMX <Style /> tag.

contactPropertiesFallbacks object

Fallback values for contact properties, keyed by property name. Per-key merge: a string value sets the fallback, a null value deletes it, and keys omitted from the map are left unchanged.

1 field

additional properties string

nullable

eventPropertiesFallbacks object

Fallback values for event properties, keyed by property name. Per-key merge: a string value sets the fallback, a null value deletes it, and keys omitted from the map are left unchanged.

1 field

additional properties string

nullable

dataVariablesFallbacks object

Fallback values for data variables, keyed by variable name. Per-key merge: a string value sets the fallback, a null value deletes it, and keys omitted from the map are left unchanged.

1 field

additional properties string

nullable

Responses

200 400 401 404 405 409 413 422

Email message updated.

EmailMessageResponseused by 2 operations

id string

The ID of the email message.

campaignId string

The campaign this email message belongs to. Present only when the message belongs to a campaign (mutually exclusive with transactionalId).

transactionalId string

The transactional email this email message belongs to. Present only when the message belongs to a transactional email (mutually exclusive with campaignId).

subject string

The email subject.

previewText string

The email preview text.

fromName string

The email sender name.

fromEmail string

The email sender email address, without the team's sending domain.

replyToEmail string

The email reply-to address.

ccEmail string

The email CC address. Only present when set.

bccEmail string

The email BCC address. Only present when set.

languageCode string

ISO 639-1 language code for the email, e.g. en or fr. Only present when set.

emailFormat string

The rendering format of the email.

enum styledplain

lmx string

The email body serialized as LMX.

contentRevisionId string

nullable

The current content revision. Pass this as expectedRevisionId on your next update.

updatedAt string · date-time

contactPropertiesFallbacks object

Fallback values for contact properties. Only present when set.

1 field

additional properties string

eventPropertiesFallbacks object

Fallback values for event properties. Only present when set.

1 field

additional properties string

dataVariablesFallbacks object

Fallback values for data variables. Only present when set.

1 field

additional properties string

warnings array of object

Non-fatal issues raised while compiling the submitted LMX. Only present on update responses when warnings were produced.

1 field

items object

4 fields

rule string

severity string

enum warning

message string

path string

Invalid request body.

EmailMessageFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Email message not found.

EmailMessageFailureResponseused by 4 operations

message string

Wrong HTTP request method.

Campaign is not in draft status, contentRevisionId is stale, content cannot be parsed, or email message uses MJML format.

EmailMessageFailureResponseused by 4 operations

message string

LMX payload exceeds the 100KB limit.

EmailMessageFailureResponseused by 4 operations

message string

LMX failed to compile.

EmailMessageFailureResponseused by 4 operations

message string

POST /v1/email-messages/{emailMessageId}

{
  "contactPropertiesFallbacks": {
    "firstName": "there"
  },
  "emailFormat": "styled",
  "expectedRevisionId": "clrev1s10n2i3d4e5f6g7h8",
  "fromEmail": "hello",
  "fromName": "Acme Team",
  "lmx": "<Paragraph>Hello, {firstName}!</Paragraph>",
  "previewText": "See what's new this season",
  "replyToEmail": "support@company.com",
  "subject": "Spring product updates"
}

200 Response

{
  "campaignId": "clc4m6n8p0q2r4s6t8u0v2x4",
  "contentRevisionId": "clrev1s10n2i3d4e5f6g7h8",
  "emailFormat": "styled",
  "fromEmail": "hello",
  "fromName": "Acme Team",
  "id": "cle5f7g9h1i3j5k7l9m1n3p5",
  "lmx": "<Paragraph>Hello, {firstName}!</Paragraph>",
  "previewText": "See what's new this season",
  "replyToEmail": "support@company.com",
  "subject": "Spring product updates",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Email message not found."
}

404 Response

{
  "message": "Email message not found."
}

409 Response

{
  "message": "Email message not found."
}

413 Response

{
  "message": "Email message not found."
}

422 Response

{
  "message": "Email message not found."
}

Send a preview of an email message

POST /v1/email-messages/{emailMessageId}/preview

Requires apiKey — bearer

Send a test preview of an email message to one or more addresses. The accepted variable fields depend on the parent's type - campaign previews accept contactProperties, workflow previews accept contactProperties and eventProperties, and transactional previews accept dataVariables. Supplying a field the parent cannot reference is rejected with 400.

Path parameters

emailMessageId string

The ID of the email message.

Request body EmailMessagePreviewRequest

emails array of string

One or more addresses to send the preview to.

rules min items 1

1 field

items string

contactProperties object

Contact property values to render. Accepted for campaign and workflow previews.

1 field

additional properties string

eventProperties object

Event property values to render. Accepted for workflow previews only.

1 field

additional properties string

dataVariables object

Transactional data variables to render. Accepted for transactional previews only.

1 field

additional properties string

Responses

200 400 401 404 405 429

Preview scheduled.

EmailMessagePreviewResponse

id string

The ID of the email message the preview was sent for.

Invalid request body, or a variable field the parent cannot reference.

EmailMessageFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Email message not found.

EmailMessageFailureResponseused by 4 operations

message string

Wrong HTTP request method.

The daily preview limit was reached.

EmailMessageFailureResponseused by 4 operations

message string

POST /v1/email-messages/{emailMessageId}/preview

{
  "contactProperties": {
    "firstName": "Alex"
  },
  "dataVariables": {
    "loginUrl": "https://app.company.com/login"
  },
  "emails": [
    "alex@company.com"
  ],
  "eventProperties": {
    "planName": "Pro"
  }
}

200 Response

{
  "id": "cle5f7g9h1i3j5k7l9m1n3p5"
}

400 Response

{
  "message": "Email message not found."
}

404 Response

{
  "message": "Email message not found."
}

429 Response

{
  "message": "Email message not found."
}

Run Guardian checks on an email message

GET /v1/email-messages/{emailMessageId}/guardian

Requires apiKey — bearer

Validate an email message's content against Guardian rules and return any errors and warnings. Errors must be resolved before the email can be published, warnings are advisory.

Path parameters

emailMessageId string

The ID of the email message.

Responses

200 400 401 404 405 409

Successful.

EmailMessageGuardianResponse

errors array of GuardianRule

Validation errors. These must be resolved before the email can be published.

1 field

items GuardianRule

4 fields

rule string

The identifier of the Guardian rule that fired.

enum unsupportedContactPropertiesmissingFallbackContactPropertiesunsupportedEventPropertiesmissingFallbackEventPropertiesunsupportedDataVariablesinvalidCustomDataVariablesmissingRequiredDataVariablesmissingButtonHrefsinvalidButtonHrefsshortenedYouTubeButtonHrefsmissingLinkHrefsinvalidLinkHrefsshortenedYouTubeLinkHrefsshortenedYouTubeImageHrefsemailWithoutMailtoButtonHrefsemailWithoutMailtoLinkHrefsemailWithoutMailtoImageHrefsbareArrayNodesmissingSocialIconHrefs

title string

A short summary of the rule.

description string

A longer explanation of why the issue matters.

items array of object

The specific elements that triggered the rule.

1 field

items object

2 fields

label string

A human-readable label for the item (for example, link text or a property name).

codeName string

Machine-readable identifier when the rule refers to a property or variable, when applicable.

warnings array of GuardianRule

Validation warnings. These are advisory and do not block publishing.

1 field

items GuardianRule

4 fields

rule string

The identifier of the Guardian rule that fired.

enum unsupportedContactPropertiesmissingFallbackContactPropertiesunsupportedEventPropertiesmissingFallbackEventPropertiesunsupportedDataVariablesinvalidCustomDataVariablesmissingRequiredDataVariablesmissingButtonHrefsinvalidButtonHrefsshortenedYouTubeButtonHrefsmissingLinkHrefsinvalidLinkHrefsshortenedYouTubeLinkHrefsshortenedYouTubeImageHrefsemailWithoutMailtoButtonHrefsemailWithoutMailtoLinkHrefsemailWithoutMailtoImageHrefsbareArrayNodesmissingSocialIconHrefs

title string

A short summary of the rule.

description string

A longer explanation of why the issue matters.

items array of object

The specific elements that triggered the rule.

1 field

items object

2 fields

label string

A human-readable label for the item (for example, link text or a property name).

codeName string

Machine-readable identifier when the rule refers to a property or variable, when applicable.

Invalid emailMessageId.

EmailMessageFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Email message not found.

EmailMessageFailureResponseused by 4 operations

message string

Wrong HTTP request method.

Email message uses MJML format.

EmailMessageFailureResponseused by 4 operations

message string

200 Response

{
  "errors": [
    {
      "description": "Buttons won't work without href value",
      "items": [
        {
          "label": "Click here"
        }
      ],
      "rule": "missingButtonHrefs",
      "title": "Missing button link"
    },
    {
      "description": "Links won't work without href value",
      "items": [
        {
          "label": "See more"
        }
      ],
      "rule": "missingLinkHrefs",
      "title": "Missing text link"
    }
  ],
  "warnings": []
}

400 Response

{
  "message": "Email message not found."
}

404 Response

{
  "message": "Email message not found."
}

409 Response

{
  "message": "Email message not found."
}

Events

Trigger workflows with events

Send an event

POST /v1/events/send

Requires apiKey — bearer

Send events to trigger workflows.

Header parameters

Idempotency-Key string

Include a unique ID for this request (maximum 100 characters) to avoid duplicate emails.

The value should be a string of up to 100 characters and should be unique for each request. We recommend using V4 UUIDs or some other method with enough guaranteed entropy to avoid collisions during a 24 hour window.

This endpoint will return a 409 Conflict response if the idempotency key has been used in the previous 24 hours.

rules max length 100

Request body EventRequest

Provide either email or userId to identify the contact (read more).Event properties will be available in emails sent by this event. Values of properties can be of type string, number, boolean or date (see allowed date formats).Make sure to create the properties in Loops before using them in API calls.You can add update the contact by adding contact properties as keys in this request (of type string, number, boolean or date (see available date formats)).

email string

The contact's email address. Required if userId is not provided.

userId string

The contact's unique user ID. Required if email is not provided.

eventName string

The name of the event.

eventProperties object

An object containing event property data for the event, available in emails sent by the event.

mailingLists MailingListSubscriptions

Manage mailing list subscriptions.

Include key-value pairs of mailing list IDs and a boolean denoting if the contact should be added (true) or removed (false) from the list.

additional properties one of

3 fields

one of · 1 string

one of · 2 number

one of · 3 boolean

any of · 1

any of · 2

Responses

200 400 405 409

Successful send.

EventSuccessResponse

success boolean

Bad request (e.g. eventName is missing).

EventFailureResponse

success boolean

message string

Wrong HTTP request method.

Idempotency key has been used.

IdempotencyKeyFailureResponseused by 2 operations

success boolean

message string

POST /v1/events/send

{
  "email": "alex@company.com",
  "eventName": "signup",
  "eventProperties": {
    "plan": "pro"
  },
  "favoriteColor": "blue",
  "mailingLists": {
    "clm2k8j4h6g0f8d6s4a2b0z8": true
  },
  "planName": "Pro",
  "userId": "usr_7f8e9d0c1b2a"
}

200 Response

{
  "success": true
}

Example generated from the schema

400 Response

{
  "message": "Contact not found.",
  "success": false
}

409 Response

{
  "message": "Request with idempotency key <idempotencyKey> has already been processed.",
  "success": false
}

Event patterns

View workflow event patterns

List event patterns

GET /v1/event-patterns

Requires apiKey — bearer

Retrieve a paginated list of event patterns available to workflow event trigger nodes.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListEventPatternsResponse

pagination object

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of EventPatternSummary

1 field

items EventPatternSummary

3 fields

id string

The ID of the event pattern.

eventName string

The name of the event pattern. Use this when sending events with the API.

incomingWebhookPlatform string

nullable

The platform that sent this event pattern, if the event pattern is from an incoming webhook. Will be null for custom events.

enum clerkpolarstripesupabasenull

Invalid perPage or cursor value.

EventPatternFailureResponseused by 3 operations

message string

Invalid API key.

Wrong HTTP request method.

200 Response

{
  "pagination": {
    "totalResults": 0,
    "returnedResults": 0,
    "perPage": 0,
    "totalPages": 0,
    "nextCursor": "string",
    "nextPage": "string"
  },
  "data": [
    {
      "id": "string",
      "eventName": "string",
      "incomingWebhookPlatform": "clerk"
    }
  ]
}

Example generated from the schema

400 Response

{
  "message": "string"
}

Example generated from the schema

Get an event pattern by name

GET /v1/event-patterns/by-name/{eventName}

Requires apiKey — bearer

Retrieve event pattern details by event name for a workflow event trigger. Event names are case-sensitive, so PaymentReceived and paymentReceived are different events.

Path parameters

eventName string

The exact event name. Event names are case-sensitive and should be URL-encoded if they contain special characters.

Responses

200 400 401 404 405

Successful.

EventPatternused by 2 operations

id string

eventName string

The name of the event pattern. Use this when sending events with the API.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

incomingWebhookPlatform string

nullable

The platform that sent this event pattern, if the event pattern is from an incoming webhook. Will be null for custom events.

enum clerkpolarstripesupabasenull

Invalid eventName.

EventPatternFailureResponseused by 3 operations

message string

Invalid API key.

Event pattern not found.

EventPatternFailureResponseused by 3 operations

message string

Wrong HTTP request method.

200 Response

{
  "id": "string",
  "eventName": "string",
  "eventProperties": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "incomingWebhookPlatform": "clerk"
}

Example generated from the schema

400 Response

{
  "message": "string"
}

Example generated from the schema

404 Response

{
  "message": "string"
}

Example generated from the schema

Get an event pattern by ID

GET /v1/event-patterns/{eventPatternId}

Requires apiKey — bearer

Retrieve event pattern details for a workflow event trigger.

Path parameters

eventPatternId string

The ID of the event pattern.

Responses

200 400 401 404 405

Successful.

EventPatternused by 2 operations

id string

eventName string

The name of the event pattern. Use this when sending events with the API.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

incomingWebhookPlatform string

nullable

The platform that sent this event pattern, if the event pattern is from an incoming webhook. Will be null for custom events.

enum clerkpolarstripesupabasenull

Invalid eventPatternId.

EventPatternFailureResponseused by 3 operations

message string

Invalid API key.

Event pattern not found.

EventPatternFailureResponseused by 3 operations

message string

Wrong HTTP request method.

200 Response

{
  "id": "string",
  "eventName": "string",
  "eventProperties": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "incomingWebhookPlatform": "clerk"
}

Example generated from the schema

400 Response

{
  "message": "string"
}

Example generated from the schema

404 Response

{
  "message": "string"
}

Example generated from the schema

Mailing lists

View mailing lists

List mailing lists

GET /v1/lists

Requires apiKey — bearer

Retrieve a list of your account's mailing lists.

Responses

200 405

Successful.

items MailingList

4 fields

id string

The ID of the mailing list.

name string

The name of the mailing list.

description string

nullable

The description of the mailing list. null if no description is set.

isPublic boolean

Whether the mailing list is public (true) or private (false).

Wrong HTTP request method.

200 Response

[
  {
    "id": "clm2k8j4h6g0f8d6s4a2b0z8",
    "name": "Product updates",
    "description": "Monthly product news and release notes",
    "isPublic": true
  }
]

Example generated from the schema

Themes

View email themes

Get a theme

GET /v1/themes/{themeId}

Requires apiKey — bearer

Retrieve a single theme by ID.

Path parameters

themeId string

The ID of the theme.

Responses

200 400 401 404 405

Successful.

ThemeResponseused by 2 operations

id string

The ID of the theme.

name string

The name of the theme.

styles ThemeStyles

Flat map of style attributes, matching the attribute names accepted by the LMX <Style /> tag.

39 fields

backgroundColor string

backgroundXPadding number

backgroundYPadding number

bodyColor string

bodyXPadding number

bodyYPadding number

bodyFontFamily string

bodyFontCategory string

borderColor string

borderWidth number

borderRadius number

buttonBodyColor string

buttonBodyXPadding number

buttonBodyYPadding number

buttonBorderColor string

buttonBorderWidth number

buttonBorderRadius number

buttonTextColor string

buttonTextFormat number

buttonTextFontSize number

dividerColor string

dividerBorderWidth number

textBaseColor string

textBaseFontSize number

textBaseLineHeight number

textBaseLetterSpacing number

textLinkColor string

heading1Color string

heading1FontSize number

heading1LineHeight number

heading1LetterSpacing number

heading2Color string

heading2FontSize number

heading2LineHeight number

heading2LetterSpacing number

heading3Color string

heading3FontSize number

heading3LineHeight number

heading3LetterSpacing number

isDefault boolean

Whether this theme is the team's default.

createdAt string

ISO 8601 timestamp for when the theme was created.

updatedAt string

ISO 8601 timestamp for when the theme was last updated.

Invalid themeId.

ThemeFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Theme not found.

ThemeFailureResponseused by 4 operations

message string

Wrong HTTP request method.

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "id": "clt3u5v7w9x1y3z5a7b9c1d3",
  "isDefault": true,
  "name": "Default",
  "styles": {
    "backgroundColor": "#f5f5f5",
    "backgroundXPadding": 24,
    "backgroundYPadding": 24,
    "bodyColor": "#ffffff",
    "bodyFontCategory": "sans-serif",
    "bodyFontFamily": "Helvetica",
    "bodyXPadding": 24,
    "bodyYPadding": 24,
    "borderColor": "#e5e5e5",
    "borderRadius": 8,
    "borderWidth": 1,
    "buttonBodyColor": "#111827",
    "buttonBodyXPadding": 16,
    "buttonBodyYPadding": 12,
    "buttonBorderColor": "#111827",
    "buttonBorderRadius": 6,
    "buttonBorderWidth": 0,
    "buttonTextColor": "#ffffff",
    "buttonTextFontSize": 16,
    "buttonTextFormat": 0,
    "dividerBorderWidth": 1,
    "dividerColor": "#e5e5e5",
    "heading1Color": "#111827",
    "heading1FontSize": 28,
    "heading1LetterSpacing": -0.5,
    "heading1LineHeight": 36,
    "heading2Color": "#111827",
    "heading2FontSize": 22,
    "heading2LetterSpacing": -0.25,
    "heading2LineHeight": 30,
    "heading3Color": "#111827",
    "heading3FontSize": 18,
    "heading3LetterSpacing": 0,
    "heading3LineHeight": 26,
    "textBaseColor": "#374151",
    "textBaseFontSize": 16,
    "textBaseLetterSpacing": 0,
    "textBaseLineHeight": 24,
    "textLinkColor": "#2563eb"
  },
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Theme not found."
}

404 Response

{
  "message": "Theme not found."
}

Update a theme

POST /v1/themes/{themeId}

Requires apiKey — bearer

Update a theme's name and/or styles. When styles change, the update cascades to every email using this theme, and affectedEmailCount in the response reports how many emails were affected. Manual style edits made on individual emails are preserved: the cascade only changes properties an email has not overridden. A per-email override is removed only when it becomes identical to the theme's new value, after which that email follows the theme for that property.

Path parameters

themeId string

The ID of the theme.

Request body UpdateThemeBody

At least one of name or styles must be provided.

name string

styles ThemeStyles

Flat map of style attributes, matching the attribute names accepted by the LMX <Style /> tag.

39 fields

backgroundColor string

backgroundXPadding number

backgroundYPadding number

bodyColor string

bodyXPadding number

bodyYPadding number

bodyFontFamily string

bodyFontCategory string

borderColor string

borderWidth number

borderRadius number

buttonBodyColor string

buttonBodyXPadding number

buttonBodyYPadding number

buttonBorderColor string

buttonBorderWidth number

buttonBorderRadius number

buttonTextColor string

buttonTextFormat number

buttonTextFontSize number

dividerColor string

dividerBorderWidth number

textBaseColor string

textBaseFontSize number

textBaseLineHeight number

textBaseLetterSpacing number

textLinkColor string

heading1Color string

heading1FontSize number

heading1LineHeight number

heading1LetterSpacing number

heading2Color string

heading2FontSize number

heading2LineHeight number

heading2LetterSpacing number

heading3Color string

heading3FontSize number

heading3LineHeight number

heading3LetterSpacing number

Responses

200 400 401 404 405

Successful.

UpdateThemeResponse

id string

The ID of the theme.

name string

The name of the theme.

styles ThemeStyles

Flat map of style attributes, matching the attribute names accepted by the LMX <Style /> tag.

39 fields

backgroundColor string

backgroundXPadding number

backgroundYPadding number

bodyColor string

bodyXPadding number

bodyYPadding number

bodyFontFamily string

bodyFontCategory string

borderColor string

borderWidth number

borderRadius number

buttonBodyColor string

buttonBodyXPadding number

buttonBodyYPadding number

buttonBorderColor string

buttonBorderWidth number

buttonBorderRadius number

buttonTextColor string

buttonTextFormat number

buttonTextFontSize number

dividerColor string

dividerBorderWidth number

textBaseColor string

textBaseFontSize number

textBaseLineHeight number

textBaseLetterSpacing number

textLinkColor string

heading1Color string

heading1FontSize number

heading1LineHeight number

heading1LetterSpacing number

heading2Color string

heading2FontSize number

heading2LineHeight number

heading2LetterSpacing number

heading3Color string

heading3FontSize number

heading3LineHeight number

heading3LetterSpacing number

isDefault boolean

Whether this theme is the team's default.

createdAt string

ISO 8601 timestamp for when the theme was created.

updatedAt string

ISO 8601 timestamp for when the theme was last updated.

affectedEmailCount number

The number of emails using this theme that are affected by the style change. 0 when only the name changed.

Invalid themeId or request body.

ThemeFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Theme not found.

ThemeFailureResponseused by 4 operations

message string

Wrong HTTP request method.

POST /v1/themes/{themeId}

{
  "name": "string",
  "styles": {
    "backgroundColor": "string",
    "backgroundXPadding": 0,
    "backgroundYPadding": 0,
    "bodyColor": "string",
    "bodyXPadding": 0,
    "bodyYPadding": 0,
    "bodyFontFamily": "string",
    "bodyFontCategory": "string",
    "borderColor": "string",
    "borderWidth": 0,
    "borderRadius": 0,
    "buttonBodyColor": "string",
    "buttonBodyXPadding": 0,
    "buttonBodyYPadding": 0,
    "buttonBorderColor": "string",
    "buttonBorderWidth": 0,
    "buttonBorderRadius": 0,
    "buttonTextColor": "string",
    "buttonTextFormat": 0,
    "buttonTextFontSize": 0,
    "dividerColor": "string",
    "dividerBorderWidth": 0,
    "textBaseColor": "string",
    "textBaseFontSize": 0,
    "textBaseLineHeight": 0,
    "textBaseLetterSpacing": 0,
    "textLinkColor": "string",
    "heading1Color": "string",
    "heading1FontSize": 0,
    "heading1LineHeight": 0,
    "heading1LetterSpacing": 0,
    "heading2Color": "string",
    "heading2FontSize": 0,
    "heading2LineHeight": 0,
    "heading2LetterSpacing": 0,
    "heading3Color": "string",
    "heading3FontSize": 0,
    "heading3LineHeight": 0,
    "heading3LetterSpacing": 0
  }
}

Example generated from the schema

200 Response

{
  "affectedEmailCount": 12,
  "createdAt": "2025-06-29T07:47:39.370Z",
  "id": "clt3u5v7w9x1y3z5a7b9c1d3",
  "isDefault": true,
  "name": "Default",
  "styles": {
    "backgroundColor": "#f5f5f5",
    "backgroundXPadding": 24,
    "backgroundYPadding": 24,
    "bodyColor": "#ffffff",
    "bodyFontCategory": "sans-serif",
    "bodyFontFamily": "Helvetica",
    "bodyXPadding": 24,
    "bodyYPadding": 24,
    "borderColor": "#e5e5e5",
    "borderRadius": 8,
    "borderWidth": 1,
    "buttonBodyColor": "#111827",
    "buttonBodyXPadding": 16,
    "buttonBodyYPadding": 12,
    "buttonBorderColor": "#111827",
    "buttonBorderRadius": 6,
    "buttonBorderWidth": 0,
    "buttonTextColor": "#ffffff",
    "buttonTextFontSize": 16,
    "buttonTextFormat": 0,
    "dividerBorderWidth": 1,
    "dividerColor": "#e5e5e5",
    "heading1Color": "#111827",
    "heading1FontSize": 28,
    "heading1LetterSpacing": -0.5,
    "heading1LineHeight": 36,
    "heading2Color": "#111827",
    "heading2FontSize": 22,
    "heading2LetterSpacing": -0.25,
    "heading2LineHeight": 30,
    "heading3Color": "#111827",
    "heading3FontSize": 18,
    "heading3LetterSpacing": 0,
    "heading3LineHeight": 26,
    "textBaseColor": "#374151",
    "textBaseFontSize": 16,
    "textBaseLetterSpacing": 0,
    "textBaseLineHeight": 24,
    "textLinkColor": "#2563eb"
  },
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Theme not found."
}

404 Response

{
  "message": "Theme not found."
}

List themes

GET /v1/themes

Requires apiKey — bearer

Retrieve a paginated list of email themes, most recently created first.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListThemesResponse

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of Theme

1 field

items Theme

6 fields

id string

The ID of the theme.

name string

The name of the theme.

styles ThemeStyles

Flat map of style attributes, matching the attribute names accepted by the LMX <Style /> tag.

39 fields

backgroundColor string

backgroundXPadding number

backgroundYPadding number

bodyColor string

bodyXPadding number

bodyYPadding number

bodyFontFamily string

bodyFontCategory string

borderColor string

borderWidth number

borderRadius number

buttonBodyColor string

buttonBodyXPadding number

buttonBodyYPadding number

buttonBorderColor string

buttonBorderWidth number

buttonBorderRadius number

buttonTextColor string

buttonTextFormat number

buttonTextFontSize number

dividerColor string

dividerBorderWidth number

textBaseColor string

textBaseFontSize number

textBaseLineHeight number

textBaseLetterSpacing number

textLinkColor string

heading1Color string

heading1FontSize number

heading1LineHeight number

heading1LetterSpacing number

heading2Color string

heading2FontSize number

heading2LineHeight number

heading2LetterSpacing number

heading3Color string

heading3FontSize number

heading3LineHeight number

heading3LetterSpacing number

isDefault boolean

Whether this theme is the team's default.

createdAt string

ISO 8601 timestamp for when the theme was created.

updatedAt string

ISO 8601 timestamp for when the theme was last updated.

Invalid perPage value.

ThemeFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "createdAt": "2025-06-29T07:47:39.370Z",
      "id": "clt3u5v7w9x1y3z5a7b9c1d3",
      "isDefault": true,
      "name": "Default",
      "styles": {
        "backgroundColor": "#f5f5f5",
        "backgroundXPadding": 24,
        "backgroundYPadding": 24,
        "bodyColor": "#ffffff",
        "bodyFontCategory": "sans-serif",
        "bodyFontFamily": "Helvetica",
        "bodyXPadding": 24,
        "bodyYPadding": 24,
        "borderColor": "#e5e5e5",
        "borderRadius": 8,
        "borderWidth": 1,
        "buttonBodyColor": "#111827",
        "buttonBodyXPadding": 16,
        "buttonBodyYPadding": 12,
        "buttonBorderColor": "#111827",
        "buttonBorderRadius": 6,
        "buttonBorderWidth": 0,
        "buttonTextColor": "#ffffff",
        "buttonTextFontSize": 16,
        "buttonTextFormat": 0,
        "dividerBorderWidth": 1,
        "dividerColor": "#e5e5e5",
        "heading1Color": "#111827",
        "heading1FontSize": 28,
        "heading1LetterSpacing": -0.5,
        "heading1LineHeight": 36,
        "heading2Color": "#111827",
        "heading2FontSize": 22,
        "heading2LetterSpacing": -0.25,
        "heading2LineHeight": 30,
        "heading3Color": "#111827",
        "heading3FontSize": 18,
        "heading3LetterSpacing": 0,
        "heading3LineHeight": 26,
        "textBaseColor": "#374151",
        "textBaseFontSize": 16,
        "textBaseLetterSpacing": 0,
        "textBaseLineHeight": 24,
        "textLinkColor": "#2563eb"
      },
      "updatedAt": "2025-06-29T07:47:39.370Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

400 Response

{
  "message": "Theme not found."
}

Create a theme

POST /v1/themes

Requires apiKey — bearer

Create a new email theme for use across Loops emails.

Request body CreateThemeBody

name string

The theme name.

styles ThemeStyles

Flat map of style attributes, matching the attribute names accepted by the LMX <Style /> tag.

39 fields

backgroundColor string

backgroundXPadding number

backgroundYPadding number

bodyColor string

bodyXPadding number

bodyYPadding number

bodyFontFamily string

bodyFontCategory string

borderColor string

borderWidth number

borderRadius number

buttonBodyColor string

buttonBodyXPadding number

buttonBodyYPadding number

buttonBorderColor string

buttonBorderWidth number

buttonBorderRadius number

buttonTextColor string

buttonTextFormat number

buttonTextFontSize number

dividerColor string

dividerBorderWidth number

textBaseColor string

textBaseFontSize number

textBaseLineHeight number

textBaseLetterSpacing number

textLinkColor string

heading1Color string

heading1FontSize number

heading1LineHeight number

heading1LetterSpacing number

heading2Color string

heading2FontSize number

heading2LineHeight number

heading2LetterSpacing number

heading3Color string

heading3FontSize number

heading3LineHeight number

heading3LetterSpacing number

Responses

201 400 401 405

Theme created.

ThemeResponseused by 2 operations

id string

The ID of the theme.

name string

The name of the theme.

styles ThemeStyles

Flat map of style attributes, matching the attribute names accepted by the LMX <Style /> tag.

39 fields

backgroundColor string

backgroundXPadding number

backgroundYPadding number

bodyColor string

bodyXPadding number

bodyYPadding number

bodyFontFamily string

bodyFontCategory string

borderColor string

borderWidth number

borderRadius number

buttonBodyColor string

buttonBodyXPadding number

buttonBodyYPadding number

buttonBorderColor string

buttonBorderWidth number

buttonBorderRadius number

buttonTextColor string

buttonTextFormat number

buttonTextFontSize number

dividerColor string

dividerBorderWidth number

textBaseColor string

textBaseFontSize number

textBaseLineHeight number

textBaseLetterSpacing number

textLinkColor string

heading1Color string

heading1FontSize number

heading1LineHeight number

heading1LetterSpacing number

heading2Color string

heading2FontSize number

heading2LineHeight number

heading2LetterSpacing number

heading3Color string

heading3FontSize number

heading3LineHeight number

heading3LetterSpacing number

isDefault boolean

Whether this theme is the team's default.

createdAt string

ISO 8601 timestamp for when the theme was created.

updatedAt string

ISO 8601 timestamp for when the theme was last updated.

Invalid request body.

ThemeFailureResponseused by 4 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

POST /v1/themes

{
  "name": "Dark mode",
  "styles": {
    "backgroundColor": "#111827",
    "bodyColor": "#1f2937"
  }
}

201 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "id": "clt3u5v7w9x1y3z5a7b9c1d3",
  "isDefault": true,
  "name": "Default",
  "styles": {
    "backgroundColor": "#f5f5f5",
    "backgroundXPadding": 24,
    "backgroundYPadding": 24,
    "bodyColor": "#ffffff",
    "bodyFontCategory": "sans-serif",
    "bodyFontFamily": "Helvetica",
    "bodyXPadding": 24,
    "bodyYPadding": 24,
    "borderColor": "#e5e5e5",
    "borderRadius": 8,
    "borderWidth": 1,
    "buttonBodyColor": "#111827",
    "buttonBodyXPadding": 16,
    "buttonBodyYPadding": 12,
    "buttonBorderColor": "#111827",
    "buttonBorderRadius": 6,
    "buttonBorderWidth": 0,
    "buttonTextColor": "#ffffff",
    "buttonTextFontSize": 16,
    "buttonTextFormat": 0,
    "dividerBorderWidth": 1,
    "dividerColor": "#e5e5e5",
    "heading1Color": "#111827",
    "heading1FontSize": 28,
    "heading1LetterSpacing": -0.5,
    "heading1LineHeight": 36,
    "heading2Color": "#111827",
    "heading2FontSize": 22,
    "heading2LetterSpacing": -0.25,
    "heading2LineHeight": 30,
    "heading3Color": "#111827",
    "heading3FontSize": 18,
    "heading3LetterSpacing": 0,
    "heading3LineHeight": 26,
    "textBaseColor": "#374151",
    "textBaseFontSize": 16,
    "textBaseLetterSpacing": 0,
    "textBaseLineHeight": 24,
    "textLinkColor": "#2563eb"
  },
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Theme not found."
}

Transactional emails

Create, manage, and send transactional emails

List transactional emails (legacy) deprecated

GET /v1/transactional

Requires apiKey — bearer

Get a list of published transactional emails.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor, to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 405

Successful.

ListTransactionalsResponse

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of TransactionalEmail

1 field

items TransactionalEmail

4 fields

id string

The ID of the transactional email.

name string

The name of the transactional email.

lastUpdated string

The date and time the transactional email was last updated in ISO 8601 format.

dataVariables array

The data variables used by the transactional email.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "dataVariables": [
        "confirmationUrl"
      ],
      "id": "cll42l54f20i1la0lfooe3z12",
      "lastUpdated": "2025-06-29T07:47:39.370Z",
      "name": "Sign up confirmation"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

Send a transactional email

POST /v1/transactional

Requires apiKey — bearer

Send a transactional email to a contact.Please email us to enable attachments on your account before using them with the API.

To set dynamic Subject, From, Reply to, CC, BCC email header fields, add data variables to those fields in the editor, then include data for each variable in the API request. Read our transactional email guide for more details.

Header parameters

Idempotency-Key string

Include a unique ID for this request (maximum 100 characters) to avoid duplicate emails.

The value should be a string of up to 100 characters and should be unique for each request. We recommend using V4 UUIDs or some other method with enough guaranteed entropy to avoid collisions during a 24 hour window.

This endpoint will return a 409 Conflict response if the idempotency key has been used in the previous 24 hours.

rules max length 100

Request body TransactionalRequest

email string

The recipient's email address.

transactionalId string

The ID of the transactional email to send.

addToAudience boolean

If true, a contact will be created in your audience using the email value (if a matching contact doesn't already exist).

dataVariables object

An object containing data as defined by the data variables added to the transactional email template. Values can be of type string or number.

If you have added optional data variables to your email, you can exclude them from the dataVariables object or set the value to "".

If you have added an array data variable to your email, make sure to include an array matching the data variables you added to your array block.

attachments array of object

A list containing file objects to be sent along with an email message. Attachments must be enabled by Loops support before they can be used with the API.

1 field

items object

3 fields

filename string

The name of the file, shown in email clients.

contentType string

The MIME type of the file.

data string

The base64-encoded content of the file.

Responses

200 400 404 405 409

Successful send.

TransactionalSuccessResponse

success boolean

Bad request (e.g. transactional email is not published).

one of · 1 TransactionalSendFailureResponse

2 fields

success boolean

message string

one of · 2 TransactionalFailure2Response

3 fields

success boolean

message string

path string

one of · 3 TransactionalFailure3Response

3 fields

success boolean

message string

error object

2 fields

path string

message string

one of · 4 TransactionalFailure4Response

3 fields

success boolean

message string

error object

2 fields

path string

reason string

one of · 5 TransactionalFailure5Response

4 fields

success boolean

message string

error object

2 fields

path string

message string

transactionalId string

Transactional email not found.

TransactionalFailure3Response

success boolean

message string

error object

2 fields

path string

message string

Wrong HTTP request method.

Idempotency key has been used.

IdempotencyKeyFailureResponseused by 2 operations

success boolean

message string

POST /v1/transactional

{
  "addToAudience": true,
  "dataVariables": {
    "name": "Alex",
    "passwordResetLink": "https://app.company.com/reset/abc123"
  },
  "email": "alex@company.com",
  "transactionalId": "cll42l54f20i1la0lfooe3z12"
}

200 Response

{
  "success": true
}

Example generated from the schema

400 Response

{
  "success": false,
  "message": "Missing required data variable(s): confirmationUrl"
}

Example generated from the schema

404 Response

{
  "success": false,
  "message": "string",
  "error": {
    "path": "string",
    "message": "string"
  }
}

Example generated from the schema

409 Response

{
  "message": "Request with idempotency key <idempotencyKey> has already been processed.",
  "success": false
}

List transactional emails

GET /v1/transactional-emails

Requires apiKey — bearer

Retrieve a paginated list of transactional emails, most recently created first.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListTransactionalsResourceResponse

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of TransactionalResource

1 field

items TransactionalResource

9 fields

id string

The ID of the transactional email.

url string · uri

The URL of the transactional email in the Loops app.

name string

The name of the transactional email.

draftEmailMessageId string

nullable

The ID of the draft email message. null if there is no draft version.

publishedEmailMessageId string

nullable

The ID of the published email message. null if there is no published version.

transactionalGroupId string

nullable

The ID of the group this transactional email belongs to.

createdAt string · date-time

ISO 8601 timestamp for when the transactional email was created.

updatedAt string · date-time

ISO 8601 timestamp for when the transactional email was last updated.

dataVariables array of string

Data variable names used by the published email. Empty for unpublished transactional emails.

1 field

items string

Invalid perPage value.

TransactionalFailureResponseused by 7 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "createdAt": "2025-06-29T07:47:39.370Z",
      "dataVariables": [
        "confirmationUrl"
      ],
      "draftEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
      "id": "cll42l54f20i1la0lfooe3z12",
      "name": "Sign up confirmation",
      "publishedEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
      "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
      "updatedAt": "2025-06-29T07:47:39.370Z",
      "url": "https://app.loops.so/transactional/cll42l54f20i1la0lfooe3z12"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

400 Response

{
  "message": "Transactional email not found."
}

Create a transactional email

POST /v1/transactional-emails

Requires apiKey — bearer

Create a new transactional email. An empty draft email message is created automatically and its draftEmailMessageId is returned. Use the POST /v1/email-messages/{emailMessageId} endpoint along with the returned draftEmailMessageContentRevisionId to set subject, sender, preview text, and LMX content, then call POST /v1/transactional-emails/{transactionalId}/publish to publish the draft.

Request body CreateTransactionalRequest

name string

The name of the transactional email.

transactionalGroupId string

The ID of the group to add this transactional email to. Defaults to the team's Unsorted group when omitted.

Responses

201 400 401 405

Transactional email created.

TransactionalDraftResponseused by 2 operations

id string

The ID of the transactional email.

url string · uri

The URL of the transactional email in the Loops app.

name string

The name of the transactional email.

draftEmailMessageId string

nullable

The ID of the draft email message.

draftEmailMessageContentRevisionId string

nullable

The contentRevisionId of the draft email message. Pass this as expectedRevisionId on your first update via POST /v1/email-messages/{emailMessageId}.

publishedEmailMessageId string

nullable

The ID of the published email message. null if there is no published version.

transactionalGroupId string

nullable

The ID of the group this transactional email belongs to. Returned when creating a transactional email.

createdAt string · date-time

ISO 8601 timestamp for when the transactional email was created.

updatedAt string · date-time

ISO 8601 timestamp for when the transactional email was last updated.

dataVariables array of string

Data variable names used by the published email. Empty for unpublished transactional emails.

1 field

items string

Invalid request body or no sending domain configured.

TransactionalFailureResponseused by 7 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

POST /v1/transactional-emails

{
  "name": "Welcome email",
  "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7"
}

Example generated from the schema

201 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "dataVariables": [
    "confirmationUrl"
  ],
  "draftEmailMessageContentRevisionId": "clrev1s10n2i3d4e5f6g7h8",
  "draftEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "cll42l54f20i1la0lfooe3z12",
  "name": "Sign up confirmation",
  "publishedEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/transactional/cll42l54f20i1la0lfooe3z12"
}

400 Response

{
  "message": "Transactional email not found."
}

Get a transactional email

GET /v1/transactional-emails/{transactionalId}

Requires apiKey — bearer

Retrieve a single transactional email by ID.

Path parameters

transactionalId string

The ID of the transactional email.

Responses

200 400 401 404 405

Successful.

TransactionalResourceused by 4 operations

id string

The ID of the transactional email.

url string · uri

The URL of the transactional email in the Loops app.

name string

The name of the transactional email.

draftEmailMessageId string

nullable

The ID of the draft email message. null if there is no draft version.

publishedEmailMessageId string

nullable

The ID of the published email message. null if there is no published version.

transactionalGroupId string

nullable

The ID of the group this transactional email belongs to.

createdAt string · date-time

ISO 8601 timestamp for when the transactional email was created.

updatedAt string · date-time

ISO 8601 timestamp for when the transactional email was last updated.

dataVariables array of string

Data variable names used by the published email. Empty for unpublished transactional emails.

1 field

items string

Invalid transactionalId.

TransactionalFailureResponseused by 7 operations

message string

Invalid API key or content API not enabled for this team.

Transactional email not found.

TransactionalFailureResponseused by 7 operations

message string

Wrong HTTP request method.

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "dataVariables": [
    "confirmationUrl"
  ],
  "draftEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "cll42l54f20i1la0lfooe3z12",
  "name": "Sign up confirmation",
  "publishedEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/transactional/cll42l54f20i1la0lfooe3z12"
}

400 Response

{
  "message": "Transactional email not found."
}

404 Response

{
  "message": "Transactional email not found."
}

Update a transactional email

POST /v1/transactional-emails/{transactionalId}

Requires apiKey — bearer

Update a transactional email by ID.

Path parameters

transactionalId string

The ID of the transactional email.

Request body UpdateTransactionalRequest

rules min properties 1

At least one field must be provided.

name string

transactionalGroupId string

The ID of the group to move this transactional email to.

Responses

200 400 401 404 405

Transactional email updated.

TransactionalResourceused by 4 operations

id string

The ID of the transactional email.

url string · uri

The URL of the transactional email in the Loops app.

name string

The name of the transactional email.

draftEmailMessageId string

nullable

The ID of the draft email message. null if there is no draft version.

publishedEmailMessageId string

nullable

The ID of the published email message. null if there is no published version.

transactionalGroupId string

nullable

The ID of the group this transactional email belongs to.

createdAt string · date-time

ISO 8601 timestamp for when the transactional email was created.

updatedAt string · date-time

ISO 8601 timestamp for when the transactional email was last updated.

dataVariables array of string

Data variable names used by the published email. Empty for unpublished transactional emails.

1 field

items string

Invalid request body or transactionalId.

TransactionalFailureResponseused by 7 operations

message string

Invalid API key or content API not enabled for this team.

Transactional email not found.

TransactionalFailureResponseused by 7 operations

message string

Wrong HTTP request method.

POST /v1/transactional-emails/{transactionalId}

{
  "name": "Password reset email",
  "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7"
}

Example generated from the schema

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "dataVariables": [
    "confirmationUrl"
  ],
  "draftEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "cll42l54f20i1la0lfooe3z12",
  "name": "Sign up confirmation",
  "publishedEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/transactional/cll42l54f20i1la0lfooe3z12"
}

400 Response

{
  "message": "Transactional email not found."
}

404 Response

{
  "message": "Transactional email not found."
}

Get transactional email metrics

GET /v1/transactional-emails/{transactionalId}/metrics

Requires apiKey — bearer

Retrieve all-time delivery metrics for a transactional email, totalled across every published version.

Path parameters

transactionalId string

The ID of the transactional email.

Responses

200 400 401 404 405

Successful.

TransactionalMetricsResponse

All-time delivery counters for a transactional email.

sends integer

Number of sends.

deliveries integer

Number of sends delivered.

spamReports integer

Number of sends reported as spam.

hardBounces integer

Number of sends that hard bounced.

softBounces integer

Number of sends that soft bounced.

Invalid transactionalId.

TransactionalFailureResponseused by 7 operations

message string

Invalid API key.

Transactional email not found.

TransactionalFailureResponseused by 7 operations

message string

Wrong HTTP request method.

200 Response

{
  "deliveries": 4175,
  "hardBounces": 9,
  "sends": 4210,
  "softBounces": 13,
  "spamReports": 1
}

400 Response

{
  "message": "Transactional email not found."
}

404 Response

{
  "message": "Transactional email not found."
}

Ensure a draft email message

POST /v1/transactional-emails/{transactionalId}/draft

Requires apiKey — bearer

Ensure the transactional email has a draft email message. If a draft already exists it is returned unchanged; otherwise a new empty draft is created (seeded from the most recent published version when present). Use POST /v1/email-messages/{emailMessageId} to edit the draft's content.

Path parameters

transactionalId string

The ID of the transactional email.

Responses

200 400 401 404 405

Draft ready.

TransactionalDraftResponseused by 2 operations

id string

The ID of the transactional email.

url string · uri

The URL of the transactional email in the Loops app.

name string

The name of the transactional email.

draftEmailMessageId string

nullable

The ID of the draft email message.

draftEmailMessageContentRevisionId string

nullable

The contentRevisionId of the draft email message. Pass this as expectedRevisionId on your first update via POST /v1/email-messages/{emailMessageId}.

publishedEmailMessageId string

nullable

The ID of the published email message. null if there is no published version.

transactionalGroupId string

nullable

The ID of the group this transactional email belongs to. Returned when creating a transactional email.

createdAt string · date-time

ISO 8601 timestamp for when the transactional email was created.

updatedAt string · date-time

ISO 8601 timestamp for when the transactional email was last updated.

dataVariables array of string

Data variable names used by the published email. Empty for unpublished transactional emails.

1 field

items string

Invalid transactionalId or no sending domain configured.

TransactionalFailureResponseused by 7 operations

message string

Invalid API key or content API not enabled for this team.

Transactional email not found.

TransactionalFailureResponseused by 7 operations

message string

Wrong HTTP request method.

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "dataVariables": [
    "confirmationUrl"
  ],
  "draftEmailMessageContentRevisionId": "clrev1s10n2i3d4e5f6g7h8",
  "draftEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "cll42l54f20i1la0lfooe3z12",
  "name": "Sign up confirmation",
  "publishedEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/transactional/cll42l54f20i1la0lfooe3z12"
}

400 Response

{
  "message": "Transactional email not found."
}

404 Response

{
  "message": "Transactional email not found."
}

Publish a transactional email draft

POST /v1/transactional-emails/{transactionalId}/publish

Requires apiKey — bearer

Publish the transactional email's current draft email message. The draft becomes the published version and the draft is cleared.

Path parameters

transactionalId string

The ID of the transactional email.

Responses

200 400 401 404 405 409 422

Transactional email published.

TransactionalResourceused by 4 operations

id string

The ID of the transactional email.

url string · uri

The URL of the transactional email in the Loops app.

name string

The name of the transactional email.

draftEmailMessageId string

nullable

The ID of the draft email message. null if there is no draft version.

publishedEmailMessageId string

nullable

The ID of the published email message. null if there is no published version.

transactionalGroupId string

nullable

The ID of the group this transactional email belongs to.

createdAt string · date-time

ISO 8601 timestamp for when the transactional email was created.

updatedAt string · date-time

ISO 8601 timestamp for when the transactional email was last updated.

dataVariables array of string

Data variable names used by the published email. Empty for unpublished transactional emails.

1 field

items string

Invalid transactionalId.

TransactionalFailureResponseused by 7 operations

message string

Invalid API key or content API not enabled for this team.

Transactional email not found.

TransactionalFailureResponseused by 7 operations

message string

Wrong HTTP request method.

No draft to publish.

TransactionalFailureResponseused by 7 operations

message string

Draft failed validation, sending domain is not verified, or content was flagged as unsafe.

TransactionalFailureResponseused by 7 operations

message string

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "dataVariables": [
    "confirmationUrl"
  ],
  "draftEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "id": "cll42l54f20i1la0lfooe3z12",
  "name": "Sign up confirmation",
  "publishedEmailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
  "transactionalGroupId": "clg7n5p3q1r9s7t5u3v1w9y7",
  "updatedAt": "2025-06-29T07:47:39.370Z",
  "url": "https://app.loops.so/transactional/cll42l54f20i1la0lfooe3z12"
}

400 Response

{
  "message": "Transactional email not found."
}

404 Response

{
  "message": "Transactional email not found."
}

409 Response

{
  "message": "Transactional email not found."
}

422 Response

{
  "message": "Transactional email not found."
}

Transactional groups

Organize transactional emails into groups

List transactional groups

GET /v1/transactional-groups

Requires apiKey — bearer

Retrieve a paginated list of transactional groups, most recently created first.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListGroupsResponseused by 3 operations

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of GroupResponse

1 field

items GroupResponse

5 fields

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid perPage value.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "createdAt": "2025-06-29T07:47:39.370Z",
      "description": "Top of funnel campaigns",
      "id": "clg7n5p3q1r9s7t5u3v1w9y7",
      "name": "Onboarding",
      "updatedAt": "2025-06-29T07:47:39.370Z"
    },
    {
      "createdAt": "2025-06-30T12:00:00.000Z",
      "description": "",
      "id": "clg8m4n6p8q0r2s4t6u8v0w2",
      "name": "Retention",
      "updatedAt": "2025-06-30T12:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

400 Response

{
  "message": "Group not found."
}

Create a transactional group

POST /v1/transactional-groups

Requires apiKey — bearer

Create a new transactional group.

Request body CreateGroupRequestused by 3 operations

name string

The group name. Cannot be the reserved name "Unsorted".

description string

An optional description for the group.

Responses

200 400 401 405

Transactional group created.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid request body or reserved group name.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

POST /v1/transactional-groups

{
  "description": "Monthly newsletter campaigns",
  "name": "Newsletters"
}

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

Get a transactional group

GET /v1/transactional-groups/{transactionalGroupId}

Requires apiKey — bearer

Retrieve a single transactional group by ID.

Path parameters

transactionalGroupId string

The ID of the transactional group.

Responses

200 400 401 404 405

Successful.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid transactionalGroupId.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Transactional group not found.

GroupFailureResponseused by 12 operations

message string

Wrong HTTP request method.

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

404 Response

{
  "message": "Group not found."
}

Update a transactional group

POST /v1/transactional-groups/{transactionalGroupId}

Requires apiKey — bearer

Update a transactional group's name or description. At least one field must be provided. The reserved "Unsorted" group cannot be edited.

Path parameters

transactionalGroupId string

The ID of the transactional group.

Request body UpdateGroupRequestused by 3 operations

At least one field must be provided.

name string

The group name. Cannot be the reserved name "Unsorted".

description string

A description for the group.

Responses

200 400 401 404 405

Transactional group updated.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid request body, reserved group name, or the Unsorted group cannot be edited.

GroupFailureResponseused by 12 operations

message string

Invalid API key or content API not enabled for this team.

Transactional group not found.

GroupFailureResponseused by 12 operations

message string

Wrong HTTP request method.

POST /v1/transactional-groups/{transactionalGroupId}

{
  "name": "string",
  "description": "string"
}

Example generated from the schema

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

404 Response

{
  "message": "Group not found."
}

Uploads

Upload image assets

Create an upload

POST /v1/uploads

Requires apiKey — bearer

Request a pre-signed URL to upload an image asset. Upload the file with an HTTP PUT to the returned presignedUrl (sending the same Content-Type and Content-Length), then call /uploads/{emailAssetId}/complete to finalize the asset.

Request body CreateUploadRequest

contentType string

The MIME type of the file to upload. Supported types are image/jpeg, image/png, image/gif and image/webp.

contentLength integer

The size of the file in bytes. Must be a positive integer no greater than 4,000,000 bytes.

Responses

200 400 401 405 413

Pre-signed upload URL created.

CreateUploadResponse

emailAssetId string

The ID of the created asset. Pass this as emailAssetId to POST /v1/uploads/{emailAssetId}/complete once the file has been uploaded.

presignedUrl string

The pre-signed URL to upload the file to with an HTTP PUT request. Send the same Content-Type and Content-Length used in the create request.

Invalid request body or unsupported contentType.

UploadFailureResponseused by 2 operations

message string

supportedContentTypes array of string

Present when the request was rejected for an unsupported contentType. Lists the accepted MIME types.

1 field

items string

maxBytes integer

Present when the upload exceeds the size limit. The maximum allowed size in bytes.

Invalid API key or content API not enabled for this team.

Wrong HTTP request method.

Upload exceeds the maximum allowed size.

UploadFailureResponseused by 2 operations

message string

supportedContentTypes array of string

Present when the request was rejected for an unsupported contentType. Lists the accepted MIME types.

1 field

items string

maxBytes integer

Present when the upload exceeds the size limit. The maximum allowed size in bytes.

POST /v1/uploads

{
  "contentType": "image/png",
  "contentLength": 102400
}

Example generated from the schema

200 Response

{
  "emailAssetId": "cla3s5s7e9t1i3d5f7g9h1j3",
  "presignedUrl": "https://loops-assets.s3.amazonaws.com/uploads/cla3s5s7e9t1i3d5f7g9h1j3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
}

400 Response

{
  "maxBytes": 4000000,
  "message": "Unsupported content type.",
  "supportedContentTypes": [
    "image/jpeg",
    "image/png",
    "image/gif",
    "image/webp"
  ]
}

413 Response

{
  "maxBytes": 4000000,
  "message": "Unsupported content type.",
  "supportedContentTypes": [
    "image/jpeg",
    "image/png",
    "image/gif",
    "image/webp"
  ]
}

Complete an upload

POST /v1/uploads/{emailAssetId}/complete

Requires apiKey — bearer

Finalize an image upload after the file has been uploaded to the pre-signed URL. Returns the public URL of the uploaded image asset.

Path parameters

emailAssetId string

The emailAssetId returned when the upload was created via POST /v1/uploads.

Responses

200 400 401 404 405 429

Upload completed.

CompleteUploadResponse

emailAssetId string

The ID of the created asset.

finalUrl string

The public URL of the uploaded asset.

Upload id is missing or the uploaded file has an unsupported content type.

UploadFailureResponseused by 2 operations

message string

supportedContentTypes array of string

Present when the request was rejected for an unsupported contentType. Lists the accepted MIME types.

1 field

items string

maxBytes integer

Present when the upload exceeds the size limit. The maximum allowed size in bytes.

Invalid API key or content API not enabled for this team.

Upload not found.

UploadFailureResponseused by 2 operations

message string

supportedContentTypes array of string

Present when the request was rejected for an unsupported contentType. Lists the accepted MIME types.

1 field

items string

maxBytes integer

Present when the upload exceeds the size limit. The maximum allowed size in bytes.

Wrong HTTP request method.

Upload limit exceeded.

UploadLimitExceededFailureResponse

message string

maxUploads integer

The maximum number of uploads allowed per window.

windowHours integer

The number of hours in the upload limit window.

200 Response

{
  "emailAssetId": "cla3s5s7e9t1i3d5f7g9h1j3",
  "finalUrl": "https://assets.loops.so/cla3s5s7e9t1i3d5f7g9h1j3/logo.png"
}

400 Response

{
  "maxBytes": 4000000,
  "message": "Unsupported content type.",
  "supportedContentTypes": [
    "image/jpeg",
    "image/png",
    "image/gif",
    "image/webp"
  ]
}

404 Response

{
  "maxBytes": 4000000,
  "message": "Unsupported content type.",
  "supportedContentTypes": [
    "image/jpeg",
    "image/png",
    "image/gif",
    "image/webp"
  ]
}

429 Response

{
  "message": "Upload limit exceeded: max 50 uploads per 24 hours. Please contact support if you need to increase your upload limit.",
  "maxUploads": 50,
  "windowHours": 24
}

Example generated from the schema

Workflows

View and mutate workflow graphs

List workflows

GET /v1/workflows

Requires apiKey — bearer

Retrieve a paginated list of workflows.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListWorkflowsResponse

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of WorkflowSummary

1 field

items WorkflowSummary

5 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

name string

The name of the workflow.

createdAt string · date-time

ISO 8601 timestamp for when the workflow was created.

updatedAt string · date-time

ISO 8601 timestamp for when the workflow was last updated.

Invalid perPage or cursor value.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "createdAt": "2025-06-29T07:47:39.370Z",
      "id": "clw1a3b5c7d9e1f3g5h7i9j1",
      "name": "Welcome series",
      "updatedAt": "2025-06-29T07:47:39.370Z",
      "url": "https://app.loops.so/workflows/clw1a3b5c7d9e1f3g5h7i9j1"
    }
  ],
  "pagination": {
    "nextCursor": "clp9k2m4n6p8q0r2s4t6u8v0",
    "nextPage": "https://app.loops.so/api/v1/workflows?cursor=clp9k2m4n6p8q0r2s4t6u8v0&perPage=20",
    "perPage": 20,
    "returnedResults": 20,
    "totalPages": 3,
    "totalResults": 45
  }
}

400 Response

{
  "message": "Workflow not found."
}

Create a workflow

POST /v1/workflows

Requires apiKey — bearer

Create a draft workflow with a blank trigger and exit node.

Request body CreateWorkflowRequest

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of a mailing list the workflow sends to. After creation, the mailing list can be changed with the /v1/workflows/{workflowId}/mailing-list endpoint.

Responses

200 400 401 405 500

Workflow created.

SimplifiedWorkflowused by 10 operations

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid request body.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Wrong HTTP request method.

Workflow creation is unavailable for this team.

WorkflowFailureResponseused by 14 operations

message string

POST /v1/workflows

{
  "name": "string",
  "description": "string",
  "mailingListId": "string"
}

Example generated from the schema

200 Response

{
  "description": "Onboarding emails for new signups",
  "id": "clw1a3b5c7d9e1f3g5h7i9j1",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "name": "Welcome series",
  "nodes": {
    "cln1a3b5c7d9e1f3g5h7i9j1": {
      "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
      "nextNodeIds": [],
      "subject": "Welcome to Acme!",
      "typeName": "SendEmailAction"
    },
    "cln8p0q2r4s6t8u0v2w4x6z8": {
      "nextNodeIds": [
        "cln1a3b5c7d9e1f3g5h7i9j1"
      ],
      "typeName": "SignupTrigger"
    }
  },
  "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
  "status": "Draft",
  "url": "https://app.loops.so/workflows/clw1a3b5c7d9e1f3g5h7i9j1"
}

400 Response

{
  "message": "Workflow not found."
}

500 Response

{
  "message": "Workflow not found."
}

Get a workflow

GET /v1/workflows/{workflowId}

Requires apiKey — bearer

Retrieve a workflow graph with node type names, connections, and selected display fields.

Path parameters

workflowId string

The ID of the workflow.

Responses

200 400 401 404 405

Successful.

SimplifiedWorkflowused by 10 operations

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid workflowId.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

200 Response

{
  "description": "Onboarding emails for new signups",
  "id": "clw1a3b5c7d9e1f3g5h7i9j1",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "name": "Welcome series",
  "nodes": {
    "cln1a3b5c7d9e1f3g5h7i9j1": {
      "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
      "nextNodeIds": [],
      "subject": "Welcome to Acme!",
      "typeName": "SendEmailAction"
    },
    "cln8p0q2r4s6t8u0v2w4x6z8": {
      "nextNodeIds": [
        "cln1a3b5c7d9e1f3g5h7i9j1"
      ],
      "typeName": "SignupTrigger"
    }
  },
  "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
  "status": "Draft",
  "url": "https://app.loops.so/workflows/clw1a3b5c7d9e1f3g5h7i9j1"
}

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

Update a workflow

POST /v1/workflows/{workflowId}

Requires apiKey — bearer

Update a workflow's display properties. At least one property must be provided. To change the workflow's mailing list, use the POST /v1/workflows/{workflowId}/mailing-list endpoint instead.

Path parameters

workflowId string

The ID of the workflow.

Request body UpdateWorkflowPropertiesRequest

At least one property must be provided.

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

name string

The updated workflow name.

description string

The updated workflow description.

any of · 1

any of · 2

Responses

200 400 401 404 405 409

Workflow properties updated.

SimplifiedWorkflowused by 10 operations

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid workflowId or request body.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

POST /v1/workflows/{workflowId}

null

Example generated from the schema

200 Response

{
  "description": "Onboarding emails for new signups",
  "id": "clw1a3b5c7d9e1f3g5h7i9j1",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "name": "Welcome series",
  "nodes": {
    "cln1a3b5c7d9e1f3g5h7i9j1": {
      "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
      "nextNodeIds": [],
      "subject": "Welcome to Acme!",
      "typeName": "SendEmailAction"
    },
    "cln8p0q2r4s6t8u0v2w4x6z8": {
      "nextNodeIds": [
        "cln1a3b5c7d9e1f3g5h7i9j1"
      ],
      "typeName": "SignupTrigger"
    }
  },
  "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
  "status": "Draft",
  "url": "https://app.loops.so/workflows/clw1a3b5c7d9e1f3g5h7i9j1"
}

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

Delete a workflow

DELETE /v1/workflows/{workflowId}

Requires apiKey — bearer

Delete a workflow. Successful deletion returns 204 No Content. If the workflow is currently sending or has queued contacts, Loops returns 409 Conflict with a message instead of deleting. Retry with confirmDelete: true to delete the workflow, stop sending, and cancel queued contacts.

Path parameters

workflowId string

The ID of the workflow.

Request body DeleteWorkflowRequest

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

confirmDelete boolean

Set to true after a confirmation-required 409 Conflict response to confirm deleting a sending workflow or a workflow with queued contacts.

Responses

204 400 401 404 405 409

Workflow deleted. No response body.

Invalid workflowId, request body, or delete target.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow not found. Deleted workflows are returned as not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale, or workflow deletion requires confirmation because the workflow is currently sending or has queued contacts.

WorkflowFailureResponseused by 14 operations

message string

DELETE /v1/workflows/{workflowId}

{
  "expectedRevisionId": "string",
  "confirmDelete": false
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "workflowRevisionId mismatch. Latest workflowRevisionId is clx7a3b5c7d9e1f3g5h7i9j1. Refetch and retry."
}

Change workflow mailing list

POST /v1/workflows/{workflowId}/mailing-list

Requires apiKey — bearer

Dry run or apply a workflow mailing list change. If queued contacts would be removed from the workflow due to the change of mailing list, Loops returns with "status": "queuedContactsFound" instead of applying the change. Retry with queuedContactPolicy: "discard" to apply the change and discard those contacts. Confirmed update responses include the simplified workflow after the mailing list changes.

Path parameters

workflowId string

The ID of the workflow.

Request body ChangeWorkflowMailingListRequest

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

mailingListId string

nullable

The mailing list to use for the workflow. When assigning a mailing list, queued contacts excluded by the new list can return queuedContactsFound; retry with queuedContactPolicy: "discard" to apply the change and discard those contacts. Use null to clear the workflow mailing list; clearing does not discard queued contacts.

dryRun boolean

If true, the request will be validated but the workflow will not be modified.

queuedContactPolicy WorkflowQueuedContactPolicy

fail returns queued-contact impact instead of mutating. discard confirms that matching queued contacts should be discarded. Defaults to fail when omitted.

enum faildiscard

default fail

Responses

200 400 401 404 405 409

Mailing-list dry run, queued-contact warning, or update result. Confirmed update responses include the simplified workflow after the mailing list changes.

ChangeWorkflowMailingListResponse

one of · 1 WorkflowMailingListPreview

3 fields

status string

enum dryRunqueuedContactsFound

mailingListId string

nullable

queuedContactCount number

The number of queued contacts that would be removed from the workflow due to the mailing list changing.

one of · 2 WorkflowMailingListUpdatedResponse

5 fields

status string

enum updated

mailingListId string

nullable

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

queuedContactCount number

The number of queued contacts that were removed from the workflow due to the mailing list changing.

workflow SimplifiedWorkflow

9 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid workflowId, request body, mailing list, or workflow state.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

POST /v1/workflows/{workflowId}/mailing-list

{
  "expectedRevisionId": "string",
  "mailingListId": "string",
  "dryRun": false,
  "queuedContactPolicy": "fail"
}

Example generated from the schema

200 Response

{
  "status": "dryRun",
  "mailingListId": "string",
  "queuedContactCount": 0
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

Workflow groups

Organize workflows into groups

List workflow groups

GET /v1/workflow-groups

Requires apiKey — bearer

Retrieve a paginated list of workflow groups, most recently created first.

Query parameters

perPage string

How many results to return in each request. Must be between 10 and 50. Default is 20.

cursor string

A cursor to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response.

Responses

200 400 401 405

Successful.

ListGroupsResponseused by 3 operations

pagination Pagination

6 fields

totalResults number

returnedResults number

perPage number

totalPages number

nextCursor string

nullable

nextPage string

nullable

data array of GroupResponse

1 field

items GroupResponse

5 fields

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid perPage value.

GroupFailureResponseused by 12 operations

message string

Invalid API key.

Wrong HTTP request method.

200 Response

{
  "data": [
    {
      "createdAt": "2025-06-29T07:47:39.370Z",
      "description": "Top of funnel campaigns",
      "id": "clg7n5p3q1r9s7t5u3v1w9y7",
      "name": "Onboarding",
      "updatedAt": "2025-06-29T07:47:39.370Z"
    },
    {
      "createdAt": "2025-06-30T12:00:00.000Z",
      "description": "",
      "id": "clg8m4n6p8q0r2s4t6u8v0w2",
      "name": "Retention",
      "updatedAt": "2025-06-30T12:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "nextPage": null,
    "perPage": 20,
    "returnedResults": 2,
    "totalPages": 1,
    "totalResults": 2
  }
}

400 Response

{
  "message": "Group not found."
}

Create a workflow group

POST /v1/workflow-groups

Requires apiKey — bearer

Create a new workflow group.

Request body CreateGroupRequestused by 3 operations

name string

The group name. Cannot be the reserved name "Unsorted".

description string

An optional description for the group.

Responses

200 400 401 405

Workflow group created.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid request body or reserved group name.

GroupFailureResponseused by 12 operations

message string

Invalid API key.

Wrong HTTP request method.

POST /v1/workflow-groups

{
  "description": "Monthly newsletter campaigns",
  "name": "Newsletters"
}

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

Get a workflow group

GET /v1/workflow-groups/{workflowGroupId}

Requires apiKey — bearer

Retrieve a single workflow group by ID.

Path parameters

workflowGroupId string

The ID of the workflow group.

Responses

200 400 401 404 405

Successful.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid workflowGroupId.

GroupFailureResponseused by 12 operations

message string

Invalid API key.

Workflow group not found.

GroupFailureResponseused by 12 operations

message string

Wrong HTTP request method.

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

404 Response

{
  "message": "Group not found."
}

Update a workflow group

POST /v1/workflow-groups/{workflowGroupId}

Requires apiKey — bearer

Update a workflow group's name or description. At least one field must be provided. The reserved "Unsorted" group cannot be edited.

Path parameters

workflowGroupId string

The ID of the workflow group.

Request body UpdateGroupRequestused by 3 operations

At least one field must be provided.

name string

The group name. Cannot be the reserved name "Unsorted".

description string

A description for the group.

Responses

200 400 401 404 405

Workflow group updated.

GroupResponseused by 12 operations

id string

The ID of the group.

name string

The name of the group.

description string

The description of the group.

createdAt string · date-time

ISO 8601 timestamp for when the group was created.

updatedAt string · date-time

ISO 8601 timestamp for when the group was last updated.

Invalid request body, reserved group name, or the Unsorted group cannot be edited.

GroupFailureResponseused by 12 operations

message string

Invalid API key.

Workflow group not found.

GroupFailureResponseused by 12 operations

message string

Wrong HTTP request method.

POST /v1/workflow-groups/{workflowGroupId}

{
  "name": "string",
  "description": "string"
}

Example generated from the schema

200 Response

{
  "createdAt": "2025-06-29T07:47:39.370Z",
  "description": "Top of funnel campaigns",
  "id": "clg7n5p3q1r9s7t5u3v1w9y7",
  "name": "Onboarding",
  "updatedAt": "2025-06-29T07:47:39.370Z"
}

400 Response

{
  "message": "Group not found."
}

404 Response

{
  "message": "Group not found."
}

Workflow nodes

View and mutate workflow nodes

Create a workflow node

POST /v1/workflows/{workflowId}/nodes

Requires apiKey — bearer

Create a new default workflow node and return it with the latest workflow.

Choose where the node goes with insertMode: between places it between an existing fromNodeId -> toNodeId connection, before places it before toNodeId, and after places it after fromNodeId when that node has exactly one outgoing connection. after is a convenience for simple linear paths, so callers do not need to fetch and pass the current child node ID. It is invalid when fromNodeId has no outgoing nodes, multiple outgoing nodes, or is an exit node. When the source has multiple outgoing nodes, use between with the exact toNodeId instead. For before, deprecated beforeNodeId requests are still accepted for compatibility, but new callers should use toNodeId.

New nodes start with default settings; update the node after creation to configure it. Branch nodes create their default paths too: BranchNode creates two AudienceFilter children, and ExperimentBranchNode creates two regular VariantNode children plus one control VariantNode. Public workflows can have up to 400 nodes. Generated children count toward that limit, so a normal create adds 1 node, BranchNode adds 3, and ExperimentBranchNode adds 4. To add a sibling child path to a branch or experiment branch, use the POST /v1/workflows/{workflowId}/nodes/{nodeId}/add-branch endpoint. Branch paths can be edited with create-node, but a workflow cannot be started unless each direct BranchNode child is an AudienceFilter. For experiments, use create-node only to insert a missing VariantNode before non-variant content; use add-branch for another variant path.

Path parameters

workflowId string

The ID of the workflow.

Request body CreateWorkflowNodeRequest

Create a new workflow node with an explicit insertMode. To configure the node after creation, use the POST /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

one of · 1 CreateWorkflowNodeBetweenRequest

Insert a new node between two existing nodes, fromNodeId and toNodeId. When fromNodeId is an ExperimentBranchNode, nodeTypeName must be VariantNode, and toNodeId cannot already be a VariantNode; use add-branch to add sibling variants. Branch paths can be edited with create-node, but a workflow cannot be started unless each direct BranchNode child is an AudienceFilter.

5 fields

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

insertMode string

enum between

nodeTypeName CreateWorkflowNodeTypeName

Node types that can be created with the API. *Trigger nodes and ExitAction nodes cannot be created.

enum AudienceFilterBranchNodeExperimentBranchNodeTimerActionSendEmailActionVariantNode

fromNodeId string

The node to insert after. This node must currently point to toNodeId. If this is an ExperimentBranchNode, nodeTypeName must be VariantNode and toNodeId cannot already be a VariantNode.

toNodeId string

The node to insert before.

one of · 2 CreateWorkflowNodeBeforeRequest

Insert a new node before toNodeId. VariantNode cannot use insertMode: "before"; to restore a missing variant path, use insertMode: "between" with the experiment branch as fromNodeId.

7 fields

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

insertMode string

enum before

nodeTypeName CreateWorkflowNodeTypeName

Node types that can be created with the API. *Trigger nodes and ExitAction nodes cannot be created.

enum AudienceFilterBranchNodeExperimentBranchNodeTimerActionSendEmailActionVariantNode

toNodeId string

The node to insert before. The target must have at least one incoming parent and cannot be a trigger node.

beforeNodeId string

deprecated

Deprecated. Use toNodeId instead.

one of · 1 object

1 field

toNodeId string

one of · 2 object

1 field

beforeNodeId string

deprecated

one of · 3 CreateWorkflowNodeAfterRequest

Insert a new node after fromNodeId. This is valid only when fromNodeId has exactly one outgoing node. It is invalid when fromNodeId has no outgoing nodes, multiple outgoing nodes, or is an exit node. When the source has multiple outgoing nodes, use between with the exact toNodeId instead.

4 fields

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

insertMode string

enum after

nodeTypeName CreateWorkflowNodeTypeName

Node types that can be created with the API. *Trigger nodes and ExitAction nodes cannot be created.

enum AudienceFilterBranchNodeExperimentBranchNodeTimerActionSendEmailActionVariantNode

fromNodeId string

The node to insert after. This node must currently have exactly one outgoing node.

Responses

200 400 401 404 405 409

Workflow node created.

CreateWorkflowNodeResponse

node CreatedWorkflowNode

2 fields

createdChildNodes array of WorkflowMutationNode

Default child nodes created along with the requested node. BranchNode creation returns two AudienceFilter children. ExperimentBranchNode creation returns two regular VariantNode children and one control VariantNode.

1 field

items WorkflowMutationNode

Detailed workflow node returned from create and update mutations. The exact fields depend on typeName.

12 fields

one of · 1 SignupTriggerWorkflowMutationNode

3 fields

id string

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 EventTriggerWorkflowMutationNode

6 fields

id string

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

The name of the event pattern that triggers this node.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 ContactPropertyTriggerWorkflowMutationNode

5 fields

id string

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 AddToListTriggerWorkflowMutationNode

5 fields

id string

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list this trigger sends to, if set.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 BlankTriggerWorkflowMutationNode

3 fields

id string

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 AudienceFilterWorkflowMutationNode

6 fields

id string

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

audienceSegmentId string

The ID of the audience segment this trigger targets.

appliesDownstream boolean

If true, the audience filter will apply to all downstream nodes. If false, the audience filter will only apply to the current node. Matches the "Filter scope" option in the UI.

one of · 7 TimerActionWorkflowMutationNode

5 fields

id string

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SendEmailActionWorkflowMutationNode

5 fields

id string

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

one of · 9 ExitActionWorkflowMutationNode

3 fields

id string

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 BranchWorkflowMutationNode

3 fields

id string

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 ExperimentBranchWorkflowMutationNode

4 fields

id string

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch. 100 sends all contacts to variant branches.

one of · 12 VariantWorkflowMutationNode

4 fields

id string

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

all of WorkflowMutationNodeWithRevision

Detailed workflow node returned from a mutation, plus the latest workflow revision token.

12 fields

one of · 1 SignupTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 2 EventTriggerWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

The name of the event pattern that triggers this node.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 3 ContactPropertyTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 4 AddToListTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list this trigger sends to, if set.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 5 BlankTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 6 AudienceFilterWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

audienceSegmentId string

The ID of the audience segment this trigger targets.

appliesDownstream boolean

If true, the audience filter will apply to all downstream nodes. If false, the audience filter will only apply to the current node. Matches the "Filter scope" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 7 TimerActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 8 SendEmailActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 9 ExitActionWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 10 BranchWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 11 ExperimentBranchWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch. 100 sends all contacts to variant branches.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 12 VariantWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

workflow SimplifiedWorkflow

9 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid request. Details will be shown in message.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

POST /v1/workflows/{workflowId}/nodes

{
  "expectedRevisionId": "string",
  "insertMode": "between",
  "nodeTypeName": "AudienceFilter",
  "fromNodeId": "string",
  "toNodeId": "string"
}

Example generated from the schema

200 Response

{
  "node": {
    "createdChildNodes": [
      {
        "id": "string",
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "string"
        ]
      }
    ]
  },
  "workflow": {
    "id": "clw1a3b5c7d9e1f3g5h7i9j1",
    "url": "https://app.loops.so/workflows/clw1a3b5c7d9e1f3g5h7i9j1",
    "status": "Draft",
    "name": "Welcome series",
    "description": "Onboarding emails for new signups",
    "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
    "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
    "nodes": {
      "cln8p0q2r4s6t8u0v2w4x6z8": {
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "cln1a3b5c7d9e1f3g5h7i9j1"
        ]
      },
      "cln1a3b5c7d9e1f3g5h7i9j1": {
        "typeName": "SendEmailAction",
        "nextNodeIds": [],
        "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
        "subject": "Welcome to Acme!"
      }
    }
  }
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

Add a branch

POST /v1/workflows/{workflowId}/nodes/{nodeId}/add-branch

Requires apiKey — bearer

Add a branch and a child node under an existing Branch or Experiment node. Returns the created child node plus the latest workflow.

Adding a branch to a BranchNode creates one AudienceFilter child node.
Adding a branch to an ExperimentBranchNode creates one VariantNode child node.

This endpoint does not accept node configuration fields; update the child node with POST /v1/workflows/{workflowId}/nodes/{nodeId} after creation. Public workflows are limited to 400 nodes, and this endpoint adds 1 node.

Path parameters

workflowId string

The ID of the workflow.

nodeId string

The ID of the BranchNode or ExperimentBranchNode that should receive one new child.

Request body AddWorkflowBranchRequest

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

Responses

200 400 401 404 405 409

Branch added.

AddWorkflowBranchResponse

node WorkflowMutationNodeWithRevision

Detailed workflow node returned from a mutation, plus the latest workflow revision token.

12 fields

one of · 1 SignupTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 2 EventTriggerWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

The name of the event pattern that triggers this node.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 3 ContactPropertyTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 4 AddToListTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list this trigger sends to, if set.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 5 BlankTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 6 AudienceFilterWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

audienceSegmentId string

The ID of the audience segment this trigger targets.

appliesDownstream boolean

If true, the audience filter will apply to all downstream nodes. If false, the audience filter will only apply to the current node. Matches the "Filter scope" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 7 TimerActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 8 SendEmailActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 9 ExitActionWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 10 BranchWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 11 ExperimentBranchWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch. 100 sends all contacts to variant branches.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 12 VariantWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

workflow SimplifiedWorkflow

9 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid workflowId, nodeId, request body, branch target, workflow state, or workflow node cap.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

POST /v1/workflows/{workflowId}/nodes/{nodeId}/add-branch

{
  "expectedRevisionId": "string"
}

Example generated from the schema

200 Response

{
  "node": {
    "id": "string",
    "typeName": "SignupTrigger",
    "nextNodeIds": [
      "string"
    ],
    "workflowRevisionId": "string"
  },
  "workflow": {
    "id": "clw1a3b5c7d9e1f3g5h7i9j1",
    "url": "https://app.loops.so/workflows/clw1a3b5c7d9e1f3g5h7i9j1",
    "status": "Draft",
    "name": "Welcome series",
    "description": "Onboarding emails for new signups",
    "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
    "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
    "nodes": {
      "cln8p0q2r4s6t8u0v2w4x6z8": {
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "cln1a3b5c7d9e1f3g5h7i9j1"
        ]
      },
      "cln1a3b5c7d9e1f3g5h7i9j1": {
        "typeName": "SendEmailAction",
        "nextNodeIds": [],
        "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
        "subject": "Welcome to Acme!"
      }
    }
  }
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

Get a workflow node

GET /v1/workflows/{workflowId}/nodes/{nodeId}

Requires apiKey — bearer

Retrieve detailed data for a single workflow node.

Path parameters

workflowId string

The ID of the workflow.

nodeId string

The ID of the workflow node.

Responses

200 400 401 404 405

Successful.

WorkflowNodeWithRevision

Detailed workflow node returned from read operations. The exact fields depend on typeName.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

all of WorkflowNode

12 fields

one of · 1 SignupTriggerWorkflowNode

4 fields

id string

workflowId string

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 EventTriggerWorkflowNode

7 fields

id string

workflowId string

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

The name of the event pattern that triggers this node.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 ContactPropertyTriggerWorkflowNode

6 fields

id string

workflowId string

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 AddToListTriggerWorkflowNode

6 fields

id string

workflowId string

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 BlankTriggerWorkflowNode

4 fields

id string

workflowId string

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 AudienceFilterWorkflowNode

7 fields

id string

workflowId string

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

audienceSegmentId string

appliesDownstream boolean

If true, the audience filter will apply to all downstream nodes. If false, the audience filter will only apply to the current node. Matches the "Filter scope" option in the UI.

one of · 7 TimerActionWorkflowNode

6 fields

id string

workflowId string

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SendEmailActionWorkflowNode

6 fields

id string

workflowId string

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

one of · 9 ExitActionWorkflowNode

4 fields

id string

workflowId string

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 BranchWorkflowNode

4 fields

id string

workflowId string

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 ExperimentBranchWorkflowNode

5 fields

id string

workflowId string

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch. 100 sends all contacts to variant branches.

one of · 12 VariantWorkflowNode

5 fields

id string

workflowId string

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid workflowId or nodeId.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

200 Response

{
  "workflowRevisionId": "string"
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

Update a workflow node

POST /v1/workflows/{workflowId}/nodes/{nodeId}

Requires apiKey — bearer

Update workflow-node-owned fields for a single node. Shared resources such as email messages and audience segments should be updated through their own APIs.

Path parameters

workflowId string

The ID of the workflow.

nodeId string

The ID of the workflow node.

Request body UpdateWorkflowNodeRequest

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

payload UpdateWorkflowNodePayload

Node-type-specific fields to update. The allowed fields depend on the existing node type. Trigger node updates may include typeName when changing one trigger node type to another trigger node type.

8 fields

any of · 1 WorkflowSignupTriggerPayload

Changes an existing trigger node to a signup trigger.

1 field

typeName string

enum SignupTrigger

any of · 2 WorkflowEventTriggerPayload

Updates an event trigger, or changes an existing trigger node to an event trigger. Assign the event pattern with either eventPatternId or eventName, not both. Set either field to null to clear the event-pattern relationship.

rules min properties 1

4 fields

typeName string

enum EventTrigger

eventPatternId string

nullable

The ID of the event pattern to trigger on. Use either eventPatternId or eventName, not both. Set to null to clear the event-pattern relationship.

eventName string

nullable

The name of the event pattern to trigger on. Use this when you know the event name but not the internal event pattern ID. Use either eventName or eventPatternId, not both. Set to null to clear the event-pattern relationship.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

any of · 3 WorkflowContactPropertyTriggerPayload

Updates a contact-property trigger, or changes an existing trigger node to a contact-property trigger.

rules min properties 1

3 fields

typeName string

enum ContactPropertyTrigger

contactPropertyQuery WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

any of · 4 WorkflowAddToListTriggerPayload

Updates an add-to-list trigger, or changes an existing trigger node to an add-to-list trigger.

rules min properties 1

2 fields

typeName string

enum AddToListTrigger

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

any of · 5 WorkflowAudienceFilterPayload

Configuration for the audience filter node.

rules min properties 1

3 fields

audienceSegmentId string

nullable

The ID of an audience segment. Setting this without also providing audienceFilter clears any existing audienceFilter. If both are provided, the filter is applied on top of the segment's filter.

audienceFilter AudienceFilterInRequest

nullable

A tree of audience conditions combined with match. Setting this without also providing audienceSegmentId clears any existing audienceSegmentId. When both are provided, this filter is applied on top of the segment's filter.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

appliesDownstream boolean

If true, the audience filter will apply to all downstream nodes. If false, the audience filter will only apply to the current node. Matches the "Filter scope" option in the UI.

any of · 6 WorkflowTimerActionPayload

Configuration for the timer action node.

rules min properties 1

2 fields

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

any of · 7 WorkflowExperimentBranchPayload

Configuration for the experiment branch node.

rules min properties 1

1 field

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch. 100 sends all contacts to variant branches.

any of · 8 WorkflowVariantPayload

Configuration for the variant node.

rules min properties 1

1 field

isControl boolean

Use true to set this variant as the control of the experiment. This will set false on the existing control, if one exists. Experiments do not require a control variant.

Responses

200 400 401 404 405 409 501

Workflow node updated.

UpdateWorkflowNodeResponse

The updated workflow node, plus the latest simplified workflow.

workflow SimplifiedWorkflow

9 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

all of WorkflowMutationNodeWithRevision

Detailed workflow node returned from a mutation, plus the latest workflow revision token.

12 fields

one of · 1 SignupTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 2 EventTriggerWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

The name of the event pattern that triggers this node.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 3 ContactPropertyTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 4 AddToListTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list this trigger sends to, if set.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 5 BlankTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 6 AudienceFilterWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

audienceSegmentId string

The ID of the audience segment this trigger targets.

appliesDownstream boolean

If true, the audience filter will apply to all downstream nodes. If false, the audience filter will only apply to the current node. Matches the "Filter scope" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 7 TimerActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 8 SendEmailActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 9 ExitActionWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 10 BranchWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 11 ExperimentBranchWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch. 100 sends all contacts to variant branches.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 12 VariantWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

Invalid workflowId, nodeId, request body, or node update.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

This node update is not implemented.

WorkflowFailureResponseused by 14 operations

message string

POST /v1/workflows/{workflowId}/nodes/{nodeId}

{
  "expectedRevisionId": "string",
  "payload": {
    "typeName": "SignupTrigger"
  }
}

Example generated from the schema

200 Response

{
  "workflow": {
    "id": "clw1a3b5c7d9e1f3g5h7i9j1",
    "url": "https://app.loops.so/workflows/clw1a3b5c7d9e1f3g5h7i9j1",
    "status": "Draft",
    "name": "Welcome series",
    "description": "Onboarding emails for new signups",
    "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
    "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
    "nodes": {
      "cln8p0q2r4s6t8u0v2w4x6z8": {
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "cln1a3b5c7d9e1f3g5h7i9j1"
        ]
      },
      "cln1a3b5c7d9e1f3g5h7i9j1": {
        "typeName": "SendEmailAction",
        "nextNodeIds": [],
        "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
        "subject": "Welcome to Acme!"
      }
    }
  }
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

501 Response

{
  "message": "Workflow not found."
}

Delete a workflow node

DELETE /v1/workflows/{workflowId}/nodes/{nodeId}

Requires apiKey — bearer

Delete a single workflow node. If contacts are queued at the node, Loops returns with "status": "queuedContactsFound" instead of deleting. Retry with queuedContactPolicy: "discard" to delete the node and discard those queued contacts. Confirmed deletion responses include the simplified workflow after the node is removed.

Path parameters

workflowId string

The ID of the workflow.

nodeId string

The ID of the workflow node.

Request body DeleteWorkflowNodeRequestused by 2 operations

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

dryRun boolean

If true, the request will be validated but the workflow will not be modified.

queuedContactPolicy WorkflowQueuedContactPolicy

fail returns queued-contact impact instead of mutating. discard confirms that matching queued contacts should be discarded. Defaults to fail when omitted.

enum faildiscard

default fail

Responses

200 400 401 404 405 409

Delete dry run, queued-contact warning, or deletion result. Confirmed deletion responses include the simplified workflow after the node is removed.

DeleteWorkflowNodeResponseused by 2 operations

one of · 1 WorkflowQueuedContactDeletePreview

3 fields

status string

enum dryRunqueuedContactsFound

nodeIds array of string

The IDs of the nodes that would be deleted.

1 field

items string

queuedContactCount number

The number of queued contacts that would be removed from the workflow due to the node deletion.

one of · 2 WorkflowDeletedResponse

5 fields

status string

enum deleted

nodeIds array of string

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

queuedContactCount number

The number of queued contacts that were removed from the workflow due to the node deletion.

workflow SimplifiedWorkflow

9 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid workflowId, nodeId, request body, or delete target.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

DELETE /v1/workflows/{workflowId}/nodes/{nodeId}

{
  "expectedRevisionId": "string",
  "dryRun": false,
  "queuedContactPolicy": "fail"
}

Example generated from the schema

200 Response

{
  "status": "dryRun",
  "nodeIds": [
    "string"
  ],
  "queuedContactCount": 0
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

Get workflow node metrics

GET /v1/workflows/{workflowId}/nodes/{nodeId}/metrics

Requires apiKey — bearer

Retrieve all-time email engagement metrics for a workflow SendEmailAction node. Nodes of any other type return a 400 response. A SendEmailAction node with an email that has not sent anything yet reports every counter as 0.

Path parameters

workflowId string

The ID of the workflow.

nodeId string

The ID of the SendEmailAction node.

Responses

200 400 401 404 405

Successful.

EmailMetricsResponseused by 2 operations

All-time email engagement counters. Opens and clicks count sends, not events: a send opened five times counts once. A recipient who received the email twice is counted once per send, not once per person.

sends integer

Number of sends.

opens integer

Number of sends that were opened at least once.

clicks integer

Number of sends where at least one link was clicked.

unsubscribes integer

Number of unsubscribes.

spamReports integer

Number of sends reported as spam.

hardBounces integer

Number of sends that hard bounced.

softBounces integer

Number of sends that soft bounced.

Invalid workflowId or nodeId, the node is not a SendEmailAction node, or the node has no email message.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

200 Response

{
  "clicks": 301,
  "hardBounces": 9,
  "opens": 1922,
  "sends": 4210,
  "softBounces": 13,
  "spamReports": 1,
  "unsubscribes": 12
}

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

Reroute a node connection

POST /v1/workflows/{workflowId}/nodes/{nodeId}/reroute

Requires apiKey — bearer

Reroute the source node's existing connection to another valid target node. Returns the updated source node and the latest workflow.

Path parameters

workflowId string

The ID of the workflow.

nodeId string

The ID of the source workflow node whose outgoing connection should be moved.

Request body RerouteNodeConnectionRequest

Reroute the source node's only outgoing connection to newTargetNodeId.

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

newTargetNodeId string

The valid workflow node that should receive the connection from the source node.

Responses

200 400 401 404 405 409

Node connection rerouted.

RerouteNodeConnectionResponse

The updated source node, plus the latest workflow.

workflow SimplifiedWorkflow

9 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

all of WorkflowMutationNodeWithRevision

Detailed workflow node returned from a mutation, plus the latest workflow revision token.

12 fields

one of · 1 SignupTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 2 EventTriggerWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

The name of the event pattern that triggers this node.

eventProperties array of WorkflowEventProperty

The properties of the event pattern, which can be used in emails.

1 field

items WorkflowEventProperty

2 fields

name string

type string

enum stringnumberbooleandate

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 3 ContactPropertyTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 4 AddToListTriggerWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list this trigger sends to, if set.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 5 BlankTriggerWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 6 AudienceFilterWorkflowMutationNodeWithRevision

7 fields

id string

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

audienceFilter AudienceFilter

nullable

A tree of audience conditions combined with match.

2 fields

match string

enum allany

conditions array of AudienceFilterCondition

rules min items 1

1 field

items AudienceFilterCondition

3 fields

one of · 1 PropertyCondition

Matches contacts by a property value.

4 fields

type string

enum property

key string

The contact property name.

operator string

enum anycontainsnotContainsequalsnotEqualsgreaterThanlessThanisTrueisFalseemptynotEmptydateEmptydateNotEmptyafterbeforebetween

value one of

The comparison value. Omitted for value-less operators (e.g. isTrue, empty). A { from, to } object for between.

3 fields

one of · 1 string

one of · 2 number

one of · 3 object

2 fields

from string · date-time

to string · date-time

one of · 2 OptInCondition

Matches contacts by mailing list opt-in status.

2 fields

type string

enum optIn

status string

nullable

enum acceptedpendingrejectednull

one of · 3 ActivityCondition

Matches contacts by their activity on a campaign or workflow.

5 fields

type string

enum activity

action string

enum sentopenedclicked

negate boolean

target string

enum campaignworkflowworkflowEmail

id string

The ID of the campaign, workflow, or workflow email.

audienceSegmentId string

The ID of the audience segment this trigger targets.

appliesDownstream boolean

If true, the audience filter will apply to all downstream nodes. If false, the audience filter will only apply to the current node. Matches the "Filter scope" option in the UI.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 7 TimerActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 8 SendEmailActionWorkflowMutationNodeWithRevision

6 fields

id string

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 9 ExitActionWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 10 BranchWorkflowMutationNodeWithRevision

4 fields

id string

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 11 ExperimentBranchWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch. 100 sends all contacts to variant branches.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

one of · 12 VariantWorkflowMutationNodeWithRevision

5 fields

id string

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

Invalid workflowId, nodeId, request body, node connection selection, reroute target, or workflow state.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

POST /v1/workflows/{workflowId}/nodes/{nodeId}/reroute

{
  "expectedRevisionId": "clx7a3b5c7d9e1f3g5h7i9j1",
  "newTargetNodeId": "cln3c5d7e9f1g3h5i7j9k1l3"
}

200 Response

{
  "id": "cln8p0q2r4s6t8u0v2w4x6z8",
  "nextNodeIds": [
    "cln3c5d7e9f1g3h5i7j9k1l3"
  ],
  "typeName": "SignupTrigger",
  "workflow": {
    "description": "Onboarding emails for new signups",
    "id": "clw1a3b5c7d9e1f3g5h7i9j1",
    "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
    "name": "Welcome series",
    "nodes": {
      "cln1a3b5c7d9e1f3g5h7i9j1": {
        "nextNodeIds": [
          "cln3c5d7e9f1g3h5i7j9k1l3"
        ],
        "typeName": "AudienceFilter"
      },
      "cln3c5d7e9f1g3h5i7j9k1l3": {
        "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
        "nextNodeIds": [],
        "subject": "Welcome to Acme!",
        "typeName": "SendEmailAction"
      },
      "cln8p0q2r4s6t8u0v2w4x6z8": {
        "nextNodeIds": [
          "cln3c5d7e9f1g3h5i7j9k1l3"
        ],
        "typeName": "SignupTrigger"
      }
    },
    "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
    "status": "Draft",
    "workflowRevisionId": "clx7a3b5c7d9e1f3g5h7i9j2"
  },
  "workflowRevisionId": "clx7a3b5c7d9e1f3g5h7i9j2"
}

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

Delete workflow nodes recursively

DELETE /v1/workflows/{workflowId}/nodes/{nodeId}/recursive

Requires apiKey — bearer

Delete a node and its downstream subtree. If contacts are queued at any node that would be deleted, Loops returns with "status": "queuedContactsFound" instead of deleting. Retry with queuedContactPolicy: "discard" to delete the nodes and discard those queued contacts. Confirmed deletion responses include the simplified workflow after the nodes are removed.

Path parameters

workflowId string

The ID of the workflow.

nodeId string

The root node ID of the subtree to delete.

Request body DeleteWorkflowNodeRequestused by 2 operations

expectedRevisionId WorkflowExpectedRevisionId

nullable

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

dryRun boolean

If true, the request will be validated but the workflow will not be modified.

queuedContactPolicy WorkflowQueuedContactPolicy

fail returns queued-contact impact instead of mutating. discard confirms that matching queued contacts should be discarded. Defaults to fail when omitted.

enum faildiscard

default fail

Responses

200 400 401 404 405 409

Delete dry run, queued-contact warning, or deletion result. Confirmed deletion responses include the simplified workflow after the nodes are removed.

DeleteWorkflowNodeResponseused by 2 operations

one of · 1 WorkflowQueuedContactDeletePreview

3 fields

status string

enum dryRunqueuedContactsFound

nodeIds array of string

The IDs of the nodes that would be deleted.

1 field

items string

queuedContactCount number

The number of queued contacts that would be removed from the workflow due to the node deletion.

one of · 2 WorkflowDeletedResponse

5 fields

status string

enum deleted

nodeIds array of string

1 field

items string

workflowRevisionId WorkflowRevisionId

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation.

queuedContactCount number

The number of queued contacts that were removed from the workflow due to the node deletion.

workflow SimplifiedWorkflow

9 fields

id string

The ID of the workflow.

url string · uri

The URL of the workflow in the Loops app.

workflowRevisionId NullableWorkflowRevisionId

nullable

The current workflow revision token. Pass the latest value as expectedRevisionId on the next workflow mutation. Will be null for workflows without a revision token yet.

status string

enum DraftSendingPausedPausedAndQueueing

name string

The name of the workflow.

description string

The description of the workflow.

mailingListId string

nullable

The ID of the mailing list the workflow sends to.

rootNodeId string

The ID of the root node in the workflow graph.

nodes object

A map of node IDs to simplified node objects. Each node includes typeName and nextNodeIds, plus type-specific fields when present. To get the full node object, use the GET /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

1 field

additional properties SimplifiedWorkflowNode

12 fields

one of · 1 SimplifiedSignupTriggerWorkflowNode

2 fields

typeName string

enum SignupTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 2 SimplifiedEventTriggerWorkflowNode

4 fields

typeName string

enum EventTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

eventName string

nullable

The name of the event that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 3 SimplifiedContactPropertyTriggerWorkflowNode

4 fields

typeName string

enum ContactPropertyTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

contactPropertyQuery one of

2 fields

one of · 1 WorkflowContactPropertyQuery

Define the contact property change that triggers the workflow. In update requests, key must resolve to an existing contact property that is available for Contact Updated triggers. Hidden or unsupported fields, such as createdAt, notes, and computed contact properties, are rejected.

3 fields

key string

The camel-cased key of the contact property to query. The property must exist for the team and must be available for Contact Updated triggers.

is WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

was WorkflowContactPropertyComparison

Comparison for the new contact property value after the update.

one of · 2

nullable

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 4 SimplifiedAddToListTriggerWorkflowNode

4 fields

typeName string

enum AddToListTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

mailingListId string

nullable

The ID of the mailing list that triggers the workflow.

reEligible WorkflowReEligible

If true, the contacts will be able to enter this workflow every time the trigger is matched. If false, contacts will only ever enter this workflow once. Matches the "Trigger frequency" option in the UI.

one of · 5 SimplifiedBlankTriggerWorkflowNode

2 fields

typeName string

enum BlankTrigger

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 6 SimplifiedAudienceFilterWorkflowNode

2 fields

typeName string

enum AudienceFilter

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 7 SimplifiedTimerActionWorkflowNode

4 fields

typeName string

enum TimerAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

amount WorkflowTimerAmount

The amount of time to wait before triggering the next node. Set to 0 to move to the next node immediately.

unit WorkflowTimerUnit

The unit of time for the timer action node. m = minutes, h = hours, d = days.

enum mhd

one of · 8 SimplifiedSendEmailActionWorkflowNode

4 fields

typeName string

enum SendEmailAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

emailMessageId string

nullable

The ID of the email message to send. To edit this email, use the POST /v1/email-messages/{emailMessageId} endpoint.

subject string

The subject of the email message (reference only).

one of · 9 SimplifiedExitActionWorkflowNode

2 fields

typeName string

enum ExitAction

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 10 SimplifiedBranchWorkflowNode

2 fields

typeName string

enum BranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

one of · 11 SimplifiedExperimentBranchWorkflowNode

3 fields

typeName string

enum ExperimentBranchNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

samplingRate number

The percentage of contacts that will be sent to variant branches, between 0 and 100. The remaining percentage will be sent to the control branch.

one of · 12 SimplifiedVariantWorkflowNode

3 fields

typeName string

enum VariantNode

nextNodeIds WorkflowNextNodeIds

The IDs of the nodes that are downstream of this node.

1 field

items string

isControl boolean

Whether this is the control variant of an experiment.

Invalid workflowId, nodeId, request body, or delete target.

WorkflowFailureResponseused by 14 operations

message string

Invalid API key.

Workflow or workflow node not found.

WorkflowFailureResponseused by 14 operations

message string

Wrong HTTP request method.

expectedRevisionId is stale.

WorkflowFailureResponseused by 14 operations

message string

DELETE /v1/workflows/{workflowId}/nodes/{nodeId}/recursive

{
  "expectedRevisionId": "string",
  "dryRun": false,
  "queuedContactPolicy": "fail"
}

Example generated from the schema

200 Response

{
  "status": "dryRun",
  "nodeIds": [
    "string"
  ],
  "queuedContactCount": 0
}

Example generated from the schema

400 Response

{
  "message": "Workflow not found."
}

404 Response

{
  "message": "Workflow not found."
}

409 Response

{
  "message": "Workflow not found."
}

Loops OpenAPI Spec

Servers

Authentication

API key

Responses

Audience segments

Path parameters

Responses

Query parameters

Responses

Request body CreateAudienceSegmentRequest

Responses

Campaigns

Query parameters

Responses

Request body CreateCampaignRequest

Responses

Path parameters

Responses

Path parameters

Request body UpdateCampaignRequest

Responses

Path parameters

Responses

Campaign groups

Query parameters

Responses

Request body CreateGroupRequestused by 3 operations

Responses

Path parameters

Responses

Path parameters

Request body UpdateGroupRequestused by 3 operations

Responses

Configuration

Responses

Contacts

Request body ContactRequest

Responses

Request body ContactUpdateRequest

Responses

Query parameters

Responses

Request body ContactDeleteRequest

Responses

Query parameters

Responses

Query parameters

Responses

Contact properties

Query parameters

Responses

Request body ContactPropertyCreateRequest

Responses

Components

Path parameters

Responses

Path parameters

Request body UpdateComponentBody

Responses

Query parameters

Responses

Request body CreateComponentBody

Responses

Email messages

Path parameters

Responses

Path parameters

Request body UpdateEmailMessageRequest

Responses

Path parameters

Request body EmailMessagePreviewRequest

Responses

Path parameters

Responses

Events

Header parameters

Request body EventRequest

Responses

Event patterns