Substitution tags allow you to 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.
"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 href="http://example.com/customerOffer?id=-customerID-">Claim your offer!</a>
Substitution tags will work in the Subject line, body of the email and in Unique Arguments.
Unique Arguments will be stored as a "Not PII" field and may be used for counting or other operations as SendGrid runs its systems. These fields generally cannot be redacted or removed. You should take care not to place PII in this field. SendGrid does not treat this data as PII, and its value may be visible to SendGrid employees, stored long-term, and may continue to be stored after you've left SendGrid's platform.
Substitutions are limited to 50,000 bytes per personalization block.
When passing substitutions please make sure to only use strings as shown in our examples. Any other type could result in unintended behavior.
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.
You can have up to 4 nested substitutions.
Do not use spaces inside your substitution tags, for example: %first name%
Do not nest substitution tags in substitutions as they will fail and your substitution will not take place.
Email HTML content:
1<html>2<head></head>3<body>4<p>5Hello -name-,<br />6Thank you for your interest in our products. I have set up an appointment7to call you at -time- EST to discuss your needs in more detail. If you8would like to reschedule this call, please visit the following link: `<a9href="http://example.com/reschedule?id=-customerID-"10>reschedule</a11>` Regards, -salesContact- -contactPhoneNumber-<br />12</p>13</body>14</html>
An accompanying SMTP API JSON header might look something like this:
1{2"to": ["example@example.com", "example@example.com"],3"sub": {4"-name-": ["John", "Jane"],5"-customerID-": ["1234", "5678"],6"-salesContact-": ["Jared", "Ben"],7"-contactPhoneNumber-": ["555.555.5555", "777.777.7777"],8"-time-": ["3:00pm", "5:15pm"]9}10}
The resulting email for John would look like this:
1<html>2<head></head>3<body>4<p>5Hello John,<br />6Thank you for your interest in our products. I have set up an appointment7to call you at 3:00 pm EST to discuss your needs in more detail. If you8would like to reschedule this call, please visit the following link:9<a href="http://example.com/reschedule?id=1234">reschedule</a>10Regards, Jared 555.555.555511</p>12</body>13</html>
In contrast, the resulting email for Jane will look like the following, with her specific values replaced in for each tag:
1<html>2<head></head>3<body>4<p>5Hello Jane,<br />6Thank you for your interest in our products. I have set up an appointment7to call you at 5:15pm EST to discuss your needs in more detail. If you8would like to reschedule this call please visit the following link:9<a href="http://example.com/reschedule?id=5678">reschedule</a>10Regards, Ben 777.777.777711</p>12</body>13</html>