- POST /automationtemplates
- GET /automationtemplates
- GET /automationtemplates/{key}
- PUT /automationtemplates/{key}
- POST /automationtemplates/{key}/publish
- POST /automationtemplates/{key}/senddraft
- POST /automationtemplates/{key}/send
- DELETE /automationtemplates/{key}
- GET /automationtemplates/{key}/renderdraft/{contactID}
- GET /automationtemplates/{key}/renderpublished/{contactID}
API Description and Functional Purpose:
An automationtemplate instance within the automationtemplates collection contains the essential information to define a communication template for an automated message. Templates include details for content, channel, classification of communication (transactional or promotional), subject line, from and reply address, and HTML. It is possible to use a template one or more times.
Additional information:
- Template key values must be unique. Therefore, it is important to consider a naming convention that will accommodate creating multiple templates over time. For example. "sports_newsletter_Jan_2018_week1" is better than "jan_newsletter".
- Cordial provides a default transport for sending communications; however it is possible to use an external provider if needed.
- By default, results data is aggregated on a "daily" interval. This can be optionally set to "hourly" if further granularity is needed.
POST /automationtemplates
Method | URI Path |
---|---|
POST | /automationtemplates |
Creates a new message template in the Cordial database using the appropriate JSON body.
Posting more than one time for the same template key value will generate an error. Use PUT to change or update template data once created. |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
Template | |||
*key | string | Unique value assigned to the template. The key may only contain letters, numbers, and dashes. | news-01-21-2018 |
*Name | string | A name given to the message. | news-01-21-2018 |
*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 |
*baseAggregation | string | Specific to API and triggered messages. Options include daily and hourly. | daily |
tags | array | List of string values to identify and categorize the message. | ["birthday","promo"] |
transportID | string | Defines the transportID if overriding the default. | trans_1134 |
draftContent | string | Defines if the message will be submitted as a draft or published version. Value is boolean: true or false. Default is false. | true |
trackLinks | string | Enables or disables storing link tracking data. Options include or enabled or disabled. The default is enabled. | disabled |
Message/Headers (email) | |||
*subject | string | The subject line for the communication. | Welcome! |
*fromEmail | string | The email address that the message is from. | email@example.com |
*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 email message or plain text for SMS. | <div>content</div> |
Example JSON requests
The following will create a new automation template for a promotional email message.
{ "key": "promo_01_20_2018", "name": "promo_01_20_2018", "channel": "email", "classification": "promotional", "baseAggregation": "hourly", "message": { "headers": { "subject": "One Day Only Sale", "fromEmail": "info@example.com", "replyEmail": "info@example.com", "fromDesc": "Promotions Team" }, "content": { "text/html": "<div>Hello World</div>" } } }
The following will create a new automation template for a promotional SMS message. Note: SMS messages can only be classified as promotional at this time.
{ "key": "sms_cyber_promo", "baseAggregation": "daily", "channel": "sms", "classification": "promotional", "name": "Cyber Monday Deal", "tags": ["cyber_monday", "cm_promo"], "message": { "content": { "text": "SMS text message content" } } }
Example Request URIs
The following URI in conjunction with the JSON will perform the POST of the automationtemplates.
http://<path>/automationtemplates
GET /automationtemplates
Method | URI Path |
---|---|
GET | /automationtemplates |
Retrieves all automation templates from the Cordial database. |
Query String Parameters
Parameter | Type | Description | Example |
---|---|---|---|
fields | string | Limits the data returned to the fields specified. Multiple fields are comma separated. Possible Values: key, name, classification, channel, stats, baseAggregation, createdAt, lastUpdate, message, mdtID. Note: The status field always displays the value of disabled and does not represent the actual status of a sending method. This field is unused. |
?fields=key%2ClastUpdate |
ct[gt] | string | Returns records where the create date is greater than the specified date. |
?ct%5Bgt%5D=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%5Bgte%5D=2018-01-01T00:00:00.000Z |
ct[lt] | string | Returns records where the create date is less than the specified date. |
?ct%5Blt%5D=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%5Blte%5D=2018-01-01T00:00:00.000Z |
lm[gt] | string | Returns records where the last modified time is greater than the specified date. |
?lm%5Bgt%5D=2018-01-01T00:00:00.000Z |
lm[gte] | string | Returns records where the last modified time is greater than or equal to the specified date. |
?lm%5Bgte%5D=2018-01-01T00:00:00.000Z |
lm[lt] | string | Returns records where the last modified time is less than the specified date. |
?lm%5Blt%5D=2018-01-01T00:00:00.000Z |
lm[lte] | string | Returns records where the last modified time is less than or equal to the specified date. |
?lm%5Blte%5D=2018-01-01T00:00:00.000Z |
tags | string | Returns results that contain the specified message tags. Multiple tags are comma separated. |
?tags=welcome%2C%20promo |
page | string | Specifies the results page number. |
?page=3 |
per_page | string | Specifies the number of records returned per page. |
?per_page=100 |
Example Request URIs
The following URI will retrieve all automation templates and include all fields.
http://<path>/automationtemplates
The following URI will retrieve all automation templates, but will only include the field data for "name".
http://<path>/automationtemplates?fields=name
The following URI will retrieve all automation templates, and will only include the field data for "name" and "message".
http://<path>/automationtemplates?fields=name%2Cmessage
The following URI will retrieve all automation templates starting from the third page grouping contacts by 10. For example, page-1 would have included the first 10, page-2 the second group of 10 and so on.
http://<path>/automationtemplates?page=3&per_page=10
GET /automationtemplates/{key}
Method | URI Path |
---|---|
GET | /automationtemplates/{key} |
Retrieves an automation template from the Cordial database.
The automation template record is defined by the template's unique key value. |
Query String Parameters
Parameter | Type | Description | Example |
---|---|---|---|
fields | string | Limits the data returned to the fields specified. Multiple fields are comma separated. Possible Values: key, name, classification, channel, stats, baseAggregation, createdAt, lastUpdate, message, mdtID. Note: The status field always displays the value of disabled and does not represent the actual status of a sending method. This field is unused. |
?fields=key%2ClastUpdate |
Example Request URIs
The following URI will retrieve an automation template where the key value is "promo_01_20_2018" and include all fields.
http://<path>/automationtemplates/promo_01_20_2018
The following URI will retrieve an automation template where the key value is "promo_01_20_2018", but will only include the field data for name.
http://<path>/automationtemplates/promo_01_20_2018?fields=name
The following URI will retrieve an automation template where the key value is "promo_01_20_2018", and will only include the field data for name and message.
http://<path>/automationtemplates/promo_01_20_2018?fields=name%2Cmessage
PUT /automationtemplates/{key}
Method | URI Path |
---|---|
PUT | /automationtemplates/{key} |
Updates fields for a automation template within the Cordial database.
The automation template record is defined by the template's unique key value. For example, /automationtemplates/promo_01_20_2018 allows the template with the key value of "promo_01_20_2018" to be updated using the appropriate JSON body. |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
Template | |||
transportID | string | Defines the transportID if overriding the default. | trans_1134 |
draftContent | string | Defines if the message will be submitted as a draft or published version. Value is boolean: true or false. Default is false. | true |
trackLinks | string | Enables or disables storing link tracking data. Options include or enabled or disabled. The default is enabled. | disabled |
Message/Headers | |||
*subject | string | The subject line for the communication. | Welcome! |
*fromEmail | string | The email address that the message is from. | email@example.com |
*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> |
Example JSON Requests
The following will update the subject for an automation template.
{ "message": { "headers": { "subject": "Big Sale This Weekend", "fromEmail": "info@example.com", "replyEmail": "info@example.com", "fromDesc": "Promo Team" } } }
Example Request URIs
The following URI in conjunction with the JSON will perform the PUT to the automation template "promo_01_20_2018".
http://<path>/automationtemplates/promo_01_20_2018
POST /automationtemplates/{key}/publish
Method | URI Path |
---|---|
POST | /automationtemplates/{key}/publish |
Publishes an automation template draft.
The automation template record is defined by the template's unique key value. |
Example Request URI
The following URI will perform a POST to the automation template with a key of "promo_01_20_2018 ".
http://<path>/automationtemplates/promo_01_20_2018/publish
POST /automationtemplates/{key}/senddraft
Method | URI Path |
---|---|
POST | /automationtemplates/{key}/senddraft |
Sends an automation template draft for testing purposes.
The automation template draft to be sent is defined by the template's unique key value. For example, /automationtemplates/promo_01_20_2018/senddraft allows the template with the key value of "promo_01_20_2018" to be sent using the appropriate JSON body. The template can be sent to one or more contacts, as defined within the JSON body. |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
To/Contact | |||
*contact identifier | string | Specify the message recipient using a contact identifier value. | email@example.com, ID1234, 16198880000 |
Using extVars, any number of additional external variables may be added. These values are then available in the template. For example, if "extVars": {"orderID": "o1234"} is included as an order ID value, then in the message it can be accessed as {$extVars.orderID}.
Example JSON Requests
The following will send a message to a single contact. The three examples each use a different contact identifier key/value pair to identify the recipient.
{ "to": { "contact": { "email": "msmith@example.com" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } } }
{ "to": { "contact": { "cID": "58d30719ac0c8117814da1f3" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } } }
{ "to": { "contact": { "customKey": "identifierValue" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } } }
POST /automationtemplates/{key}/send
Method | URI Path |
---|---|
POST | /automationtemplates/{key}/send |
Sends an automation template.
The automation template to be sent is defined by the template's unique key value. For example, /automationtemplates/promo_01_20_2018 week1/send allows the template with the key value of "promo_01_20_2018" to be sent using the appropriate JSON body. The template can be sent to one or more contacts, as defined within the JSON body. Note: This endpoint will successfully create a new contact record if the contact identifier value in the request does not already exist. The newly added contact will have a subscribe status of |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
To/Contact | |||
*contact identifier | string | Specify the message recipient using a contact identifier value. | email@example.com, 58d30719ac0c811, 16198880000, ID1234 |
identifyBy | string | Denotes the identifier key to be used to look up the contact. | email, cID, SMS, customKey |
IdentifyBy
The identifyBy
parameter is used to specify which identifier key in the request body should be used to look up the contact. Because contact attribute data sent in the "contact" object of the call will upsert corresponding contact attributes in Cordial, identifyBy
should be used to specify which key is the contact identifier.
The identifier key you specify for the identifyBy
parameter essentially becomes "reserved" for the purpose of looking up the contact, and its value will not be upserted. However, the call will upsert any secondary contact identifier values within the contact object if provided.
The use of this parameter becomes especially relevant for Cordial accounts where a contact can be uniquely identified using more than one identifier key, be it primary or secondary.
identifyBy
is not included, the request body will be searched for the key that serves as the primary contact identifier in your Cordial account, and if not found, the call will return the pk-not-preset-inpayload
response. This occurs because the call is configured to fall back to the primary contact identifier when no other identifier is specified.External variables
Using extVars, any number of additional external variables may be added. These values are then available in the template. For example, if "extVars": {"orderID": "o1234"} is included as an order ID value, then in the message it can be accessed as {$extVars.orderID}.
Example JSON Requests
The following will send to a single contact.
In this example, identifyBy
indicates email is the contact identifier used to look up the contact. The call will upsert the provided SMS and age contact attribute values in Cordial.
{ "identifyBy": "email", "to": { "contact": { "email": "msmith@example.com", "sms": "16198880000", "age": "34" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } } }
{ "identifyBy": "cID", "to": { "contact": { "cID": "58d30719ac0c8117814da1f3" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } } }
{ "identifyBy": "customKey", "to": { "contact": { "customKey": "identifierValue" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } } }
The following will send to multiple email addresses.
{ "identifyBy": "email", "to": [ { "contact": { "email": "msmith@example.com" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } }, { "contact": { "email": "jsmith@example.com" }, "extVars": { "orderID": "456", "orderItems": [ { "name": "San Diego Tee", "amount": "22.75" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Winter Hat", "amount": "13.40" } ] } } ] }
The following will send to a single email address AND will set the contact subscribe status to subscribed. Note the channels addition to the JSON.
identifyBy
parameter is to use dot notation. For example: "identifyBy": "channels.email.address"
.{ "identifyBy": "email", "to": { "contact": { "channels": { "email": { "address": "msmith@example.com", "subscribeStatus": "subscribed" } }, "fname": "Mark" }, "extVars": { "orderID": "123", "orderItems": [ { "name": "Tour Tee", "amount": "22.50" }, { "name": "Icon Tee", "amount": "25.50" }, { "name": "Icon Hat", "amount": "15.50" } ] } } }
Error response messages
Action | Error Message | Response Code |
---|---|---|
Attempt to send an automated template to a malformed email address or the contact identifier key is uniquely constrained to an existing contact record. | validation | 201 |
Attempt to send a promotional message to a contact who is not subscribed or attempt to send to a contact that does not have an email address in the system. | Contact not subscribed | 201 |
Pass in a parameter in the API call that is not part of the payload schema. | Key (key name provided) is not part of the schema for this resource. | 422 |
Both templateID and key are part of the payload. | Specify only one of "key" or "templateID. | 422 |
Attempt to send to an automated template that is not published. | There is no published version for this template. | 422 |
"To" parameter is not part of payload. | "to" must be specified | 422 |
Attempt to send automated template that does not have API sending enabled. | Trigger API is disabled | 422 |
Attempt to send an automated template where the "to" parameter does not contain a single contact or an array of contacts. | "to" parameter must contain a single contact or an array of contacts to send to | 422 |
Attempt to send an automated template to an array of contacts and one of the entries does not contain a value. | contact-data-not-found | 422 |
Attempt to send to same contact more than once per millisecond. | exceeded-rate-limit | 422 |
Cordial is unable to create message contact record. | internal-error | 422 |
Attempt to send an automated template that does not exist. | an error has occurred | 500 |
DELETE /automationtemplates/{key}
Method | URI Path |
---|---|
DELETE | /automationtemplates/{key} |
Deletes an automation template within the Cordial database.
The automation template is defined by the template's unique key value. For example, /automationtemplate/sports_newsletter_Jan_2018_week1 would delete the template with the key value of "sports_newsletter_Jan_2018_week1". |
Example Request URIs
The following URI will delete an automation template where the key value is "promo_01_20_2018".
http://<path>/automationtemplates/promo_01_20_2018
GET /automationtemplates/{key}/renderdraft/{contactID}
Method | URI Path |
---|---|
GET | /automationtemplates/{key}/renderdraft/{contactID} |
Retrieves the message headers, the rendered HTML and experiment name and variants of an automated template draft for a specified contact. For example, /automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3" will return the response data of the draft template with the key value of "order_confirm" and the contactID of "58d30719ac0c8117814da1f3". Additionally, you can pass experiment names and variants using a query string. |
Query String Parameters
Parameter | Type | Description | Example |
---|---|---|---|
experiment | string | Returns the automation template populated with the specified experiment. Variant is required if experiment is specified. |
?experiment=SubjectTest&variant=Left_Cart_Items |
variant | string | Returns the automation template populated with the specified experiement variant. Experiement is required if variant is specified. |
?experiment=SubjectTest&variant=Left_Cart_Items |
Example Request URIs
The following URI will perform the GET to the automation template draft where:
- Key = order_confirm
- Contact ID = 58d30719ac0c8117814da1f3
http://<path>/automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3
The following URI will perform the GET to the automation template draft where:
- Key = order_confirm
- Contact ID = 58d30719ac0c8117814da1f3
- Subject experiment = SubjectTest
- Subject experiment Variant = TestSubjectA
http://<path>/automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA
The following URI will perform the GET to the automation template draft where:
- Key = order_confirm
- Contact ID = 58d30719ac0c8117814da1f3
- Subject experiment = SubjectTest
- Subject experiment Variant = TestSubjectA
- Body experiment = BodyExperiment
- Body experiment variant = BodyA
http://<path>/automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA&experiment=BodyExperiment&variant=BodyA
GET /automationtemplates/{key}/renderpublished/{contactID}
Method | URI Path |
---|---|
GET | /automationtemplates/{key}/renderpublished/{contactID} |
Retrieves the message headers, the rendered HTML and experiment name and variants of a published automated template for a specified contact. For example, /automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3" will return the response data of the published template with the key value of "order_confirm" and the contactID of "58d30719ac0c8117814da1f3". Additionally, you can pass experiment names and variants using a query string. |
Query String Parameters
Parameter | Type | Description | Example |
---|---|---|---|
experiment | string | Returns the automation template populated with the specified experiment. Variant is required if experiment is specified. |
?experiment=SubjectTest&variant=Left_Cart_Items |
variant | string | Returns the automation template populated with the specified experiement variant. Experiement is required if variant is specified. |
?experiment=SubjectTest&variant=Left_Cart_Items |
Example Request URIs
The following URI will perform the GET to the published automation template where:
- Key = order_confirm
- Contact ID = 58d30719ac0c8117814da1f3
http://<path>/automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3
The following URI will perform the GET to the published automation template where:
- Key = order_confirm
- Contact ID = 58d30719ac0c8117814da1f3
- Subject experiment = SubjectTest
- Subject experiment Variant = TestSubjectA
http://<path>/automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA
The following URI will perform the GET to the published automation template where:
- Key = order_confirm
- Contact ID = 58d30719ac0c8117814da1f3
- Subject experiment = SubjectTest
- Subject experiment Variant = TestSubjectA
- Body experiment = BodyExperiment
- Body experiment variant = BodyA
http://<path>/automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA&experiment=BodyExperiment&variant=BodyA
Comments
0 comments
Please sign in to leave a comment.