Use Email Templates

By using templates for your emails sent via the TMS API, you can separate your content creation and approvals from the act of sending the message.

Separation of concerns is great for business processes, and great for performance. Using Email Templates, the body of email messages can be defined and updated in the TMS API, instead of in your application code. This offers the following benefits:

  1. Simplifies your content update process
  2. Reduces the bandwidth required for your application to send emails
  3. Changes to email contents can be made without any application code changes

Sending an email that uses a template can be as simple as specifying which template to use and who should receive it.

In this tutorial:

If you have not yet sent an email using TMS, you should first read through the Sending an Email tutorial and send some test emails to familiarize yourself with TMS Email Messages. After this tutorial, be sure to look at the /templates/email and /messages/email endpoint reference documents for more information on how to create, update, and use your email templates.

Prerequisites

Before you can send an email, there are a few things your organization will need to do to enable the Targeted Messaging Service:

  • Purchase the Targeted Messaging Service
  • Configure email addresses for the Targeted Messaging Service
  • Get a Targeted Messaging Service API Token

To get started on any of these, please email support@granicus.com.

Create an Email Template

To start off, let’s create a template for new user confirmation emails that includes a way to provide a new user with their unique confirmation URL. Just like when we send a regular email, the first thing we need to do is decide what we want to send. Let’s create a template that includes the following body:

Subject: Welcome!


Hello [[name]],

Thank you for signing up! To confirm your registration, please <a href="[[confirmationUrl]]">click here</a>.

Thank You

<img src="http://example.com/images/logos/agency_logo.png"></img>

Note: You’ll notice that this example included a macro: [[name]]. Macros are one option for personalizing content in your email template. For more information, see the Use Personalized Content and Conditional Logic in Email Templates section below.

Now that we know what we want to send, it’s simply a matter of making a POST to /templates/email and specifying subject, body, and macros.

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json"  https://tms.govdelivery.com/templates/email --data \
'{
    "uuid": "new-template_1",
    "subject": "Welcome!",
     "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please <a href=\"[[confirmationUrl]]\">click here</a>.\n\nThank You\n\n<img src=\"http://example.com/images/logos/agency_logo.png\"></img>",
     "macros": {
        "name": "New User",
        "confirmationUrl": "http://example.com/confirm?t=false"
    }
}'

