Personalization

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.

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

The Email API supports LiquidJS for advanced email templating.

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

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.