- POST /batchmessages
- GET /batchmessages
- PUT /batchmessages/{id}
- GET /batchmessages/{id}
- DELETE /batchmessages/{id}
- PUT /batchmessages/{id}/send
- PUT /batchmessages/{id}/sendtest
- GET /batchmessages/{id}/renderedwip/{contactID}
- PUT /batchmessages/{id}/pause
- PUT /batchmessages/{id}/cancel
- PUT /batchmessages/{id}/resume
API Description and Functional Purpose:
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 address 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 by default placed into a "draft" status. 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.
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 | Description of the channel for this message. Options currently include "email". | |
*classification | string | Describes the class of communication. Options include "transactional" and "promotional". | transactional |
name | string | An optional name given to the message. | Jan_Newsletter_2018 |
tags | array | List of string values to identify and categorize the message. | ["birthday","promo"] |
audience | object | Defines search criteria to select only those contacts that meet the criteria. | allContacts:true |
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. | 2018-01-09 17:47:43 |
scheduleType | string | Enable sending at the scheduled time per the timezone of the contact | contactTZ |
transportID | string | Defines the transportID if overriding the default. Default used if parameter is not included. | 57d098b66c8766fd53ad19d7 |
trackLinks | string | Enables or disables storing link tracking data. Options include "true" or "false", or "enabled" or "disabled". The default is "enabled". | 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 who is 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", "classification": "promotional", "name": "promo_01_20_2018", "audience": [], "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 URIs
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. |
?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. 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 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
Same parameters as 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", "audience": [], "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 URIs
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 URIs
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 URIs
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 URIs
The following URI in conjunction will 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 batchmessage.
The batchmessages record is defined by the batchmessages's unique "id" value. |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
array | An array of email address to receive the test message. | [ "test1@example.com","test2@example.com" ] |
Example JSON Requests
{ "email": [ "test1@example.com","test2@example.com" ] }
Example Request URIs
The following URI 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 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 URIs
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}/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 URIs
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}/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 URIs
The following URI will perform the PUT to the batch message with the "id" "252:58ffed51f0c36063476c1752:ot".
http://<path>/batchmessages/252:58ffed51f0c36063476c1752:ot/resume
Comments
0 comments
Please sign in to leave a comment.