How can we help?

Get JSON Feeds (getJson method)


The data stored within an externally hosted JSON feed can be referenced and used within any message body.

Our example

For our example, we'll be using external JSON data consisting of a list of automobiles. Using the tabs below, you can view the HTML and Smarty used in the message, the JSON data being referenced and the rendered output that will display when a message is sent or previewed. Copy and paste the code below into a message and preview or send the message to see the results.

  • {$cars=$utils->getJson('')} 
    {foreach $cars as $car}
    <strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
    Mileage: {$car.mileage}<br> <br>
  • [
          "model": "pilot",
          "brand": "honda",
          "price": 33000,
          "mileage": 100000,
          "id": "01"
          "model": "explorer",
          "brand": "ford",
          "price": 34000,
          "mileage": 39000,
          "id": "02"
          "model": "prius",
          "brand": "toyota",
          "price": 27000,
          "mileage": 66000,
          "id": "03"
          "model": "model s",
          "brand": "tesla",
          "price": 130000,
          "mileage": 56000,
          "id": "04"
          "model": "versa",
          "brand": "nissan",
          "price": 16000,
          "mileage": 94000,
          "id": "05"
          "model": "camary",
          "brand": "toyota",
          "price": 29000,
          "mileage": 310000,
          "id": "06"
          "model": "accord",
          "brand": "honda",
          "price": 24000,
          "mileage": 49000,
          "id": "07"
  • Honda Pilot
    Mileage: 100000
    View details

    Ford Explorer
    Mileage: 39000
    View details

    Toyota Prius
    Mileage: 66000
    View details

    Tesla Model S
    Mileage: 56000
    View details

    Nissan Versa
    Mileage: 94000
    View details

    Toyota Camary
    Mileage: 310000
    View details

    Honda Accord
    Mileage: 49000
    View details

getJson method

In order to access remote JSON data within a message, use the getJson method, which is a custom extension of Smarty provided by Cordial.

The getJson method has 3 parameters: url, cacheMinutes and options. They must be written in this order and separated by commas. Only url is required.

For best results, the remote JSON file size should not exceed 1MB in size.

getJson($url, $cacheMinutes, $options)

Parameter Description Required Expected Default
url URL for the JSON resource. required valid URL NA
cacheMinutes Number of minutes to store the feed data in memory. This optimizes send time if the system doesn't have to request the feed for every individual message. optional integer 10
options Allows for the configuration of options such as HTTP request headers or maximum wait time. Can be used to limit the maximum number of records returned when only an integer is supplied. optional array or integer []

Set the URL

For the purpose of this example, we hosted the JSON document and included the link below. You can use the example feed in your system for testing.


In the example above, a variable cars is assigned to the resulting data set returned from the remote JSON document. The getJson method will get the data from the URL for each message that is rendered per contact.

Set cacheMinutes

A cache can be set in memory for the data so the system doesn't have to request the feed for every individual message. This optimizes the time it takes to compile and send a message as well as reduces the load of the server hosting the data feed (your IT team will thank you). You can specify the number of minutes that the data is stored in memory with this parameter. In the example below, the data would be retrieved from the server 1 time every 20 minutes.


Set options

This parameter allows for the configuration of options.

Set HTTP request headers for authorization

{$coupon=$utils->getJson("", 0, ["headers"=>['Authorization' => 'Basic <base64 encoded username:password>']])}

Basic authentication is currently the only supported authentication method for use with the getJson method.

Set a maximum wait time

This is useful when an external JSON file is not available or taking too long to respond. The timeout option will set a maximum number seconds the system will wait for the data.

In the following example, the request will timeout after 1 second:

{$coupon=$utils->getJson("", 0, ["timeout" => 1])}

The default timeout is 60 seconds. Maximum wait time cannot exceed 60 seconds.

Set a limit on the number of records returned

You can use an integer as the third parameter to limit the number of records returned.

In the following example, the request will return three records:

{$coupon=$utils->getJson("", 0, 3)}

Render data in a message

After the data is available with the getJson method, you can render the data in the message.

Loop through data with {foreach}

A {foreach} statement is the most common way to loop through the data array and render the results in a message.


{foreach $cars as $car}
<strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>
Mileage: {$car.mileage}<br> <br>

Reference an array index

If you don't need to loop through all of the data in the array, you can render a specific value by referencing its index within the array.


<strong>{$cars[0].brand|capitalize} {$cars[0].model|capitalize}</strong><br>
Mileage: {$cars[0].mileage}

This example will look in the first record of the data array and render the value for brand, model, price and mileage.

The first item of an array is referenced by 0, the second is 1, the third is 2, and so on.

In the next article, you can learn about getting XML feeds.



Please sign in to leave a comment.