--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/sendgrid/for-developers/sending-email/personalizations#article headline: Personalizations description: Learn how to use personalizations to customize your messages sent using the Mail Send v3 REST API. url: https://www.twilio.com/docs/sendgrid/for-developers/sending-email/personalizations inLanguage: en dateModified: 2026-10-21T14:36:21.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # 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. > \[!NOTE] > > 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][custom arguments] 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 550 properties. > \[!NOTE] > > To send the same email to both `john@example.com` and `jane@example.com` but set each email to be delivered at different times. > > ```json > { > "from": "sender@example.com", > "template_id": "YOUR TEMPLATE ID", > "personalizations": [{ > "to": [{ > "email": "john@example.com" > }], > "send_at": 1600188812 > }, > { > "to": [{ > "email": "jane@example.com" > }], > "send_at": 1600275471 > }] > } > ``` ## 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 recipient The following example shows you what the personalization property would look like if you wanted to send one email to one recipient. ```json { "personalizations": [{ "to": [{ "email": "recipient1@example.com" }], "cc": [{ "email": "recipient2@example.com" }], "subject": "YOUR SUBJECT LINE GOES HERE" }] } ``` ## With substitutions The following example shows the personalization property for sending a single email to a single recipient with substitutions. ```json { "personalizations": [{ "to": [{ "email": "recipient@example.com" }], "substitutions": { "-fname-": "recipient", "-CustomerID-": "CUSTOMER ID GOES HERE" }, "subject": "YOUR SUBJECT LINE GOES HERE" }] } ``` ## With one CC 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. ```json { "personalizations": [{ "to": [{ "email": "recipient1@example.com" }], "cc": [{ "email": "recipient2@example.com" }], "subject": "YOUR SUBJECT LINE GOES HERE" }] } ``` ## With one CC and one BCC 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`. ```json { "personalizations": [{ "to": [{ "email": "recipient1@example.com" }], "cc": [{ "email": "recipient2@example.com" }], "bcc": [{ "email": "recipient3@example.com" }] }] } ``` ### Send email messages to many recipient examples ## To many recipients To send one email to three different recipients, follow this example: ```json { "personalizations": [{ "to": [{ "email": "recipient1@example.com" },{ "email": "recipient2@example.com" },{ "email": "recipient3@example.com" }], "subject": "YOUR SUBJECT LINE GOES HERE" }] } ``` All recipients can see all other recipients to the email. ## With many CCs and BCCs To send one email to one recipient with multiple CCs and BCCs, follow this example: ```json { "personalizations": [{ "to": [{ "email": "recipient1@example.com" }], "cc": [{ "email": "recipient2@example.com" },{ "email": "recipient3@example.com" },{ "email": "recipient4@example.com" }], "bcc": [{ "email": "recipient5@example.com" },{ "email": "recipient6@example.com" },{ "email": "recipient7@example.com" }], "subject": "YOUR SUBJECT LINE GOES HERE" }] } ``` ## Two emails to two groups To send two different emails to two different groups of recipients, follow this example: ```json { "personalizations": [{ "to": [{ "email": "recipient1@example.com" }], "cc": [{ "email": "recipient2@example.com" },{ "email": "recipient3@example.com" },{ "email": "recipient4@example.com" }], "subject": "YOUR SUBJECT LINE GOES HERE" },{ "to": [{ "email": "recipient5@example.com" }], "cc": [{ "email": "recipient6@example.com" },{ "email": "recipient7@example.com" },{ "email": "recipient8@example.com" }], "subject": "YOUR SUBJECT LINE GOES HERE" }] } ``` ### 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] > > 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 recipients To send email messages using multiple `From` addresses, following this example: ```json // This is valid { "from": { "email": "support@example.com" }, "personalizations": [{ "from": { "email": "noreply@example.com" } }] } ``` ```json // This is invalid { "from": { "email": "support@example.com" }, "personalizations": [{ "from": { "email": "noreply@differentexample.com" } }] } ``` ## Many emails to many recipients To send many email messages from more than one `from.email` addresses, follow this example: ```json { "from": { "email": "default@samedomain.com" }, "personalizations": [{ "subject": "YOUR SUBJECT LINE GOES HERE", "to": [{ "email": "recipient1@example1.com" }], "from": { "email": "sender1@samedomain.com" } },{ "subject": "YOUR SUBJECT LINE GOES HERE", "to": [{ "email": "recipient2@example2.com" }], "from": { "email": "sender2@samedomain.com" } },{ "subject": "YOUR SUBJECT LINE GOES HERE", "to": [{ "email": "recipient3@example3.com" }], "from": { "email": "sender3@samedomain.com" } }] } ``` [domain authentication]: /docs/sendgrid/ui/account-and-settings/how-to-set-up-domain-authentication [Substitutions]: /docs/sendgrid/ui/sending-email/substitution-and-section-tags [Mail Send v3]: /docs/sendgrid/api-reference/mail-send/mail-send [custom arguments]: /docs/sendgrid/for-developers/tracking-events/event#custom-arguments [headers]: /docs/sendgrid/glossary/header [UNIX Epoch time]: https://en.wikipedia.org/wiki/Unix_time