Substitution tags allow you to easily generate dynamic content for each recipient on your list. When you send to a list of recipients over SMTP API you can specify substitution tags specific to each recipient. For example, a first name that will then be inserted into an opening greeting like the following, where each recipient sees -firstName- replaced with their first name.

1
"Dear -firstName-"

These tags can also be used in more complex scenarios. For example, you could use a -customerID- to build a custom URL that is specific to that user.

A customer specific ID can replace -customerID- in the URL within your email

1
<a href="http://example.com/customerOffer?id=-customerID-">Claim your offer!</a>

Substitution tags will work in the Subject line as well as the body of the email.

How you format your substitution tags may depend on the library you use to create your SMTP connection, the language you are writing your code in, or any intermediate mail servers that your servers will send mail through. In some cases -subVal- may be the best choice while in other %subVal% or #subVal# may make more sense. It is best to avoid characters that have special meaning in html, such as <,>, and &. These might end up encoded and will not be properly substituted.

Do not use spaces inside your substitution tags, e.g. %first name%

Substitution Tag Example

Email HTML content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<html>
  <head></head>
  <body>
    <p>Hello -name-,<br>
       Thank you for your interest in our products. I have set up an appointment
             to call you at -time- EST to discuss your needs in more detail. If you would
             like to reschedule this call please visit the following link:
             <a href="http://example.com/reschedule?id=-customerID-">reschedule</a>

                Regards,

                -salesContact-
                -contactPhoneNumber-<br>
    </p>
  </body>
</html>

An accompanying SMTP API JSON header might look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "to": [
    "john.doe@gmail.com",
    "jane.doe@hotmail.com"
  ],
  "sub": {
    "-name-": [
      "John",
      "Jane"
    ],
    "-customerID-": [
      "1234",
      "5678"
    ],
    "-salesContact-": [
      "Jared",
      "Ben"
    ],
    "-contactPhoneNumber-": [
      "555.555.5555",
      "777.777.7777"
    ],
    "-time-": [
      "3:00pm",
      "5:15pm"
    ]
  }
}

The resulting email for John would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<html>
  <head></head>
  <body>
    <p>Hello John,<br>
       Thank you for your interest in our products. I have set up an appointment
             to call you at 3:00pm EST to discuss your needs in more detail. If you would
             like to reschedule this call please visit the following link:
             <a href="http://example.com/reschedule?id=1234">reschedule</a>

                Regards,

                Jared
                555.555.5555<br>
    </p>
  </body>
</html>

In contrast, the resulting email for Jane will look like the following, with her specific values replaced in for each tag:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<html>
  <head></head>
  <body>
    <p>Hello Jane,<br>
       Thank you for your interest in our products. I have set up an appointment
             to call you at 5:15pm EST to discuss your needs in more detail. If you would
             like to reschedule this call please visit the following link:
             <a href="http://example.com/reschedule?id=5678">reschedule</a>

                Regards,

                Ben
                777.777.7777<br>
    </p>
  </body>
</html>

Nested Substitutions

You can have up to 4 nested substitutions. Any deeper nesting will result in the tag being printed in your email.

Example: substitution1 replaced by substitution2 replaced by substitution3 replaced by substitution4 replaced by [substitution5] - the email shows “[substitution5]”

This works for section tags as well:

Example: substitution1 replaced by section1 replaced by substitution2 replaced by section2 replaced by [substitution5] – the email shows “[substitution5]”

Please note:

  • Substitution tags within section tags work
  • Section tags within substitution tags work
  • Section tags within section tags work
  • Section tags can only be added via substitution tags