diff --git a/content/docs/for-developers/sending-email/personalizations.md b/content/docs/for-developers/sending-email/personalizations.md index 0b0e40fc55..b73448b198 100644 --- a/content/docs/for-developers/sending-email/personalizations.md +++ b/content/docs/for-developers/sending-email/personalizations.md @@ -11,27 +11,52 @@ navigation: show: true --- +When sending an email with the v3 Mail Send endpoint, you define the various metadata about your message, such as the recipients, sender, subject, and send time, at the root level of a JSON request body. Personalizations allow you to override these various metadata for each email in an API request. -When sending an email with the v3 Mail Send endpoint, the various metadata about the message (such as the recipients, subject line, headers, substitutions, and custom arguments) are contained within an array called personalizations. - -Think of the personalizations section of the request body like the envelope of a letter: the fields defined within personalizations apply to each email, not the recipient. Like an envelope, personalizations are used to identify who should receive the email as well as specifics about how you would like the email to be handled. For example, you can define when you would like it to be sent, what headers you would like to include, and any substitutions or custom arguments you would like to be included with the email. +Personalizations is an array of objects. Think of the personalizations array like the envelope of a letter: the fields defined within personalizations apply to each email, not the recipient. Like an envelope, personalizations are used to identify who should receive the email as well as details about how you would like the email to be handled. For example, you can define when you would like it to be sent, what headers you would like to include, and any substitutions or custom arguments you would like to be included with the email. Personalizations allow you to define: -* "to", "cc", "bcc" - The recipients of your email. -* "subject" - The subject of your email. -* "headers" - Any headers you would like to include in your email. -* "substitutions" - Any substitutions you would like to be made for your email. -* "custom_args" - Any custom arguments you would like to include in your email. -* "send_at" - A specific time that you would like your email to be sent. +- "to", "cc", "bcc" - The recipients of your email. +- "from" - The sender or _return path_ address of your email. +- "subject" - The subject of your email. +- "headers" - Any headers you would like to include in your email. +- "substitutions" - Any substitutions you would like to be made for your email. +- "custom_args" - Any custom arguments you would like to include in your email. +- "send_at" - A specific time that you would like your email to be sent. -You must include at least one "to" object within the personalizations array. +You must include at least one `to` object within the personalizations array. -Since the `personalizations` parameter is an array, you may include multiple objects allowing you to specify different handling instructions for different copies of your email. For example, you could send the same email to both <john@example.com> and <janeexampexample@example.com>, but set each email to be delivered at different times. +Since the `personalizations` property is an array, you may include multiple objects allowing you to specify different handling instructions for different copies of your email. For example, you could 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@yourdomain.com", + "template_id": "YOUR TEMPLATE ID", + "personalizations": [ + { + "to": [ + { + "email": "john@example.com" + } + ], + "send_at": 1600188812 + }, + { + "to": [ + { + "email": "jane@example.com" + } + ], + "send_at": 1600275471 + } + ] +} +``` @@ -39,183 +64,315 @@ You may not include more than 1000 personalizations per API request. If you need -Some parameters can be defined both at the "message level" and at the "personalizations" level. - -For example, the subject, headers, custom arguments, and send_at parameters can all be defined globally or at the personalizations level. When SendGrid processes and validates your request, it first looks at the globally defined parameters. Then the personalizations you have specified are applied, overriding any duplicates already specified globally. +Some properties can be defined both at the root level of the request body (message level) and at the personalizations level. -Individual fields within the personalization array will override any other global, or "message level", parameters that are defined outside of personalizations. For example, the email subject defined within personalizations will override the subject defined at the message level in the JSON payload. +For example, the `from`, `subject`, `headers`, `custom_arg`, and `send_at` properties can all be defined at the message level or at the personalizations level. Individual fields within the `personalizations` array will override any message level properties that are defined outside of personalizations. For example, the email subject defined within personalizations will override the subject defined at the message level in the JSON payload. -Keys within objects like custom_args will be merged. If any of the keys conflict, the keys in the personalizations object will replace the message level object’s keys. +Keys within objects such as `custom_args` will be merged. If any of the keys conflict, the keys in the `personalizations` object will replace the message level object’s keys. -All of the recipients in a single personalization object (either in the `to`, `cc`, or `bcc` fields) will see the same email, as defined by the data in that personalization, as such we do not allow duplicate emails between these 3 arrays in a single personalization. +All of the recipients in a single personalization object (specified in the `to`, `cc`, or `bcc` fields) will see the same email, as defined by the data in that personalization. Because of this, SendGrid does not allow duplicate email addresses among these three recipient arrays in a single personalization. Below are some examples of how you can use personalizations for various use cases. -Personalization Examples Index +## Personalization Examples -* [Sending a Single Email to a Single Recipient](#sending-a-single-email-to-a-single-recipient) -* [Sending a Single Email to a Single Recipient with a CC](#sending-a-single-email-to-a-single-recipient-with-a-cc) -* [Sending a Single Email to a Single Recipient with a CC and a BCC](#sending-a-single-email-to-a-single-recipient-with-a-cc-and-a-bcc) -* [Sending a Single Email to Multiple Recipients](#sending-the-same-email-to-multiple-recipients) -* [Sending a Single Email to a Single Recipient with Multiple CCs/BCCs](#sending-a-single-email-to-a-single-recipient-with-multiple-ccs/bccs) -* [Sending Two Different Emails to Two Different Groups of Recipients](#sending-two-different-emails-to-two-different-groups-of-recipients) +- [Sending a single email to a single recipient](#sending-a-single-email-to-a-single-recipient) +- [Sending a single email to a single recipient with substitutions](#sending-a-single-email-to-a-single-recipient-with-substitutions) +- [Sending a single email to a single recipient with a CC](#sending-a-single-email-to-a-single-recipient-with-a-cc) +- [Sending a single email to a single recipient with a CC and a BCC](#sending-a-single-email-to-a-single-recipient-with-a-cc-and-a-bcc) +- [Sending a single email from a single sender to multiple recipients](#sending-the-same-email-to-multiple-recipients) +- [Sending a single email from a single sender to a single recipient with multiple CCs/BCCs](#sending-a-single-email-to-a-single-recipient-with-multiple-ccs/bccs) +- [Sending two different emails to two different groups of recipients](#sending-two-different-emails-to-two-different-groups-of-recipients) +- [Sending multiple emails from multiple senders to multiple recipients](#sending-multiple-emails-from-multiple-senders-to-multiple-recipients) -## Sending a Single Email to a Single Recipient +### Sending a single email to a single recipient -The following example shows you what the personalization parameter would look like if you wanted to send a single email to a single recipient. +The following example shows you what the personalization property would look like if you wanted to send a single email to a single recipient. ```json { - "personalizations": [{ - "to": [{ - "email": "recipient@example.com" - }], - "substitutions": { - "%fname%": "recipient", - "%CustomerID%": "CUSTOMER ID GOES HERE" - }, - "subject": "YOUR SUBJECT LINE GOES HERE" - }] + "personalizations": [ + { + "to": [ + { + "email": "recipient@example.com" + } + ], + "subject": "YOUR SUBJECT LINE GOES HERE" + } + ] } ``` -## Sending a Single Email to a Single Recipient With a 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. +### Sending a single email to a single recipient with substitutions + +The following example shows you what the personalization property would look like if you wanted to send a single email to a single recipient with substitutions. ```json { - "personalizations": [{ - "to": [{ - "email": "recipient1@example.com" - }], - "cc": [{ - "email": "recipient2@example.com" - }], - "substitutions": { - "%fname%": "recipient", - "%CustomerID%": "CUSTOMER ID GOES HERE" - }, - "subject": "YOUR SUBJECT LINE GOES HERE" - }] + "personalizations": [ + { + "to": [ + { + "email": "recipient@example.com" + } + ], + "substitutions": { + "%fname%": "recipient", + "%CustomerID%": "CUSTOMER ID GOES HERE" + }, + "subject": "YOUR SUBJECT LINE GOES HERE" + } + ] } ``` -## Sending a Single Email to a Single Recipient With a CC and a BCC +### Sending a single email to a single recipient with a CC -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. +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" - }], - "bcc": [{ - "email": "recipient3@example.com" - }], - "substitutions": { - "%fname%": "recipient", - "%CustomerID%": "CUSTOMER ID GOES HERE" - } - }] + "personalizations": [ + { + "to": [ + { + "email": "recipient1@example.com" + } + ], + "cc": [ + { + "email": "recipient2@example.com" + } + ], + "subject": "YOUR SUBJECT LINE GOES HERE" + } + ] } ``` -## Sending the Same Email to Multiple Recipients +### Sending a single email to a single recipient with a CC and a BCC -The following shows how to send 1 email to 3 different recipients: recipient1@example.com, recipient2@example.com, and recipient3@example.com. These recipients will all be able to see each other on the email. +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" - }, { - "email": "recipient2@example.com" - }, { - "email": "recipient3@example.com" - }], - "substitutions": { - "%fname%": "recipient", - "%CustomerID%": "CUSTOMER ID GOES HERE" - }, - "subject": "YOUR SUBJECT LINE GOES HERE" - }] + "personalizations": [ + { + "to": [ + { + "email": "recipient1@example.com" + } + ], + "cc": [ + { + "email": "recipient2@example.com" + } + ], + "bcc": [ + { + "email": "recipient3@example.com" + } + ] + } + ] } ``` -## Sending a Single Email to a Single Recipient With Multiple CCs and BCCs - +### Sending the same email to multiple recipients + +The following shows how to send one email to three different recipients: `recipient1@example.com`, `recipient2@example.com`, and `recipient3@example.com`. These recipients will all be able to see each other on the email. + +```json +{ + "personalizations": [ + { + "to": [ + { + "email": "recipient1@example.com" + }, + { + "email": "recipient2@example.com" + }, + { + "email": "recipient3@example.com" + } + ], + "subject": "YOUR SUBJECT LINE GOES HERE" + } + ] +} +``` + +### Sending a single email to a single recipient with multiple CCs and BCCs + The following shows what personalizations are required to send the same email to one recipient, with multiple CCs and BCCs. ```json { - "personalizations": [{ - "to": [{ - "email": "recipient1@example.com" - }], - "cc": [{ - "email": "recipient2@example.com" - }, { - "email": "recipient3@example.com" - }, { - "email": "recipient4@example.com" - }], - "substitutions": { - "%fname%": "recipient", - "%CustomerID%": "CUSTOMER ID GOES HERE" - }, - "subject": "YOUR SUBJECT LINE GOES HERE" - }] + "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" + } + ] +} +``` + +### Sending two different emails to two different groups of recipients + +The following shows how to send two different emails to two different groups of recipients. + +```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" + } + ] } ``` -## Sending Two Different Emails to Two Different Groups of Recipients +### Sending multiple emails from multiple senders to multiple recipients + +It is possible to specify multiple From addresses using personalizations. If a personalization object does not contain a `from` object, SendGrid will use the `email` address in the `from` object defined at the root level of the request body. -The following shows how to send 2 different emails to 2 different groups of recipients. +To successfully deliver email using multiple From addresses, the following conditions must be met. + +- A `from` object with an `email` property must be specified at the root level of the request body. +- The domain of the `from` `email` property specified in any personalization must match the domain of the `from` `email` property specified at root level of the request body—SendGrid will reject requests if these domains do not match. + +```json +// This is valid +{ + "from": { + "email": "support@example.com" + }, + "personalizations": [ + { + "from": { + "email": "noreply@example.com" + } + } + ] +} + +// This is invalid +{ + "from": { + "email": "support@example.com" + }, + "personalizations": [ + { + "from": { + "email": "noreply@differentexample.com" + } + } + ] +} +``` + +The following shows how to send multiple emails using three different `from` addresses on the same domain. + + + +You must complete [domain authentication]({{root_url}}/ui/account-and-settings/how-to-set-up-domain-authentication/) to send email from multiple addresses. SendGrid will reject requests from a sending domain that has not been authenticated. + + ```json { - "personalizations": [{ - "to": [{ - "email": "recipient1@example.com" - }], - "cc": [{ - "email": "recipient2@example.com" - }, { - "email": "recipient3@example.com" - }, { - "email": "recipient4@example.com" - }], - "substitutions": { - "%fname%": "recipient", - "%CustomerID%": "CUSTOMER ID GOES HERE" - }, - "subject": "YOUR SUBJECT LINE GOES HERE" - }, { - "to": [{ - "email": "recipient5@example.com" - }], - "cc": [{ - "email": "recipient6@example.com" - }, { - "email": "recipient7@example.com" - }, { - "email": "recipient8@example.com" - }], - "substitutions": { - "%fname%": "recipient2", - "%CustomerID%": 55 - }, - "subject": "YOUR SUBJECT LINE GOES HERE" - }] + "from": { + "email": "default@samedomain.com" + }, + "personalization": [ + { + "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" + } + } + ] } ``` diff --git a/content/docs/release-notes/2020-09-16.md b/content/docs/release-notes/2020-09-16.md new file mode 100644 index 0000000000..fbe09fbf6f --- /dev/null +++ b/content/docs/release-notes/2020-09-16.md @@ -0,0 +1,10 @@ +--- +title: 'release notes 2020-09-16' +date: 2020-09-16 +releaseType: + - api +--- + +### Specify multiple From addresses in personalizations + +Twilio SendGrid now allows you to define multiple From addresses in personalizations objects. This allows you to override the default sender in each personalization as long as the default sending domain and personalizations sending domains match. For more information, visit our [Personalizations documentation]({{root_url}}/for-developers/sending-email/personalizations/#sending-multiple-emails-from-multiple-senders-to-multiple-recipients). diff --git a/content/docs/ui/managing-contacts/create-and-manage-contacts.md b/content/docs/ui/managing-contacts/create-and-manage-contacts.md index 7a21c046a9..17e773a83d 100644 --- a/content/docs/ui/managing-contacts/create-and-manage-contacts.md +++ b/content/docs/ui/managing-contacts/create-and-manage-contacts.md @@ -22,12 +22,15 @@ The content on this page describes the experience in the latest version of Marke ## Add Contacts +You can add contacts to Marketing Campaigns by uploading a CSV, manually via the UI, using a Signup Form, or by integrating with the Contacts API. + Note that automations will only trigger to contacts who are added to an entry criteria list *after* the automation is set live. Contacts who you add to a list before the automation is set live will not receive any emails in the series. - + + ### Upload a CSV -You can add contacts to a list via CSV upload or by creating a Signup Form to automatically send signups to a list. +A common way to add contacts is to upload a CSV and map your data to custom fields. 1. Use [this CSV template]({{root_url}}/assets/example.csv) to make sure your CSV is formatted correctly. 1. Click **Add Contacts** and then select **Upload CSV**. diff --git a/content/docs/ui/managing-contacts/segmenting-your-contacts.md b/content/docs/ui/managing-contacts/segmenting-your-contacts.md index 09bcbc37b3..b89f39d9ca 100644 --- a/content/docs/ui/managing-contacts/segmenting-your-contacts.md +++ b/content/docs/ui/managing-contacts/segmenting-your-contacts.md @@ -22,6 +22,12 @@ The content on this page describes the experience in the latest version of Marke [Segments]({{root_url}}/glossary/segmentation/) are similar to contact lists, except they update dynamically over time as information stored about your contacts changes. When you segment your audience, you are able to create personalized Automation emails and Single Sends that directly address the wants and needs of your particular audience. + + +Marketing Campaigns supports up to 200 segments per user. + + + [Custom fields]({{root_url}}/ui/managing-contacts/custom-fields/), [reserved fields]({{root_url}}/glossary/reserved-fields/), and engagement data like opens and clicks, provide unique information you can use to identify contacts for different segments. As your contacts' traits change or you add more contacts that meet the criteria of your segment, your segments will update to reflect these changes. For example, a segment populated using the criteria, “lives in Denver” or, “is under 30 years old” will change as your contacts age or their addresses change. Segments can pull from _All Contacts_ or any of your more narrowly defined lists.