How can we help?

External variables (API sending)


When sending an automated message via the automation templates API, Cordial provides the option to pass variables within that message. These are called external variables and are not saved in the system. External variables can be used to render content in the message body and message header fields.

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


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:

Smarty in Message Data in API Call Rendered Output
{$extVars.orderID} 01234 01234
{$extVars.track} RGTF3DR7 RGTF3DR7

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}
    {foreach $extVars.items as $item}
    productID: {$item.productID}<br>
    Name: {$}<br>
    Price: ${$item.price}<br><br>
  • {
    "identifyBy": "email", "to":{ "contact":{ "email":"" }, "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:

Smarty in Message Data in API Call Rendered Output
{$extVars.first} John John
{$extVars.fromDesc} Be Cordial Be Cordial

Values being passed into the From and Reply email header fields must be correctly formatted email addresses. Referencing values inside 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:

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



Please sign in to leave a comment.