Overview

An automation template instance within the automation templates 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. You can use a template one or more times.

Additional information

• Template key values must be unique. Therefore, it's 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.

Methods, parameters, and examples

• POST/automationtemplates
• GET/automationtemplates
• GET/automationtemplates/{key}
• PUT/automationtemplates/{key}
• PUT/automationtemplates/{key}/publish
• POST/automationtemplates/{key}/senddraft
• POST/automationtemplates/{key}/send
• DELETE/automationtemplates/{key}
• GET/automationtemplates/{key}/renderdraft/{contactID}
• GET/automationtemplates/{key}/renderpublished/{contactID}
• Error responses

POST/automationtemplates

• *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 automation template.	news-01-21-2018
  *channel	string	Messaging channel key (e.g. email, sms, push). Note that some of your channels may have custom keys.	email
  *classification	string	If applicable, classifies the message as transactional or promotional.	transactional
  *baseAggregation	string	Message performance aggregate rollup interval. Specific to API and event triggered messages. Possible values: daily, hourly.	daily
  tags	array	An array of string values to identify and categorize the message. Tags are case sensitive.	["birthday","promo"]
  transportID	string	Defines the transportID if overriding the default.	trans_1134
  draftContent	string	Determines if the message will be submitted as a draft or published version. Default is false (published). Possible values: true, false	true
  trackLinks	string	Determines if link performance will be tracked. Default is enabled. Possible values: enabled, disabled	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 the sender.	CS Dept
  *replyEmail	string	Email address that will receive the message replies.	email@example.com
  Message/Content
  *text/html	string	Message content. Can contain HTML markup for email messages or plain text for SMS.	<div>content</div>

• Email

  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>"
      }
    }
  }
  

  SMS

  The following will create a new automation template for a promotional SMS message.

  {
    "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"
      }
    }
  }
  

• The following URI in conjunction with the JSON will perform the POST of the automationtemplates.

  http://<path>/automationtemplates
  

GET/automationtemplates

• 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 automation templates that contain the specified message tags. Multiple tags are comma separated.	?tags=welcome%2C%20promo
  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

• 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}

• 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

• 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}

• *Required

  Parameter	Type	Description	Example
  Template
  transportID	string	Defines the transportID if overriding the default.	trans_1134
  draftContent	string	Determines if the message will be submitted as a draft or published version. Default is false (published). Possible values: true, false	true
  trackLinks	string	Determines if link performance will be tracked. Default is enabled. Possible Values: enabled, disabled	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 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	Message content. Can contain HTML markup or plain text, depending on message type and channel.	<div>content</div>

• 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"
          }
      }
  }

• 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
  

PUT/automationtemplates/{key}/publish

• The following URI will perform a PUT to the automation template draft with a key of "promo_01_20_2018 ".

  http://<path>/automationtemplates/promo_01_20_2018/publish
  

POST/automationtemplates/{key}/senddraft

• *Required

  Parameter	Type	Description	Example
  To/Contact
  *contact identifier	string	Specify the message recipient using a contact identifier key/value pair. Use the "identifierKey": "identifierValue" format.	"email@example.com": "msmith@example.com", "custID": "ID1234"

  Using the extVars object, 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}.

  Data passed within external variables is not stored in the Cordial platform.

  Data passed as external variables should represent relatively simple string values. Attempts to pass more complex data, such as markup code, will be blocked by the server due to security considerations.

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

  Email as identifier

  {
      "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"
                  }
              ]
          }
      }
  }
  

  cID as identifier

  {
      "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"
                  }
              ]
          }
      }
  }
  

  Custom identifier

  {
      "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

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 none and will not receive promotional messages until subscribed to the appropriate channel. If the contact exists, data passed in the contact object will upsert corresponding contact attributes in Cordial.

There is a one-request-per-second default limit on API send calls. Additional capacity can be requested by contacting your Client Success Manager.

• *Required

  Parameter	Type	Description	Example
  To/Contact
  *contact identifier	string	Specify the message recipient using a contact identifier key/value pair. Use the "identifierKey": "identifierValue" format.	"email@example.com": "msmith@example.com", "custID": "ID1234"
  identifyBy	string	Specifies which identifier key in the request body should 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 serves as 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.

  For calls where 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}.

  Data passed within external variables is not stored in the Cordial platform.

  Data passed as external variables should represent relatively simple string values. Attempts to pass more complex data, such as markup code, will be blocked by the server due to security considerations.

• 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"
          }
        ]
      }
    }
  }
  

  cID as identifier

  {
      "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"
                  }
              ]
          }
      }
  }
  

  Custom identifier

  {
      "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. Take note of the channels addition to the JSON.

  Another way to access the contact identifier with the 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"
          }
        ]
      }
    }
  }

DELETE/automationtemplates/{key}

• 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}

• Parameter	Type	Description	Example
  experiment	string	Returns the automation template that contains the specified experiment. Variant is required if experiment is specified.	?experiment=SubjectTest&variant=Left_Cart_Items
  variant	string	Returns the automation template that contains the specified experiment variant. Experiment is required if variant is specified.	?experiment=SubjectTest&variant=Left_Cart_Items

• 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}

• Parameter	Type	Description	Example
  experiment	string	Returns the automation template that contains the specified experiment. Variant is required if experiment is specified.	?experiment=SubjectTest&variant=Left_Cart_Items
  variant	string	Returns the automation template that contains the specified experiment variant. Experiment is required if variant is specified.	?experiment=SubjectTest&variant=Left_Cart_Items

• 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

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 Automation Templates 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.