// RESPONSE BODY
{
  "id": 10027,
  "uuid": "new-template_1",
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/agency_logo.png\"\u003e\u003c/img\u003e",
  "subject": "Welcome!",
  "link_tracking_parameters": null,
  "macros": {
    "name":"New User",
    "confirmationUrl": "http://example.com/confirm?t=false"
  },
  "open_tracking_enabled": false,
  "click_tracking_enabled": false,
  "created_at": "2015-05-05T19:23:47Z",
  "_links":{
    "self":"/templates/email/10027",
    "account":"/accounts/10040",
    "from_address":"/from_addresses/10040"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
template_body = <<eob
Hello [[name]],

Thank you for signing up! To confirm your registration, please <a href="[[confirmationUrl]]">click here</a>.

Thank You

<img src="http://example.com/images/logos/agency_logo.png"></img>
eob

template = client.email_templates.build(uuid: 'new_template-1',
                                        subject: 'Welcome!',
                                        body: template_body,
                                        macros: {"name"=>"New User", "confirmationUrl"=>"http://example.com/confirm?t=false"})
template.post
=> true

Once this POST is sent, TMS will respond with your newly created template object, which you will need for the next step.

Send an Email Using a Template

With our template now defined and ready, we can now use it to send a confirmation email simply by creating a new email message and specifying the template and our recipients:

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "recipients": [
    { 
      "email": "jim@example.com", 
      "macros": {
          "name":"Jim",
          "confirmationUrl": "http://example.com/confirm?t=1234abcd"
      } 
    },
    { 
      "email": "amy@example.com", 
      "macros": {
          "name": "Amy",
          "confirmationUrl": "http://example.com/confirm?t=9876zyxw"
      } 
    },
    { 
      "email": "bill@example.com"
    }
  ], 
  "_links": {
    "email_template": "new-template"
  }
}'

// RESPONSE BODY
{
  "subject":"Welcome!",
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/agency_logo.png\"\u003e\u003c/img\u003e",
  "click_tracking_enabled": false,
  "errors_to": "me@example.com",
  "from_email": "me@example.com",
  "from_name": null,
  "macros": {
      "name":"New User"
  },
  "open_tracking_enabled": false,
  "reply_to": "me@example.com",
  "created_at": "2015-05-05T20:02:20Z",
  "status": "new",
  "_links": {
      "self": "/messages/email/10287",
      "recipients": "/messages/email/10287/recipients",
      "failed": "/messages/email/10287/recipients/failed",
      "sent": "/messages/email/10287/recipients/sent",
      "clicked": "/messages/email/10287/recipients/clicked",
      "opened": "/messages/email/10287/recipients/opened",
      "email_template":"/templates/email/new-template"
  }
}

email = client.email_messages.build
email.links[:email_template] = template.uuid
email.recipients.build(email:'jim@example.com', macros:{"name"=>"Jim", "confirmationUrl"=>"http://example.com/confirm?t=1234abcd"})
email.recipients.build(email:'amy@example.com', macros:{"name"=>"Amy", "confirmationUrl"=>"http://example.com/confirm?t=9876zyxw"})
email.recipients.build(email:'bill@example.com')
email.post
=> true

When you use an email template to create a new email message, your new email message will take on the values that are set in the template. In this case, our new email took on the subject, body, and macros values, so we did not have to specify those while creating the message.

Just because you don’t have to specify values already defined in a template doesn’t mean you can’t. In fact, TMS allows you to specify unique values for certain fields while using a template. For example, let’s send another new user confirmation email using our confirmation email template, but with a unique subject:

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "subject": "Welcome Bob!",
  "recipients": [
    { 
      "email": "bob@example.com", 
      "macros": {
          "name":"Bob",
          "confirmationUrl": "http://example.com/confirm?t=asdf1337"
      } 
    }
  ], 
  "_links": {
    "email_template": "new-template"
  }
}'

// RESPONSE BODY
{
  "subject":"Welcome Bob!",
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/agency_logo.png\"\u003e\u003c/img\u003e",
  "click_tracking_enabled": false,
  "errors_to": "me@example.com",
  "from_email": "me@example.com",
  "from_name": null,
  "macros": {
      "name":"New User"
  },
  "open_tracking_enabled": false,
  "reply_to": "me@example.com",
  "created_at": "2015-05-05T20:06:31Z",
  "status": "new",
  "_links": {
      "self": "/messages/email/10288",
      "recipients": "/messages/email/10288/recipients",
      "failed": "/messages/email/10288/recipients/failed",
      "sent": "/messages/email/10288/recipients/sent",
      "clicked": "/messages/email/10288/recipients/clicked",
      "opened": "/messages/email/10288/recipients/opened",
      "email_template":"/templates/email/10027"
  }
}

email = client.email_messages.build(subject: "Welcome Bob!")
email.links[:email_template] = template.uuid
email.recipients.build(email:'bob@example.com', macros:{"name"=>"Bob", "confirmationUrl"=>"http://example.com/confirm?t=asdf1337"})
email.post
=> true

Update an Email Template

Change comes to all things, including your templates. Let’s update our user confirmation email template to use a new logo and a more helpful signature:

Subject: Welcome!


Hello [[name]],

Thank you for signing up! To confirm your registration, please <a href="[[confirmationUrl]]">click here</a>.

Thank You

<img src="http://example.com/images/logos/pretty_logo.png"></img>

Have any questions? Email <a href="mailto:help@example.com">help@example.com</a>, and we will get right back to you.

Fortunately, updating the content, or the look and feel, of your template is as easy as a PUT:

