Personalizations

When sending an email with the v3 Mail Send endpoint, you define the various metadata about your message, like the recipients, sender, and subject, at the root level of a JSON request body. With Personalizations, you can override these various metadata for each email in an API request.

In the request body, you express Personalizations as an array of objects. The personalizations array workslike the envelope of a letter: the fields defined within personalizations apply to each email, not the recipient. Like an envelope, personalizations identify who should receive the email and how you want Twilio to handle the email.

(information)

Personalizations limit

Each API request has a limit of 1,000 personalization objects. To include more than 1,000, divide the objects across multiple API requests.

In the personalizations array, you can define:

Property	Necessity	Purpose
`to`	Required	The recipients of your email.
`cc`	Optional	The recipients of your email.
`bcc`	Optional	The recipients of your email.
`from`	Optional	The sender or return path address of your email.
`subject`	Optional	The subject line of your email.
`headers`	Optional	Any headers you want in your email.
`substitutions`	Optional	Any substitutions you want for your email.
`custom_args`	Optional	Any custom arguments you want in your email.
`send_at`	Optional	A specific time to send your email.

With the personalizations array, you can specify different handling instructions for different copies of your email.

(information)

Send messages at different times to different recipients

To send the same email to both john@example.com and jane@example.com but set each email to be delivered at different times.

1{
2  "from": "sender@example.com",
3  "template_id": "YOUR TEMPLATE ID",
4  "personalizations": [{
5    "to": [{
6      "email": "john@example.com"
7    }],
8    "send_at": 1600188812
9  },
10  {
11    "to": [{
12      "email": "jane@example.com"
13    }],
14    "send_at": 1600275471
15  }]
16}

Some properties can be defined both at the root level of the request body, or per message level, and at the personalizations level.
- These properties include from, subject, headers, custom_arg, and send_at.
Individual fields within the personalizations array override any message-level properties defined outside of personalizations.
Keys within objects such as custom_args get merged. If any of the keys conflict, the keys in the personalizations objects replace the message level object's keys.
No email address in any of the to, cc, or bcc properties can repeat within the same personalizations array.
Limit of 150 substitutions per personalization block.

Personalization examples

The following examples show how to use personalizations for common use cases, including sending to a single recipient, adding CC and BCC recipients, sending to multiple recipients, and sending from multiple senders.

Send one email to one recipient examples

One recipientWith substitutionsWith one CCWith one CC and one BCC

The following example shows you what the personalization property would look like if you wanted to send one email to one recipient.

1{
2  "personalizations": [{
3    "to": [{
4      "email": "recipient1@example.com"
5    }],
6    "cc": [{
7      "email": "recipient2@example.com"
8    }],
9    "subject": "YOUR SUBJECT LINE GOES HERE"
10  }]
11}

The following example shows the personalization property for sending a single email to a single recipient with substitutions.

1{
2  "personalizations": [{
3      "to": [{
4          "email": "recipient@example.com"
5        }],
6      "substitutions": {
7        "-fname-": "recipient",
8        "-CustomerID-": "CUSTOMER ID GOES HERE"
9      },
10      "subject": "YOUR SUBJECT LINE GOES HERE"
11    }]
12}

The following example shows how to send one email to recipient1@example.com with a carbon copy sent to recipient2@example@com. Both emails will have the same headers.

1{
2  "personalizations": [{
3    "to": [{
4      "email": "recipient1@example.com"
5    }],
6    "cc": [{
7      "email": "recipient2@example.com"
8    }],
9    "subject": "YOUR SUBJECT LINE GOES HERE"
10  }]
11}

The following example shows how to send one email to recipient1@example.com with a CC sent to recipient2@example.com and a BCC sent to recipient3@example.com.

1{
2  "personalizations": [{
3    "to": [{
4      "email": "recipient1@example.com"
5    }],
6    "cc": [{
7      "email": "recipient2@example.com"
8    }],
9    "bcc": [{
10      "email": "recipient3@example.com"
11    }]
12  }]
13}

Send email messages to many recipient examples

To many recipientsWith many CCs and BCCsTwo emails to two groups

To send one email to three different recipients, follow this example:

1{
2  "personalizations": [{
3    "to": [{
4      "email": "recipient1@example.com"
5      },{
6      "email": "recipient2@example.com"
7      },{
8      "email": "recipient3@example.com"
9    }],
10    "subject": "YOUR SUBJECT LINE GOES HERE"
11  }]
12}

All recipients can see all other recipients to the email.

To send one email to one recipient with multiple CCs and BCCs, follow this example:

1{
2  "personalizations": [{
3    "to": [{
4      "email": "recipient1@example.com"
5    }],
6    "cc": [{
7      "email": "recipient2@example.com"
8      },{
9      "email": "recipient3@example.com"
10      },{
11      "email": "recipient4@example.com"
12    }],
13    "bcc": [{
14      "email": "recipient5@example.com"
15      },{
16      "email": "recipient6@example.com"
17      },{
18      "email": "recipient7@example.com"
19    }],
20    "subject": "YOUR SUBJECT LINE GOES HERE"
21  }]
22}

To send two different emails to two different groups of recipients, follow this example:

1{
2  "personalizations": [{
3    "to": [{
4      "email": "recipient1@example.com"
5    }],
6    "cc": [{
7      "email": "recipient2@example.com"
8    },{
9      "email": "recipient3@example.com"
10    },{
11      "email": "recipient4@example.com"
12    }],
13    "subject": "YOUR SUBJECT LINE GOES HERE"
14  },{
15    "to": [{
16      "email": "recipient5@example.com"
17    }],
18    "cc": [{
19      "email": "recipient6@example.com"
20    },{
21      "email": "recipient7@example.com"
22    },{
23      "email": "recipient8@example.com"
24    }],
25    "subject": "YOUR SUBJECT LINE GOES HERE"
26  }]
27}

Send email messages from many senders examples

To send email messages from more than one sender, use personalizations.

Set a from.email property at the root level of the request body.
Add more from.email addresses in the personalizations array.
If a personalization object doesn't contain a from.email property, Twilio SendGrid uses the email address in the from.email property in the root level of the request body.

(warning)

Email address restrictions

Twilio SendGrid rejects requests from a sending domain under two conditions:

The domain of the from.email and personalizations.from.email don't match. All email messages must come from the same sending domain.
The sneding domain hasn't undergone domain authentication.

If these domains don't match or haven't been authenticated, Twilio SendGrid rejects the request.

To many recipientsMany emails to many recipients

To send email messages using multiple From addresses, following this example:

1// This is valid
2{
3  "from": {
4    "email": "support@example.com"
5  },
6  "personalizations": [{
7    "from": {
8      "email": "noreply@example.com"
9    }
10  }]
11}

1// This is invalid
2{
3  "from": {
4    "email": "support@example.com"
5  },
6  "personalizations": [{
7    "from": {
8      "email": "noreply@differentexample.com"
9    }
10  }]
11}