Personalizations

When you send an email message using the Mail Send v3 endpoint, you define properties about the email message: who sends it (from), who receives it (to), and what the message concerns (subject). The common name for these properties is metadata. If you want to send one email message to multiple recipients, you can customize the message sent to each recipient using Personalizations.

Write personalizations as an array of JSON objects in the API request body. The personalizations array works like the envelope of a letter: the properties you define within personalizations apply to the email message sent to the recipient. Like an envelope, personalizations identify who should receive the email and how Twilio should handle the email message. Each personalization object applies to one recipient, set with the to property.

(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.

Personalizations differ from Substitutions, which customize the content of an email message. Personalizations can include Substitutions, but Substitutions don't contain Personalizations.

Personalization object properties

In the personalizations array, you can customize one or more of the following properties for your email messages:

Property	Necessity	Purpose
`to`	Required	One or more intended addressed recipients displayed in your message.
`cc`	Optional	The additional recipients of your message displayed to the intended recipient.
`bcc`	Optional	The additional recipients of your message hidden from the intended recipient.
`from`	Optional	The email address displayed as the sender of your message.
`subject`	Optional	The subject line that your message displays.
`headers`	Optional	Any email metadata headers your message should include.
`substitutions`	Optional	Any message body substitution text your message should include.
`custom_args`	Optional	Any unique custom metadata your message should include.
`send_at`	Optional	The specific time that your message sends expressed in UNIX Epoch time.

Personalization array syntax

Within the personalizations array, you define handling instructions for different recipients of your email message.

Some properties you can define for each email message and each recipient.
- Message-level properties are defined at the root level of the request body.
- Recipient-level properties are defined in the personalizations array.
- These properties include from, subject, headers, custom_args, and send_at.
Individual properties 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 personalizations object keys override the message-level object keys.
You can't repeat email addresses in any of the to, cc, or bcc properties within the same personalizations array.
Each object in the personalizations array limits its substitutions object to 150 properties.

(information)

Example: 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}

Personalization examples

The following examples show how to use personalizations for common use cases. These use cases include 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}