Overview

When sending an automated message via the automationtemplates API, Cordial provides the option to pass variables for use within that message. These are called "external variables" and are not saved in the system. External variables can be used to render content in message body as well as message header fields (subject, from email, reply email, and from description).

• Learn more about the automationtemplates API call.

The Smarty syntax used to reference these variables is written as follows:

{$extVars.variableName}

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.

When using this variable in an API triggered Podium orchestration, the subject line should include "triggerData," looking like this: {$extVars.triggerData.variableName}

Use case: order confirmation

A common use case is an order confirmation message. An eCommerce order may contain the order ID and tracking number. You can then send a message that renders this data to the contact.

If in the API call, you assigned the "extVars" of: {"orderID":"01234"} and {"track":"RGTF3DR7"}, you would then reference these in the HTML of the template as follows:

Product item information can be passed with external variables as an array of objects. You can then use the {foreach} statement to loop through those items and render them in the message.

When creating object names, refrain from using system reserved names such as "account", "message" or "contact", as they are used for displaying other variables in message content.

Below is an example of an order confirmation message. Using the tabs, you can view the HTML & Smarty, the order data (in JSON format) and the rendered output that will be seen after a message send.

• <h2>Thanks for your purchase!</h2>
  Order ID: {$extVars.orderID}<br>
  Date: {$extVars.purchaseDate|date_format}
  <br><br>
  {foreach $extVars.items as $item}
  productID: {$item.productID}<br>
  Name: {$item.name}<br>
  Price: ${$item.price}<br><br>
  {/foreach}
  

• {
  "identifyBy": "email",
     "to":{  
        "contact":{  
           "email":"fredgarvin@gmail.com"
        },
        "extVars":{  
           "orderID":"1234",
           "purchaseDate":"2017-03-30 12:47:34",
           "orderTotal":"30.00",
           "items":[  
              {  
                 "name":"shirt",
                 "price":"10.00",
                 "productID":"123"
              },
              {  
                 "name":"pants",
                 "price":"20.00",
                 "productID":"456"
              }
           ]
        }
     }
  }
  

• Thanks for your purchase!

  Order ID: 1234
  Date: Mar 30, 2017 
  
  productID: 123
  Name: shirt
  Price: $10.00
  
  productID: 456
  Name: pants
  Price: $20.00

External variables in message header fields

External variables can be inserted into message header fields to customize the subject line, reply email, from email, and from description.

In this example, we created three additional external variables that will be inserted into corresponding message header fields:

Values being passed into from and reply email header fields must be correctly formatted email addresses. Referencing values inside of these fields that are not email addresses will cause message send failures.

This is a preview of message header fields before the message is sent and external variables rendered:

• Learn more about setting up an automated order confirmation message here.
• Learn more about using the {foreach} statement here.

In the next article, you can learn about timestamp variables.