External Variables (API Sending)

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}

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.

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

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:

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.
Learn more about using the {foreach} statement.

In the next article learn about timestamp variables.