Passing JSON object data in a transactional email via API

When sending a transactional email via Ortto's API, you have the ability to pass a JSON object as part of the request body and use the object's values within the email content.

This page describes the options for passing JSON object data in an email sent via API and assumes you have read the guide on Using the API to send emails (and are familiar with the requirements).

Similar to how you can use a JSON endpoint to create dynamic email content in the Ortto app, you can pass the JSON object either per campaign or per contact.

NOTE: The JSON values object requires a different name depending on whether it is used at the per campaign or the per contact level:

Per campaign: static_json_values
Per contact: json_values .

See examples of each below.

Use the JSON object per campaign

To use the JSON object per campaign (so that all recipients receive the same object values), place it at the root level.

In the below example, the JSON object static_json_values is passed at the root level, separate to asset and emails:

json
 {
"static_json_values": {
  "destination": "Paris",
  "airport": "Charles de Gaulle (CDG)",
  "carrier": "Air France",
  "frequent_flyer": true
},
"asset": {
  "campaign_id": "62de45141a2a340b983eec22"
},
"emails": [{
  "fields": {
    "bol::sp": true,
    "str::email": "john@rainyday",
    "str::first": "John",
    "str::last": "Transactional"
    }
  },
  {
  "fields": {
    "bol::sp": true,
    "str::email": "kate@monsteraandmay",
    "str::first": "Kate",
    "str::last": "Values"
    }
  }
],
"merge_by": [
  "str::email"
],
"merge_strategy": 2,
"find_strategy": 0,
"skip_non_existing": false
}

The object values can then be accessed using Liquid syntax in the email body:

{{ json.destination }}
{{ json.airport }}
{{ json.carrier }}
{{ json.frequent-flyer }}

Here is an example of a transactional email showing the JSON object passed per campaign with JSON values used in the email content (at html_body):

json
 {
"static_json_values": {
  "destination": "Paris",
  "airport": "Charles de Gaulle (CDG)",
  "carrier": "Air France",
  "frequent_flyer": true
  },
"asset": {
  "from_email": "donald@travelagent.com",
  "from_name": "Donald Agent",
  "subject": "Flight booking confirmation for {{ people.first-name }}",
  "email_name": "confirm-flight-booking",
  "no_click_tracks": false,
  "no_opens_tracks": false,
  "html_body": "<!DOCTYPE html><head>
  <title>Transactional email with JSON values</title> 
  <style> table { font-family: arial, sans-serif; border-collapse: collapse; width: 100%;} td, th { border: 1px solid #dddddd; text-align: left; padding: 8px; } tr:nth-child(even) { background-color: #dddddd;} </style>
  </head><body><div>Hi {{ people.first-name }} here is your flight booking confirmation:</div>
  <table><tr><th>Destination</th><th>Airport</th><th>Carrier</th><th>Frequent flyer membership status</th></tr>
  <tr><td>{{ json.destination }}</td>
  <td>{{ json.airport }}</td>
  <td>{{ json.carrier }}</td>
  <td>{% if json.frequent_flyer == true %} Active {% else %} Inactive {% endif %}</td>
  </tr></table></body></html>",
"liquid_syntax_enabled": true
  },
"emails": [{
  "fields": {
    "bol::sp": true,
    "str::email": "john@rainyday.com",
    "str::first": "John",
    "str::last": "Transactional"
    }  
  },
  {
  "fields": {
    "bol::sp": true,
    "str::email": "kate@monsteraandmay.com",
    "str::first": "Kate",
    "str::last": "Values"
    }
  }
],
"merge_by": [
  "str::email"
],
"merge_strategy": 2,
"find_strategy": 0,
"skip_non_existing": false
}

Use the JSON object per contact

To pass the JSON object per contact (where you have values specific to a particular recipient), place it within the emails object.

In the below example, the JSON object json_values is passed within emails:

json
 {
"asset": {
  "campaign_id": "62de45141a2a340b983eec22"
},
"emails": [{
  "fields": {
    "bol::sp": true,
    "str::email": "john.doe@example.com",
    "str::first": "John",
    "str::last": "Doe",
    "str::soi-ctx": "Subscription confirmation"
   },
  "json_values": {
      "first": "John",
      "plan": "Gold",
      "credits": 450,
      "active": true,
      "company": {
          "name": "Rainy Day"
      }
  },
  "location": null
  }
],
"merge_by": [
  "str::email"
],
"merge_strategy": 2,
"find_strategy": 0,
"skip_non_existing": false
}

The object values can then be accessed using Liquid syntax in the email body:

{{ json.first }}
{{ json.plan }}
{{ json.credits }}
{{ json.active }}
{{ json.company.name }}

Here is an example of a transactional email showing the JSON object passed per contact (at emails) with JSON values used in the email content (at html_body). In this example, each contact — John and Kate — will receive an email containing their relevant JSON values.

json
 {
"asset": {
  "from_email": "jenny@company.com",
  "from_name": "Jenny Spencer",
  "subject": "Subscription confirmation",
  "email_name": "confirm-booking",
  "no_click_tracks": false,
  "no_opens_tracks": false,
  "html_body": "<!DOCTYPE html><head>
    <title>Transactional email with JSON values</title> 
    <style> table { font-family: arial, sans-serif; border-collapse: collapse; width: 100%;} td, th { border: 1px solid #dddddd; text-align: left; padding: 8px; } tr:nth-child(even) { background-color: #dddddd;} </style>
    </head><body><div>Hi {{ json.first }} here is your subscription confirmation:</div>
    <table><tr><th>Business name</th><th>Plan</th><th>Credits</th><th>Subscription status</th></tr>
    <tr><td>{{ json.company.name }}</td>
    <td>{{ json.plan }}</td>
    <td>{{ json.credits }}</td>
    <td>{% if json.active == true %} Active {% else %} Inactive {% endif %}</td>
    </tr></table></body></html>",
  "liquid_syntax_enabled": true
      },
"emails": [{
  "fields": {
    "bol::sp": true,
    "str::email": "john@rainyday.com",
    "str::first": "John",
    "str::last": "Transactional"
  },
  "json_values": {
    "first": "John",
    "plan": "Gold",
    "credits": 450,
    "active": true,
    "company": {
      "name": "Rainy Day"
      }
    }
  },
  {
  "fields": {
    "bol::sp": true,
    "str::email": "kate@monsteraandmay.com",
    "str::first": "Kate",
    "str::last": "Values"
  },
  "json_values": {
    "first": "Kate",
    "plan": "Silver",
    "credits": 350,
    "active": true,
    "company": {
      "name": "Monstera and May"
      }
  },
  "location": null
  }
],
"merge_by": [
  "str::email"
],
"merge_strategy": 2,
"find_strategy": 0,
"skip_non_existing": false
}