ASDinCloudDocs

The message object

View as Markdown

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.

List messages

View as Markdown
GET/api/v1/messages

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

Retrieve a message

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

Create a message

View as Markdown
POST/api/v1/messages

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

Update a message

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

Delete a message

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

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

Send an existing message

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

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

Send a new email

View as Markdown
POST/api/v1/messages/send

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