curl -X PUT -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json"  https://tms.govdelivery.com/templates/email/10027 --data \
'{
     "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please <a href=\"[[confirmationUrl]]\">click here</a>.\n\nThank You\n\n<img src=\"http://example.com/images/logos/pretty_logo.png\"></img>\n\nHave any questions? Email <a href=\"mailto:help@example.com\">help@example.com</a>, and we will get right back to you."
}'

// RESPONSE BODY
{
  "id": 10027,
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/pretty_logo.png\"\u003e\u003c/img\u003e\n\nHave any questions? Email \u003ca href=\"mailto:help@example.com\"\u003ehelp@example.com\u003c/a\u003e, and we will get right back to you.",
  "subject": "Welcome!",
  "link_tracking_parameters": null,
  "macros": {
    "name": "New User",
    "confirmationUrl": "http://example.com/confirm?t=false"
  },
  "open_tracking_enabled": false,
  "click_tracking_enabled": false,
  "created_at": "2015-05-05T19:23:47Z",
  "_links": {
    "self": "/templates/email/10027",
    "account": "/accounts/10040",
    "from_address": "/from_addresses/10040"
  }
}

new_template_body = <<eob
Hello [[name]],

Thank you for signing up! To confirm your registration, please <a href="[[confirmationUrl]]">click here</a>.

Thank You

<img src="http://example.com/images/logos/pretty_logo.png"></img>

Have any questions? Email <a href="mailto:help@example.com">help@example.com</a>, and we will get right back to you.
eob

template.body = new_template_body
template.put
=> true

Summary Code Example

curl -X POST -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json"  https://tms.govdelivery.com/templates/email --data \
'{
    "uuid": "new-template_1",
    "subject": "Welcome!",
     "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please <a href=\"[[confirmationUrl]]\">click here</a>.\n\nThank You\n\n<img src=\"http://example.com/images/logos/agency_logo.png\"></img>",
     "macros": {
        "name": "New User",
        "confirmationUrl": "http://example.com/confirm?t=false"
    }
}'

// RESPONSE BODY
{
  "id": 10027,
  "uuid": "new-template_1",
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/agency_logo.png\"\u003e\u003c/img\u003e",
  "subject": "Welcome!",
  "link_tracking_parameters": null,
  "macros": {
    "name":"New User",
    "confirmationUrl": "http://example.com/confirm?t=false"
  },
  "open_tracking_enabled": false,
  "click_tracking_enabled": false,
  "created_at": "2015-05-05T19:23:47Z",
  "_links":{
    "self":"/templates/email/10027",
    "account":"/accounts/10040",
    "from_address":"/from_addresses/10040"
  }
}
curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "recipients": [
    { 
      "email": "jim@example.com", 
      "macros": {
          "name":"Jim",
          "confirmationUrl": "http://example.com/confirm?t=1234abcd"
      } 
    },
    { 
      "email": "amy@example.com", 
      "macros": {
          "name": "Amy",
          "confirmationUrl": "http://example.com/confirm?t=9876zyxw"
      } 
    },
    { 
      "email": "bill@example.com"
    }
  ], 
  "_links": {
    "email_template": "new-template"
  }
}'

// RESPONSE BODY
{
  "subject":"Welcome!",
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/agency_logo.png\"\u003e\u003c/img\u003e",
  "click_tracking_enabled": false,
  "errors_to": "me@example.com",
  "from_email": "me@example.com",
  "from_name": null,
  "macros": {
      "name":"New User"
  },
  "open_tracking_enabled": false,
  "reply_to": "me@example.com",
  "created_at": "2015-05-05T20:02:20Z",
  "status": "new",
  "_links": {
      "self": "/messages/email/10287",
      "recipients": "/messages/email/10287/recipients",
      "failed": "/messages/email/10287/recipients/failed",
      "sent": "/messages/email/10287/recipients/sent",
      "clicked": "/messages/email/10287/recipients/clicked",
      "opened": "/messages/email/10287/recipients/opened",
      "email_template":"/templates/email/new-template"
  }
}
curl -X POST -H "X-AUTH-TOKEN: YourSecretToken"  -H "Content-Type: application/json" https://tms.govdelivery.com/messages/email --data \
'{
  "subject": "Welcome Bob!",
  "recipients": [
    { 
      "email": "bob@example.com", 
      "macros": {
          "name":"Bob",
          "confirmationUrl": "http://example.com/confirm?t=asdf1337"
      } 
    }
  ], 
  "_links": {
    "email_template": "new-template"
  }
}'

