ASDinCloudDocs
API ReferenceCampaigns

The campaign object

View as Markdown

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.

List campaigns

View as Markdown
GET/api/v1/campaigns

Lists 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.

Retrieve a campaign

View as Markdown
GET/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.

Create a campaign

View as Markdown
POST/api/v1/campaigns

Creates 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.

Update a campaign

View as Markdown
PATCH / PUT / POST/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.

Delete a campaign

View as Markdown
DELETE/api/v1/campaigns/{id}
POST/api/v1/campaigns/{id}/delete

Removes 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.

Clone a campaign

View as Markdown
POST/api/v1/campaigns/{id}/clone

Copies 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.

Preview a sent campaign

View as Markdown
GET/api/v1/campaigns/{id}/preview

Returns 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.

List campaign recipients

View as Markdown
GET/api/v1/campaigns/{id}/recipients

Lists 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.

Build a campaign recipient list

View as Markdown
POST/api/v1/campaigns/{id}/build-recipients

Replaces 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.

Schedule a campaign

View as Markdown
POST/api/v1/campaigns/{id}/send

Schedules 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.

Pause a campaign

View as Markdown
POST/api/v1/campaigns/{id}/pause

Pauses 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.

Send a campaign test email

View as Markdown
POST/api/v1/campaigns/{id}/send-test

Sends 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.