From da1690c8c4b5fc47ebd9c3a242295d98e29cf5e8 Mon Sep 17 00:00:00 2001
From: Niels Swimberghe <3382717+Swimburger@users.noreply.github.com>
Date: Fri, 20 May 2022 16:09:46 +0000
Subject: [PATCH 1/2] Add use case for substitutions

---
 docs/use-cases/README.md                      |  1 +
 ...ils-personalizations-with-substitutions.md | 77 +++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 docs/use-cases/multiple-emails-personalizations-with-substitutions.md

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..3c25e5d9d
--- /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: '<p>Ahoy {{name}}!</p>',
+  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('<p>Ahoy {{name}}!</p>');
+
+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.
\ No newline at end of file

From fac6c3eff8618d5e9c69cbcc752007009ce89a01 Mon Sep 17 00:00:00 2001
From: childish-sambino <sharrison@twilio.com>
Date: Fri, 3 Jun 2022 09:03:16 -0500
Subject: [PATCH 2/2] Update
 multiple-emails-personalizations-with-substitutions.md

---
 .../multiple-emails-personalizations-with-substitutions.md      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/use-cases/multiple-emails-personalizations-with-substitutions.md b/docs/use-cases/multiple-emails-personalizations-with-substitutions.md
index 3c25e5d9d..16659a41e 100644
--- a/docs/use-cases/multiple-emails-personalizations-with-substitutions.md
+++ b/docs/use-cases/multiple-emails-personalizations-with-substitutions.md
@@ -74,4 +74,4 @@ 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.
\ No newline at end of file
+Refer to [the SendGrid documentation](https://docs.sendgrid.com/for-developers/sending-email/personalizations) for more details about personalizations.