// RESPONSE BODY
{
  "subject":"Welcome Bob!",
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/agency_logo.png\"\u003e\u003c/img\u003e",
  "click_tracking_enabled": false,
  "errors_to": "me@example.com",
  "from_email": "me@example.com",
  "from_name": null,
  "macros": {
      "name":"New User"
  },
  "open_tracking_enabled": false,
  "reply_to": "me@example.com",
  "created_at": "2015-05-05T20:06:31Z",
  "status": "new",
  "_links": {
      "self": "/messages/email/10288",
      "recipients": "/messages/email/10288/recipients",
      "failed": "/messages/email/10288/recipients/failed",
      "sent": "/messages/email/10288/recipients/sent",
      "clicked": "/messages/email/10288/recipients/clicked",
      "opened": "/messages/email/10288/recipients/opened",
      "email_template":"/templates/email/10027"
  }
}
curl -X PUT -H "X-AUTH-TOKEN: YourSecretToken" -H "Content-Type: application/json"  https://tms.govdelivery.com/templates/email/10027 --data \
'{
     "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please <a href=\"[[confirmationUrl]]\">click here</a>.\n\nThank You\n\n<img src=\"http://example.com/images/logos/pretty_logo.png\"></img>\n\nHave any questions? Email <a href=\"mailto:help@example.com\">help@example.com</a>, and we will get right back to you."
}'

// RESPONSE BODY
{
  "id": 10027,
  "body": "Hello [[name]],\n\nThank you for signing up! To confirm your registration, please \u003ca href=\"[[confirmationUrl]]\"\u003eclick here\u003c/a\u003e.\n\nThank You\n\n\u003cimg src=\"http://example.com/images/logos/pretty_logo.png\"\u003e\u003c/img\u003e\n\nHave any questions? Email \u003ca href=\"mailto:help@example.com\"\u003ehelp@example.com\u003c/a\u003e, and we will get right back to you.",
  "subject": "Welcome!",
  "link_tracking_parameters": null,
  "macros": {
    "name": "New User",
    "confirmationUrl": "http://example.com/confirm?t=false"
  },
  "open_tracking_enabled": false,
  "click_tracking_enabled": false,
  "created_at": "2015-05-05T19:23:47Z",
  "_links": {
    "self": "/templates/email/10027",
    "account": "/accounts/10040",
    "from_address": "/from_addresses/10040"
  }
}

client = GovDelivery::TMS::Client.new('YourSecretToken', api_root:'https://tms.govdelivery.com/')
template_body = <<eob
Hello [[name]],

Thank you for signing up! To confirm your registration, please <a href="[[confirmationUrl]]">click here</a>.

Thank You

<img src="http://example.com/images/logos/agency_logo.png"></img>
eob

template = client.email_templates.build(uuid: 'new_template-1',
                                        subject: 'Welcome!',
                                        body: template_body,
                                        macros: {"name"=>"New User", "confirmationUrl"=>"http://example.com/confirm?t=false"})
template.post
=> true
email = client.email_messages.build
email.links[:email_template] = template.uuid
email.recipients.build(email:'jim@example.com', macros:{"name"=>"Jim", "confirmationUrl"=>"http://example.com/confirm?t=1234abcd"})
email.recipients.build(email:'amy@example.com', macros:{"name"=>"Amy", "confirmationUrl"=>"http://example.com/confirm?t=9876zyxw"})
email.recipients.build(email:'bill@example.com')
email.post
=> true
email = client.email_messages.build(subject: "Welcome Bob!")
email.links[:email_template] = template.uuid
email.recipients.build(email:'bob@example.com', macros:{"name"=>"Bob", "confirmationUrl"=>"http://example.com/confirm?t=asdf1337"})
email.post
=> true
new_template_body = <<eob
Hello [[name]],

