diff --git a/docs/use-cases/README.md b/docs/use-cases/README.md index cb66faae4..6800d1092 100644 --- a/docs/use-cases/README.md +++ b/docs/use-cases/README.md @@ -5,6 +5,7 @@ This documentation provides examples for specific Twilio SendGrid v3 API use cas * [Send a Single Email to Multiple Recipients](single-email-multiple-recipients.md) * [Send Multiple Emails to Multiple Recipients](multiple-emails-multiple-recipients.md) * [Send Multiple Emails with Personalizations](multiple-emails-personalizations.md) +* [Send Multiple Emails with Personalizations and Substitutions](multiple-emails-personalizations-with-substitutions.md) * [CC, BCC and Reply To](cc-bcc-reply-to.md) * [Flexible Email Address Fields](flexible-address-fields.md) * [Handling Success/Failure/Errors](success-failure-errors.md) diff --git a/docs/use-cases/multiple-emails-personalizations-with-substitutions.md b/docs/use-cases/multiple-emails-personalizations-with-substitutions.md new file mode 100644 index 000000000..16659a41e --- /dev/null +++ b/docs/use-cases/multiple-emails-personalizations-with-substitutions.md @@ -0,0 +1,77 @@ +# Send Multiple Emails with Personalizations and Substitutions + +Personalizations are an array of objects, each representing a separate email, that allow you to customize the metadata of each email sent within a request. With substitutions you can also have the email template dynamically be updated through [substitution tags](https://docs.sendgrid.com/for-developers/sending-email/substitution-tags). + +The below example shows how multiple emails, each with varying metadata and substitutions, are sent with personalizations. + +```js +const sgMail = require('@sendgrid/mail'); + +sgMail.setApiKey(process.env.SENDGRID_API_KEY); + +const msg = { + from: 'sender1@example.org', + subject: 'Ahoy!', + text: 'Ahoy {{name}}!', + html: '
Ahoy {{name}}!
', + personalizations: [ + { + to: 'recipient1@example.org', + substitutions: { + name: 'Jon' + } + }, + { + to: 'recipient2@example.org', + substitutions: { + name: 'Jane' + } + }, + { + to: 'recipient3@example.org', + substitutions: { + name: 'Jack' + } + } + ], +}; + +sgMail.send(msg); +``` + +The default `substitutionWrappers` are `{{` and `}}` in the node.js library, but you can change it using the `substitutionWrappers` property. + +You can also use the SendGrid helper classes to achieve the same outcome: + +```js +const sgMail = require('@sendgrid/mail'); +const sgHelpers = require('@sendgrid/helpers'); +const Mail = sgHelpers.classes.Mail; +const Personalization = sgHelpers.classes.Personalization; + +sgMail.setApiKey(process.env.SENDGRID_API_KEY); +const mail = new Mail(); +mail.setFrom('sender1@example.org'); +mail.setSubject('Ahoy'); +mail.addTextContent('Ahoy {{name}}!'); +mail.addHtmlContent('Ahoy {{name}}!
'); + +const personalization1 = new Personalization(); +personalization1.setTo('recipient1@example.org'); +personalization1.addSubstitution('name', 'Jon'); +mail.addPersonalization(personalization1); + +const personalization2 = new Personalization(); +personalization1.setTo('recipient2@example.org'); +personalization1.addSubstitution('name', 'Jane'); +mail.addPersonalization(personalization2); + +const personalization3 = new Personalization(); +personalization1.setTo('recipient3@example.org'); +personalization1.addSubstitution('name', 'Jack'); +mail.addPersonalization(personalization3); + +sgMail.send(mail); +``` + +Refer to [the SendGrid documentation](https://docs.sendgrid.com/for-developers/sending-email/personalizations) for more details about personalizations.