Personalization

The Twilio Email API uses LiquidJS templating to personalize email content for each recipient. Use it for simple variable replacement or advanced control flow such as if and unless.

Personalize emails inline

To personalize the subject, html, and text fields for each recipient, use the LiquidJS templating language. Enclose each variable name in double curly braces ({{ }}). For every variable in your content, include a matching key in the variables object for each recipient in the to array.

To get email messages to render properly, provide a default value for every variable. When a recipient's variables don't contain the corresponding data, the email message displays a generic value.

Personalize an email with inline variables

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "support@example.com",
6        "name": "Support Team"
7    },
8    "to": [
9        {
10            "address": "jane.doe@example.com",
11            "variables": {
12                "firstName": "Jane",
13                "lastName": "Doe"
14            }
15        },
16        {
17            "address": "john.doe@example.com",
18            "variables": {
19                "firstName": "John",
20                "lastName": "Doe"
21            }
22        }
23    ],
24    "content": {
25        "subject": "Hello {{ firstName | default: '\''there'\'' }}",
26        "html": "<html><body><p>Hey {{ firstName | default: '\''there'\'' }} {{ lastName }}, your order is ready.</p></body></html>",
27        "text": "Hey {{ firstName | default: '\''there'\'' }} {{ lastName }}, your order is ready."
28    }
29}' \
30-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Advanced templating

In addition to simple variable replacement, you can use control flow structures like if and unless. This lets you render parts of an email for only specific recipients.

Render content conditionally with Liquid control flow

1curl -X POST 'https://comms.twilio.com/v1/Emails' \
2-H 'Content-Type: application/json' \
3-d '{
4    "from": {
5        "address": "marketing@example.com",
6        "name": "Marketing Team"
7    },
8    "to": [
9        {
10            "address": "jane.doe@example.com",
11            "variables": {
12                "firstName": "Jane",
13                "plan": "premium"
14            }
15        },
16        {
17            "address": "john.doe@example.com",
18            "variables": {
19                "firstName": "John",
20                "plan": "free"
21            }
22        }
23    ],
24    "content": {
25        "subject": "Your monthly update, {{ firstName | default: '\''there'\'' }}",
26        "html": "<html><body><p>Hello {{ firstName | default: '\''there'\'' }}!</p>{% if plan == '\''premium'\'' %}<p>Thank you for being a premium member. Here are your exclusive benefits.</p>{% endif %}</body></html>",
27        "text": "Hello {{ firstName | default: '\''there'\'' }}! {% if plan == '\''premium'\'' %}Thank you for being a premium member. Here are your exclusive benefits.{% endif %}"
28    }
29}' \
30-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Next steps

To learn about tracking the status of your email sends, see Operations and Email Tracking.
To view delivery activity in the Console, see Email logs.