Thank you for signing up! To confirm your registration, please <a href="[[confirmationUrl]]">click here</a>.

Thank You

<img src="http://example.com/images/logos/pretty_logo.png"></img>

Have any questions? Email <a href="mailto:help@example.com">help@example.com</a>, and we will get right back to you.
eob

template.body = new_template_body
template.put
=> true

Use Personalized Content and Conditional Logic in Email Templates

You can use conditional logic and macros to further customize TMS messages while streamlining content management. These following methods for implementing personalized content can be used in tandem:

  • Macros: Let you include content personalized for the recipient.
  • Conditional logic: Determines when certain content is included in the email.

Macros

Macros are key-value pairs. Default macro keys and values are set when you create a template, and per-recipient values are set at the time the email is sent.

Notes about macros:

  • If a macro is not included in the TMS call, we look for a default value (set at time of template creation). If it’s not included in a call AND there is no default value, it is interpreted as nil.
  • Macro values must be strings
  • For ease of use, dates should be passed in as a string of the format YYYYMMDD. For example, ‘20180601’ represents the first of June of 2018. Datetimes should be passed in as a string of the format YYYYMMDDHHmmSS. For example, ‘20180326094511’ represents 9:45:11am on March 26th, 2018. Note that TMS handles dates and datetimes as simple strings, not as a special Date or Datetime type.
  • TMS does not currently have timezone support. Any datetimes in your templates & macros should not rely on timezones for evaluation.

Conditional Logic

Conditional logic is wrapped by {% %} tags. The following operators are supported:

Operator Description Notes
== Equals Evaluates to true or false (numbers and strings)
!= Not equals Evaluates to true or false (numbers and strings)
> Greater than Numbers only
< Less than Numbers only
>= Greater than or equal to Numbers only
<= Less than or equal to Numberes only
or Logical Or All ‘and’ statements are evaluated before ‘or’ statements
and Logical And All ‘and’ statements are evaluated before ‘or’ statements
contains Contains Only searches strings for substrings

Notes about conditional logic:

  • String comparisons are case sensitive (e.g., “granicus” does not equal “GRANICUS”).
  • Nil does not evaluate to false. Templates should be more specific when doing comparisons.
  • Note that & and are not valid conditional logic operators.

Examples

Date Ranges

Let’s say you are sending a notification to new business owners about quarterly estimated taxes. They are always due on the first day of the next quarter, so you want to send an email like this:

Dear Serena,

Your quarterly estimated tax payment is due April 1, 2017.

You can represent dates in TMS templates using the format YYYYMMDD, where YYYY is a four digit year (2017), MM is a two digit month (05), and DD is a two digit day (18).

The template would look like this:

Dear [[NAME]],

Your quarterly estimated tax payment is due 
{% assign ENROLL_DATE = ENROLL_DATE | plus: 0 %}
{% if (ENROLL_DATE >= 20170101 and ENROLL_DATE < 20170401) %}
  April 1, 2017.
{% elsif (ENROLL_DATE >= 20170401 and ENROLL_DATE < 20170701) %}
  July 1, 2017.
{% elsif (ENROLL_DATE >= 20170701 and ENROLL_DATE < 201701001) %}
  October 1, 2017.
{% elsif (ENROLL_DATE >= 201701001 and ENROLL_DATE < 201800101) %}
  January 1, 2018.
{% endif %}

The TMS call would include these macros:

"macros": {
    "name":"Serena",
    "ENROLL_DATE":"20170109"
}

Because ‘ENROLL_DATE’ meets the first condition, TMS will render the first block of text, emailing a due date of April 1, 2017. Note that you must use the assign tag for your date to convert it to an integer so comparison will be successful.

