Messages
View as MarkdownMessages are workspace communication records. You can create a draft, send it by email, or send an email directly.
On this page
- The message object
- List messagesGET
/api/v1/messages - Retrieve a messageGET
/api/v1/messages/{id} - Create a messagePOST
/api/v1/messages - Update a messagePATCH / PUT / POST
/api/v1/messages/{id} - Delete a messageDELETE
/api/v1/messages/{id}POST/api/v1/messages/{id}/delete - Send an existing messagePOST
/api/v1/messages/{id}/send - Send a new emailPOST
/api/v1/messages/send
Messages are workspace communication records. You can create a draft, send it by email, or send an email directly.
Attributes
idinteger- Identifier assigned by the API.
channelstring- Communication channel, email or sms.
statusstring- Current processing or delivery status.
emailstring- Recipient email address.
phonestring or null- Recipient phone number.
subjectstring- Email subject, up to 255 characters.
bodystring- Message body. For email, supply the HTML content.
athlete_idinteger or null- ID of the associated athlete.
parent_idinteger or null- ID of the associated parent.
staff_idinteger or null- ID of the associated staff member or coach.
metadatamap or null- Structured message details.
sent_atinteger or null- Unix timestamp in seconds, when available.
delivered_atinteger or null- Unix timestamp in seconds, when available.
read_atinteger or null- Unix timestamp in seconds, when available.
clicked_atinteger or null- Unix timestamp in seconds, when available.
recipient_namestring- Recipient display name. Included when listing messages.
recipient_typestring- Recipient category. Included when listing messages.
source_typestring- Message source. Included when listing messages.
tscinteger or null- Creation time as a Unix timestamp in seconds.
tsuinteger or null- Last update time as a Unix timestamp in seconds.
/api/v1/messagesLists message records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Messages → Read.
Query parameters
channelstring- Filter by email or sms.
statusstring or array- Filter by one status or several comma-separated statuses.
emailstring- Recipient email address.
phonestring- Filter by exact phone number.
athlete_idinteger or null- ID of the associated athlete.
parent_idinteger or null- ID of the associated parent.
staff_idinteger or null- ID of the associated staff member or coach.
coach_idinteger- Filter by coach. Takes precedence over staff_id.
qstring- Search text, subject, or recipient contact details.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, tsc, tsu, channel, status, sent_at, delivered_at, read_at, or clicked_at. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
Returns
Returns records in data, counts before and after text search, and the echoed draw marker.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
/api/v1/messages/{id}Returns one message by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Messages → Read.
Path parameters
idintegerRequired- ID of the message.
Returns
The message 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/messagesCreates a message.
Permissions
Send your API key in X-API-Key. Required permissions are Messages → Write.
Body parameters
channelstring- Use email or sms. Defaults to email when omitted from a write.
statusstring- Use queued, sent, failed, delivered, opened, or clicked. Defaults to queued when omitted from a write.
emailstring- Recipient email address.
phonestring or null- Recipient phone number.
subjectstring- Email subject, up to 255 characters.
bodystringRequired- Message body. For email, supply the HTML content.
athlete_idinteger or null- ID of the associated athlete.
parent_idinteger or null- ID of the associated parent.
staff_idinteger or null- ID of the associated staff member or coach.
ccstring- Copy addresses separated by commas or semicolons. Alias email_cc.
send_copy_to_clubboolean- Copy the club email. Alias copy_to_club. Defaults to false for new messages.
metadatamap or null- Structured message details.
Use the send endpoint to deliver a queued email.
Returns
The created message is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The body must be a JSON object.
422- One or more fields failed validation.
/api/v1/messages/{id}Updates a message by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Messages → Write.
Path parameters
idintegerRequired- ID of the message.
Body parameters
channelstring- Use email or sms. Defaults to email when omitted from a write.
statusstring- Use queued, sent, failed, delivered, opened, or clicked. Defaults to queued when omitted from a write.
emailstring- Recipient email address.
phonestring or null- Recipient phone number.
subjectstring- Email subject, up to 255 characters.
bodystring- Message body. For email, supply the HTML content.
athlete_idinteger or null- ID of the associated athlete.
parent_idinteger or null- ID of the associated parent.
staff_idinteger or null- ID of the associated staff member or coach.
ccstring- Copy addresses separated by commas or semicolons. Alias email_cc.
send_copy_to_clubboolean- Copy the club email. Alias copy_to_club. Defaults to false for new messages.
metadatamap or null- Structured message details.
Send the current channel and status to preserve them. Otherwise they default to email and queued.
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.
400- The body must be a JSON object.
422- One or more fields failed validation.
/api/v1/messages/{id}/api/v1/messages/{id}/deleteRemoves a message record.
Permissions
Send your API key in X-API-Key. Required permissions are Messages → Write.
Path parameters
idintegerRequired- ID of the message.
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 message could not be removed.
/api/v1/messages/{id}/sendSends an existing queued or failed email. The optional body can override the stored subject, content, and copy recipients.
Permissions
Send your API key in X-API-Key. Required permissions are Messages → Write.
Path parameters
idintegerRequired- ID of the message.
Body parameters
subjectstring- Email subject, up to 255 characters.
bodystring- HTML body. Alias body_html.
ccstring- Copy addresses separated by commas or semicolons. Alias email_cc.
send_copy_to_clubboolean- Copy the club email. Alias copy_to_club. Defaults to false for new messages.
Check the per-recipient results before retrying when a request reports a failed delivery.
Returns
Returns one result for each recipient with the address, role, message ID, and status.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The email cannot be sent in its current state, or delivery failed for a recipient.
404- The requested record was not found.
422- The club copy was requested but the club email is unavailable.
/api/v1/messages/sendSends an email immediately and records one message per recipient.
Permissions
Send your API key in X-API-Key. Required permissions are Messages → Write.
Body parameters
emailstringRequired- Recipient email address.
subjectstring- Email subject, up to 255 characters.
bodystringRequired- HTML body. Alias body_html.
ccstring- Copy addresses separated by commas or semicolons. Alias email_cc.
send_copy_to_clubboolean- Copy the club email. Alias copy_to_club. Defaults to false for new messages.
athlete_idinteger or null- ID of the associated athlete.
parent_idinteger or null- ID of the associated parent.
staff_idinteger or null- ID of the associated staff member or coach.
Returns
Returns one result for each recipient. If some recipients fail, the error response still includes the recipient results in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- Required fields are missing or delivery failed for one or more recipients.
422- The club copy was requested but the club email is unavailable.