Campaigns
View as MarkdownCampaigns send an email to a prepared list of recipients. Use the campaign endpoints to prepare content, build the recipient list, and schedule delivery.
On this page
- The campaign object
- List campaignsGET
/api/v1/campaigns - Retrieve a campaignGET
/api/v1/campaigns/{id} - Create a campaignPOST
/api/v1/campaigns - Update a campaignPATCH / PUT / POST
/api/v1/campaigns/{id} - Delete a campaignDELETE
/api/v1/campaigns/{id}POST/api/v1/campaigns/{id}/delete - Clone a campaignPOST
/api/v1/campaigns/{id}/clone - Preview a sent campaignGET
/api/v1/campaigns/{id}/preview - List campaign recipientsGET
/api/v1/campaigns/{id}/recipients - Build a campaign recipient listPOST
/api/v1/campaigns/{id}/build-recipients - Schedule a campaignPOST
/api/v1/campaigns/{id}/send - Pause a campaignPOST
/api/v1/campaigns/{id}/pause - Send a campaign test emailPOST
/api/v1/campaigns/{id}/send-test
Campaigns send an email to a prepared list of recipients. Use the campaign endpoints to prepare content, build the recipient list, and schedule delivery.
Attributes
idinteger- Identifier assigned by the API.
sport_idinteger- ID of the sport.
namestring- Campaign name, up to 255 characters.
subjectstring- Email subject, up to 255 characters. Defaults to an empty string on creation.
track_opensboolean- Whether to collect email open counts.
template_idinteger or null- ID of a saved email template. Use this or supply campaign content.
body_htmlstring or null- Campaign HTML.
body_jsonmap or JSON string- Structured content with a blocks array. Blocks use an id and type. Supported types are heading, paragraph, image, spacer, and separator.
recipient_configmap or null- Configuration recorded when building the recipient list.
statusstring- Current state: draft, ready, scheduled, sending, sent, or cancelled.
scheduled_atinteger or null- Scheduled send time as Unix seconds.
started_atinteger or null- Time sending started, in Unix seconds.
finished_atinteger or null- Time sending finished, in Unix seconds.
recipientsinteger- Number of campaign recipients.
open_countinteger- Number of recipients recorded as opening the email when tracking is enabled.
open_ratenumber- Percentage of recipients recorded as opening the email.
/api/v1/campaignsLists campaign records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Read.
Headers
X-Sport-Idinteger- Use the sport ID to limit the response to one sport.
Query parameters
typestring- Use email for email campaigns. The sms filter returns an empty list.
qstring- Search by campaign name.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, tsc, or tsu. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
Returns
Returns matching campaigns and recipient and open metrics in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
/api/v1/campaigns/{id}Returns one campaign by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Returns
The campaign is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/campaignsCreates a campaign.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Body parameters
typestring- Email campaigns are supported.
namestringRequired- Campaign name, up to 255 characters.
subjectstring- Email subject, up to 255 characters. Defaults to an empty string on creation.
track_opensboolean- Whether to collect email open counts.
template_idinteger or null- ID of a saved email template. Use this or supply campaign content.
body_htmlstring or null- Campaign HTML.
body_jsonmap or JSON string- Structured content with a blocks array. Blocks use an id and type. Supported types are heading, paragraph, image, spacer, and separator.
To provide content, choose a template or supply a body. The campaign starts in draft.
Returns
The created campaign is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
422- One or more fields failed validation.
/api/v1/campaigns/{id}Updates a campaign by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Body parameters
namestring- Campaign name, up to 255 characters.
subjectstring- Email subject, up to 255 characters. Defaults to an empty string on creation.
track_opensboolean- Whether to collect email open counts.
template_idinteger or null- ID of a saved email template. Use this or supply campaign content.
body_htmlstring or null- Campaign HTML.
body_jsonmap or JSON string- Structured content with a blocks array. Blocks use an id and type. Supported types are heading, paragraph, image, spacer, and separator.
Pause a scheduled campaign before editing it.
Returns
Returns a successful update response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
409- The campaign's current state does not allow this operation.
422- One or more fields failed validation.
/api/v1/campaigns/{id}/api/v1/campaigns/{id}/deleteRemoves a campaign before sending begins. Pause a scheduled campaign first.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Returns
Returns a successful removal response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The campaign could not be removed.
409- The campaign's current state does not allow this operation.
/api/v1/campaigns/{id}/cloneCopies the content and recipient list into a new draft campaign.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Returns
Returns the new draft and its recipient count in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
422- One or more fields failed validation.
500- The campaign operation could not be completed.
/api/v1/campaigns/{id}/previewReturns the subject and rendered HTML of a sent campaign.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Returns
Returns the subject and HTML in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
409- The campaign's current state does not allow this operation.
/api/v1/campaigns/{id}/recipientsLists recipient activity for a sent campaign.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Query parameters
eventstring- Use all, the default, or opened for tracked opens.
startinteger- Zero-based offset. Defaults to 0.
lengthinteger- Page size from 1 to 100. Defaults to 25.
qstring- Search recipient name or email.
Returns
Returns matching recipients with send and open times in Unix seconds. The counts are before and after text search.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
409- The campaign has not been sent or open tracking is disabled for the opened filter.
422- One or more fields failed validation.
/api/v1/campaigns/{id}/build-recipientsReplaces the campaign's recipient list. Sources can include entered addresses, team members, or contacts from lists.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Body parameters
custom_emailsarray of strings- Email addresses to add directly.
team_idsarray of integers- Team IDs in the selected sport. Supply include when using teams.
list_idsarray of integers- Contact list IDs in the selected sport. Use lists or teams.
includemap- When using teams, set one or more of athletes, parents, coaches, or staff to true.
Supply at least one recipient source. Custom addresses can be combined with teams or lists.
Returns
Returns the updated configuration, total recipients, and counts for sources and skipped addresses.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
409- The campaign's current state does not allow this operation.
422- The input contains incompatible sources or no eligible recipients.
500- The campaign operation could not be completed.
/api/v1/campaigns/{id}/sendSchedules a prepared campaign for immediate or future delivery.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Body parameters
scheduled_atinteger, string, or null- Use a future Unix timestamp in seconds, now, or null. Omission schedules immediate delivery.
Use Build a campaign recipient list before scheduling.
Returns
Returns the current campaign and queue status. Delivery is asynchronous.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
409- The campaign's current state does not allow this operation.
422- The campaign is not ready, it has no recipients, or the scheduled time is invalid.
500- The campaign operation could not be completed.
/api/v1/campaigns/{id}/pausePauses a scheduled campaign and returns it to draft.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Returns
Returns the campaign with its cleared schedule and current recipient count.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
409- The campaign's current state does not allow this operation.
500- The campaign operation could not be completed.
/api/v1/campaigns/{id}/send-testSends a test copy to the supplied email addresses. The campaign keeps its current state.
Permissions
Send your API key in X-API-Key. Required permissions are Campaigns → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the campaign.
Body parameters
emailsarray of strings or stringRequired- One or more email addresses. A string can use commas or newlines.
Returns
Returns the number of successful and failed sends, plus the failed addresses.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
422- The addresses are invalid or the campaign content is incomplete.
500- The campaign operation could not be completed.
502- All test sends failed.