What if you need to change content based on a specific time of the day? Datetimes can easily be compared if you use the format YYYYMMDDHHmmSS, where YYYY is a four digit year (2017), MM is a two digit month (04), DD is a two digit day (18), HH is a two digit hour in 24 hour format (‘13’ for 1pm), mm is a two digit minute (54) and SS is a two digit second (12).

Thus, the above template can be modified to end enrollment periods at 5pm as follows:

Dear [[NAME]],

Your quarterly estimated tax payment is due 
{% assign ENROLL_DATE = ENROLL_DATE | plus: 0 %}
{% if (ENROLL_DATE >= 20170101170000 and ENROLL_DATE < 20170401170000) %}
  April 1, 2017.
{% elsif (ENROLL_DATE >= 20170401170000 and ENROLL_DATE < 20170701170000) %}
  July 1, 2017.
{% elsif (ENROLL_DATE >= 20170701170000 and ENROLL_DATE < 201701001170000) %}
  October 1, 2017.
{% elsif (ENROLL_DATE >= 201701001170000 and ENROLL_DATE < 201800101170000) %}
  January 1, 2018.
{% endif %}

And macros in the TMS call would look like this:

"macros": {
    "name":"Serena",
    "ENROLL_DATE":"20170109142123" /* 2:21:23pm on January 9th, 2017 */
}

State-Specific Conditions

Let’s say you are sending an enrollment follow-up, where most residents need to complete a form first. But residents of the state of Virginia qualify to be auto-enrolled.

The template would be structured like this:

{% if STATE == "VA" %}
    You are auto-enrolled.
{% else %}
    Complete this form.
{% endif %}

The TMS call would include these macros:

"macros": {
    "NAME": "Stephen";
    "PARTNER_ID": "5319008";
    "STATE": "VA"
}

Process Status Table

Let’s say you are sending an email to individuals about the curent status of their income tax submission. This email will include a table with information about which required steps have been completed and which are yet to be completed. To provide the most useful information to individuals, this email should only include the steps that are required for that individual, based on their sources of income.

The template would be structured like this:

Dear [[NAME]],

Here is the status of your income tax submission.

<table>
  <thead>
    <tr>
      <td>Step</td>
      <td>Status</td>
    </tr>
  </thead>
  <tbody>
    {% if STEP_W2 == "true" %}
    <tr>
      <td>Submit W2</td>
      <td> [[STEP_W2_TEXT]] </td>
    </tr>
    {% endif %}
    {% if STEP_MISC == "true" %}
    <tr>
      <td>Submit 1099-MISC</td>
      <td> [[STEP_MISC_TEXT]] </td>
    </tr>
    {% endif %}
    {% if STEP_INT == "true" %}
    <tr>
      <td>Submit 1099-INT</td>
      <td> [[STEP_INT_TEXT]] </td>
    </tr>
    {% endif %}
  </tbody>
</table>

An example TMS call would include these recipients and macros:

"recipients": [
  {
    "email": "jim@example.com",
	"macros": {
	  "NAME": "Jim",
	  "STEP_INT": "true",
	  "STEP_INT_TEXT": "Complete"
	}
  },
  {
  	"email": "sarah@example.com",
	"macros": {
	  "NAME": "Sarah",
	  "STEP_MISC_TEXT": "Incomplete",
	  "STEP_MISC": "true"
	}
  }
]

In this example, Jim is an employee of a company whereas Sarah is self-employed, so you only need to include the macros relevant for each of their income taxes. If a STEP macro is not included in a recipient’s macros, then it evaluates to FALSE and the email to that recipient will not include a table row for that step.

Here is the email Jim will receive:

Dear Jim, Here is the status of your income tax submission.

Step Status
Submit 1099-INT Completed

Here is the email Sarah will receive:

Dear Sarah,

Here is the status of your income tax submission.

Step Status
Submit 1099-MISC Incomplete