Overview
The Batch Messages resource sends a message, or schedules a message to be sent, as a one-time communication. It contains details on content, channel, send trigger, type of communication (transactional or promotional), subject line, from and reply addresses, and HTML.
Additional information
- When creating a batch message, you have the option to send it on command, or to queue it for a later date and time.
- Sending is a two part process that involves a POST method to create the message and a PUT method to schedule or send the message.
- When a batch message is created via the POST method, it is placed into a "draft" status by default. This enables editing and subsequent modifications to the message, as well as deleting the batch message.
- It is important to note that the PUT method is required to activate the sending or scheduling of the message using its "id" (provided back in the response of the POST).
- Example: PUT <path>/batchmessages/{id}/send'
- If there is a "schedule" date, then the "status" changes to "scheduled"'
- If there is no "schedule" date, then the message is immediately queued and the "status" is changed to "pending".
- In either case, as soon as sending begins, the "status" will change to "processing" and then to "sent" once complete.
- The GET /batchmessages call is also used to retrieve info on daily Automation sends.
Methods, parameters, and examples
POST/batchmessages
Method | URI Path |
---|---|
POST | /batchmessages |
Creates a batch message template in the Cordial database using the appropriate JSON body.
Posting more than one time will cause subsequent batch messages to be created. Use PUT to change or update a batch message that has not yet sent. |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
MessageSend | |||
*channel | string | Messaging channel key (e.g. email, sms, push). Note that some of your channels may have custom keys. | |
*classification | string | If applicable, classifies the message as transactional or promotional. | transactional |
name | string | An optional name given to the message. | Jan_Newsletter_2018 |
tags | array | An array of string values to identify and categorize the message. Tags are case sensitive. | ["birthday","promo"] |
audience-key | string | Defines a saved audience rule "name". | 30_day_engaged |
schedule | date | An optional date and time at which the message is to be sent. The date should be in the future and use the ISO 8601 format. | 2018-01-09T22:47:12+0000 |
scheduleType | string | Enable sending at the scheduled time per the time zone of the contact. If not specified, the template will send using the Cordial account default time zone. | contactTZ |
transportID | string | Defines the transportID if overriding the default. Default is used if this parameter is not included. | 57d098b66c8766fd53ad19d7 |
trackLinks | string | Determines if link performance will be tracked. Default is enabled. Possible Values: enabled, disabled |
enabled |
Message/Headers | |||
*subject | string | The subject line for the communication. | Welcome to myco! |
*fromEmail | string | The email address that the message is from. | email@myco.io |
*fromDesc | string | Describes the sender. | CS Dept |
*replyEmail | string | The email address that the message's replies will go to. | email@example.com |
Message/Content | |||
*text/html | string | HTML markup for the message. | <div>content</div> |
tests (array) | |||
type | String | Defines the test to be run. | 250ok |
enabled | Boolean | Flag to determine if the test is enabled or disabled. The default is disabled. | true |
Example JSON requests
The following will create and schedule a new batch message for a promotional email to all contacts using the default transport. The response will include an "id" for the newly created batchmessages instance.
{ "sendtrigger": "manual",
"channel": "email", "classification": "promotional", "name": "promo_01_20_2018", "schedule": "2018-01-2316:10:08", "scheduleType": "contactTZ", "message": { "headers": { "subject": "Buyoneticketandgetsecondhalfprice", "fromEmail": "skiguy@example.com", "replyEmail": "skiguy@example.com", "fromDesc": "SkiPromotionsTeam" }, "content": { "text/html": "<div>Some Content</div>" } }, "transportID": "57d098b66c8766fd53ad19d7", "trackLinks": "enabled", "tests": [{ "type": "250ok", "enabled": true }] }
Example request URI
The following URI in conjunction with the JSON will perform the POST of batchmessages.
http://<path>/batchmessages
GET /batchmessages
Method | URI Path |
---|---|
GET | /batchmessages |
Retrieves all batch messages from the Cordial database. Note that info and stats on daily Automation sends is retrieved using the GET /batchmessages call. You are able to filter the response for automation sends using the triggers parameter, the creation time or mdtID. |
Query string parameters
Parameter | Type | Description | Example |
---|---|---|---|
sendTime[gt] | string | Returns records where the send time is greater than the specified date. |
?sendTime[gt]=2018-01-01T00:00:00.000Z |
sendTime[gte] | string | Returns records where the send time is greater than or equal to the specified date. |
?sendTime[gte]=2018-01-01T00:00:00.000Z |
sendTime[lt] | string | Returns records where the send time is less than the specified date. |
?sendTime[lt]=2018-01-01T00:00:00.000Z |
sendTime[lte] | string | Returns records where the send time is less than or equal to the specified date. |
?sendTime[lte]=2018-01-01T00:00:00.000Z |
status | string | The message status. Possible Values: sent, cancelled, paused, sending |
?status=paused |
triggers[api][enabled] | string | For Automation sends: filters results based on whether the API trigger is enabled or disabled. Possible Values: true, false |
?triggers[api][enabled]=true |
triggers[event][enabled] | string | For Automation sends: filters results based on whether the event trigger is enabled or disabled. Possible Values: true, false |
?triggers[event][enabled]=true |
triggers[recurring][enabled] | string | For Automation sends: filters results based on whether the recurring trigger is enabled or disabled. Possible Values: true, false |
?triggers[recurring][enabled]=true |
tags | string | Returns results that contain the specified message tags. |
?tags=welcome |
mdtID | string | The automation template ID. |
?mdtID=591f1a26ac0c811781bf44ea |
ct[gt] | string | Returns records where the create date is greater than the specified date. |
?ct[gt]=2018-01-01T00:00:00.000Z |
ct[gte] | string | Returns records where the create date is greater than or equal to the specified date. |
?ct[gte]=2018-01-01T00:00:00.000Z |
ct[lt] | string | Returns records where the create date is less than the specified date. |
?ct[lt]=2018-01-01T00:00:00.000Z |
ct[lte] | string | Returns records where the create date is less than or equal to the specified date. |
?ct[lte]=2018-01-01T00:00:00.000Z |
page | string | Specifies the results page number to be returned. |
?page=3 |
per_page | string | Specifies the number of records returned per page. |
?per_page=100 |
sort_by | string | Specifies the field to sort by. |
?sort_by=sendTime |
sort_dir | string | Specifies the sort direction as ascending or descending. Possible Values: desc, asc |
?sort_dir=desc |
Example request URIs
The following URI will retrieve all batch messages.
http://<path>/batchmessages
The following URI will retrieve all batch messages, starting from the third page and grouping messages by 10. For example, page-1 would have included the first 10, page-2 the second group of 10 and so on.
http://<path>/batchmessages?page=3&per_page=10
PUT /batchmessages/{id}
Method | URI Path |
---|---|
PUT | /batchmessages/{id} |
Updates an unsent batch message in the Cordial database using the appropriate JSON body.
The batch message's record is defined by the batch messages's unique "id" value (generated by the POST method). The PUT method can only be used if the "status" is "draft". |
Parameters
See the parameters for POST/batchmessages above.
Example JSON requests
The following will change the "subject" and push the launch "schedule" date by one day.
{ "status": "", "sendtrigger": "manual", "classification": "promotional", "name": "promo_01_20_2018", "schedule": "2018-01-24 16:10:08", "scheduleType": "contactTZ", "message": { "headers": { "subject": "Buy one ticket and get the second half price", "fromEmail": "skiguy@example.com", "replyEmail": "skiguy@example.com", "fromDesc": "Ski Promotions Team" }, "content": { "text/html": "<div>Some Content</div>" } }, "transportID": "account transportID", "trackLinks": "enabled" }
Example request URI
The following URI in conjunction with the JSON will perform the PUT of the batch message with the "id" of "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot
GET /batchmessages/{id}
Method | URI Path |
---|---|
GET | /batchmessages/{id} |
Retrieves a batch message from the Cordial database.
The batch message's record is defined by the batch message's unique "id" value. |
Example request URI
The following URI will retrieve a batch message where the "id" value is "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot
DELETE /batchmessages/{id}
Method | URI Path |
---|---|
DELETE | /batchmessages/{id} |
Deletes a batch message within the Cordial database.
The batch message is defined by the batch messages's unique "id" value. |
Example request URI
The following URI will delete a batch message where the "id" value is "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot
PUT /batchmessages/{id}/send
Method | URI Path |
---|---|
PUT | /batchmessages/{id}/send |
Sends or schedules a batch message within the Cordial database.
The batch message record is defined by the batch message's unique "id" value. |
Example request URI
The following URI perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/send
PUT /batchmessages/{id}/sendtest
Method | URI Path |
---|---|
PUT | /batchmessages/{id}/sendtest |
Sends a test batch message.
The batchmessages record is defined by the batchmessages's unique "id" value. |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
*contact identifier | array | An array of contact identifier values to receive the test message. | [ "test1@example.com","test2@example.com" ] |
Example JSON requests
-
{ "email": [ "test1@example.com","test2@example.com" ] }
-
{ "cID": [ "58d30719ac0c8117814da1f3","39f67345aq0c0276295da1g9" ] }
-
{ "customKey": [ "identifierValue1","identifierValue2" ] }
Example request URI
The following URI in conjunction with the JSON will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/sendtest
GET /batchmessages/{id}/renderedwip/{contactID}
Method | URI Path |
---|---|
GET | /batchmessages/{id}/renderedwip/{contactID} |
Retrieves the message headers, the rendered HTML, and the experiment name and variants of a batch message draft for a specified contact from the Cordial database. |
Query string parameters
Parameter | Type | Description | Example |
---|---|---|---|
experiment | string | Name of experiment. |
?experiment=SubjectTest |
variant | string | Variant name. |
?variant=Test1 |
Example request URIs
The following URI will perform the GET to the batch message where:
- Message ID = 252:594ac3d2f0c360031181a7f0:ot
- Contact ID = 58d30719ac0c8117814da1f3
http://<path>/batchmessages/252:594ac3d2f0c360031181a7f0:ot/renderedwip/58d30719ac0c8117814da1f3
The following URI will perform the GET to the batch message where:
- Message ID = 252:594ac3d2f0c360031181a7f0:ot
- Contact ID = 58d30719ac0c8117814da1f3
- Subject experiment = SubjectTest
- Subject experiment Variant = Test1
http://<path>/batchmessages/252:594ac3d2f0c360031181a7f0:ot/renderedwip/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=Test1
The following URI will perform the GET to the batch message where:
- Message ID = 252:594ac3d2f0c360031181a7f0:ot
- Contact ID = 58d30719ac0c8117814da1f3
- Subject experiment = SubjectTest
- Subject experiment Variant = Test1
- Body experiment = AB-No-Champ
- Body experiment variant = B
http://<path>/batchmessages/252:594ac3d2f0c360031181a7f0:ot/renderedwip/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=Test1&experiment=AB-No-Champ&variant=B
PUT /batchmessages/{id}/pause
Method | URI Path |
---|---|
PUT | /batchmessages/{id}/pause |
Pauses the sending of a batch message.
The batch message record is defined by the batch message's unique "id" value. |
Example request URI
The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/pause
PUT /batchmessages/{id}/resume
Method | URI Path |
---|---|
PUT | /batchmessages/{id}/resume |
Resumes the sending of a batch message.
The batch message record is defined by the batch message's unique "id" value. |
Example request URI
The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/resume
PUT /batchmessages/{id}/cancel
Method | URI Path |
---|---|
PUT | /batchmessages/{id}/cancel |
Cancels the sending of a batch message. A paused message may also be canceled.
The batch message record is defined by the batch message's unique "id" value. |
Example request URI
The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/cancel
PUT /batchmessages/{id}/unschedule
Method | URI Path |
---|---|
PUT | /batchmessages/{id}/unschedule |
Unschedule a scheduled batch message. Unscheduled messages will revert to draft status and can be edited. Messages that are in the processing status cannot be unscheduled ("Unable to unschedule message" notification will be returned).
The batch message record is defined by the batch message's unique "id" value. |
Example request URI
The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/unschedule
Error responses
The Cordial API will return an error object with an errorKey
and message
if there is a problem with an API call. Below is a list of errors specific to the Batch Messages API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API error responses page.
errorKey | Message | Modifications |
---|---|---|
CHANNELS_KEY_NOT_FOUND | Incorrect channel for current account | The provided channel is not present for the current account. |
CHANNELS_KEY_NOT_FOUND | Channel is not detected | Check that the messaging channel key was input correctly. |
BATCH_MESSAGES_SMS_TRANSACTIONAL_MESSAGES_NOT_ALLOWED | Transactional messages are not allowed for messages of type sms. | SMS messages must be classified as promotional. |
BATCH_MESSAGES_AUDIENCE_FILTER_CONFLICT | Please use only one from existing filters 'audience' OR 'audience-key' | Either audience or audience-key may be used to filter, but not both. |
MESSAGE_TRANSPORT_NOT_CONFIGURED | Transport must be configured before messages can be created | Ensure the transport has been configured and input correctly. |
BATCH_MESSAGES_AUDIENCE_NOT_FOUND | Audience with name: ':audienceKey' does not exist. | The given audience was not found. |
BATCH_MESSAGES_TEST_INTEGRATION_DISABLED | Integrations is disabled | The integration setting has been set to disabled. |
BATCH_MESSAGES_INSUFFICIENT_TEST_PARAMETERS | Not enough parameters for tests | Check that both Tests parameters are correctly filled in. |
BATCH_MESSAGES_TEST_INTEGRATION_ERROR | Error data from 250OK integration | Check the integration data. |
BATCH_MESSAGES_CANNOT_EDIT_SENT_MESSAGE | Can't be changed | A sent message cannot be edited. |
MESSAGE_TRANSPORT_NOT_SELECTED | Transport should be selected before sending | Ensure the transport has been selected properly. |
BATCH_MESSAGES_REMOVE_REQUEST_NOT_ALLOWED | It's not allowed to remove this message. | This message is not allowed to be removed. |
BATCH_MESSAGES_CANNOT_UPDATE_STATUS_TO_SCHEDULED | Batch messages cannot update status to scheduled. | Messages that are in the processing status cannot be scheduled. |
BATCH_MESSAGES_CANNOT_UPDATE_STATUS_TO_PENDING | Batch messages cannot update status to pending. | A sent message cannot be changed to pending status. |
EXPERIMENT_VALIDATION_ERROR | Incorrect experiment name Supported experiment strategies in this context are split,split-with-champion dissimilar experiments |
Check that the experiment names are correct. |
BATCH_MESSAGES_UNABLE_TO_UPDATE_JOB | No sub jobs created Could not create SendBatchMessage job |
This job was unable to be updated. |
RECORD_NOT_FOUND | Batch Message does not exist Message ID is not found. |
The identifier entered didn't return any results. |
BATCH_MESSAGES_CONTACT_KEY_MUST_BE_INDEXED | Key :mainIdentifier not indexed field. | All contacts should be indexed. |
BATCH_MESSAGES_CONTACT_NOT_ASSOCIATED_WITH_CHANNEL | Contact does not support message channel. Contact doesn't have a valid entry for :name channel |
Ensure the contact information has been input correctly for this channel. |
BATCH_MESSAGES_CONTACT_NOT_ASSOCIATED_WITH_CHANNEL | Message is stopped No msID available Invalid contact |
Ensure the contact information has been input correctly for this channel. |
BATCH_MESSAGES_SEND_RENDER_ERROR | Unable to render content :message | This is a render error using Smarty. |
BATCH_MESSAGES_SEND_INTERNAL_RENDER_ERROR | Internal render error | Contact your Cordial support member as soon as possible to resolve this issue. |
BATCH_MESSAGES_UNABLE_TO_ASSIGN_MCID | Error assigning message to contact | Ensure the contact information has been input correctly for this message. |
BATCH_MESSAGES_CONTACT_NOT_FOUND | Contact does not exist Contact is not found. |
The contact identifier entered didn't return any results. |
BATCH_MESSAGES_STATUS_ERROR | Message canceled and can't be resumed Message already canceled |
The message status does not allow updates. |
BATCH_MESSAGES_CUSTOM_KEY_ERROR | Unable to determine a channel Unable to determine a channelType by channel :channel |
Ensure channel is input correctly. |
BATCH_MESSAGES_SCHEDULE_ERROR | Time is in the past. sendSchedule is required |
Check that the time has been scheduled for a future time. |
CHANNEL_NOT_FOUND | Service for this channel not exist | Service for this channel does not exist. |
BATCH_MESSAGES_MISSING_AUDIENCE_INCLUDE_RULE | Audience rule is invalid. {include} should not be empty | Check that the include is valid and has been input correctly. |
MESSAGE_TRANSPORT_INVALID_ACCOUNT_TRANSPORT | TransportID does not belong to this account | The selected transport is not valid for this account. |
BATCH_MESSAGES_TEST_ERROR | Not enough parameters | Check the required parameters for correct formatting. |
BATCH_MESSAGES_CANNOT_UNSCHEDULE_PROCESSING_MESSAGE | Unable to unschedule message | Batch messages with the status of 'Processing' cannot be unscheduled. |
BATCH_MESSAGES_INCORRECT_AUDIENCE_RULE | Incorrect audience rule | Make sure the audience rule was input correctly. |
CONTACT_DATA_NOT_FOUND | Contact not provided in payload | Some contact data may be missing. |
NO_ADDRESS_SET | Address not present in contact for particular message channel | The contact's address may be missing for this channel. |
INVALID | Contact marked as invalid | The contact's information may be missing/incorrect. |
NOT_SUBSCRIBED | Contact not subscribed | The contact must be subscribed to receive messages. |
EXCEEDED_RATE_LIMIT | Duplicated record in message contacts collection | Contact your Cordial support member as soon as possible to resolve this issue. |
INTERNAL_ERROR | Internal error | Contact your Cordial support member as soon as possible to resolve this issue. |
Comments
0 comments
Please sign in to leave a comment.