feat: allow personalization of the From name and email for each email…

… recipient (#706) * feat: allow personalization of the From name and email for email recipients
sendgrid · Oct 21, 2021 · a2c71ef · a2c71ef
1 parent bb9c0ea
commit a2c71ef
Show file tree

Hide file tree

Showing 6 changed files with 87 additions and 6 deletions.
diff --git a/examples/helpers/mail/Example.java b/examples/helpers/mail/Example.java
@@ -57,22 +57,26 @@ public static Mail buildKitchenSink() {
     to2.setName("Example User");
     to2.setEmail("[email protected]");
     personalization2.addTo(to2);
+    Email fromEmail2 = new Email();
+    fromEmail2.setName("Example User");
+    fromEmail2.setEmail("[email protected]");
+    personalization2.setFrom(fromEmail2);
     to2.setName("Example User");
-    to2.setEmail("test2@example.com");
+    to2.setEmail("test3@example.com");
     personalization2.addTo(to2);
     Email cc2 = new Email();
     cc2.setName("Example User");
-    cc2.setEmail("test3@example.com");
+    cc2.setEmail("test4@example.com");
     personalization2.addCc(cc2);
     cc2.setName("Example User");
-    cc2.setEmail("test4@example.com");
+    cc2.setEmail("test5@example.com");
     personalization2.addCc(cc2);
     Email bcc2 = new Email();
     bcc2.setName("Example User");
-    bcc2.setEmail("test5@example.com");
+    bcc2.setEmail("test6@example.com");
     personalization2.addBcc(bcc2);
     bcc2.setName("Example User");
-    bcc2.setEmail("test6@example.com");
+    bcc2.setEmail("test7@example.com");
     personalization2.addBcc(bcc2);
     personalization2.setSubject("Hello World from the Personalized Twilio SendGrid Java Library");
     personalization2.addHeader("X-Test", "test");

diff --git a/examples/helpers/mail/MultipleEmailsMultipleRecipients.java b/examples/helpers/mail/MultipleEmailsMultipleRecipients.java
@@ -29,6 +29,7 @@ public static void main(String[] args) throws IOException {
 
     final Personalization personalization2 = new Personalization();
     personalization2.addTo(new Email("[email protected]", "Example User2"));
+    personalization2.setFrom(new Email("[email protected]", "Example User3"));
     personalization2.addDynamicTemplateData("name", "Example User2");
     personalization2.addDynamicTemplateData("city", "San Francisco");
     mail.addPersonalization(personalization2);

diff --git a/src/main/java/com/sendgrid/helpers/mail/objects/Personalization.java b/src/main/java/com/sendgrid/helpers/mail/objects/Personalization.java
@@ -15,6 +15,9 @@ public class Personalization {
   @JsonProperty("to")
   private List<Email> tos;
 
+  @JsonProperty("from")
+  private Email from;
+
   @JsonProperty("cc")
   private List<Email> ccs;
 
@@ -59,6 +62,15 @@ public void addTo(Email email) {
     }
   }
 
+  @JsonProperty("from")
+  public Email getFrom() {
+    return from;
+  }
+
+  public void setFrom(Email email) {
+    this.from = email;
+  }
+
   @JsonProperty("cc")
   public List<Email> getCcs() {
     if (ccs == null) {
@@ -260,6 +272,13 @@ public boolean equals(Object obj) {
     } else if (!tos.equals(other.tos)) {
       return false;
     }
+    if (from == null) {
+      if (other.from != null) {
+        return false;
+      }
+    } else if (!from.equals(other.from)) {
+      return false;
+    }
     return true;
   }
 }
diff --git a/src/test/java/com/sendgrid/helpers/MailTest.java b/src/test/java/com/sendgrid/helpers/MailTest.java
@@ -78,6 +78,10 @@ public void testKitchenSink() throws IOException {
     to2.setName("Example User");
     to2.setEmail("[email protected]");
     personalization2.addTo(to2);
+    Email fromEmail2 = new Email();
+    fromEmail2.setName("Example Sender");
+    fromEmail2.setEmail("[email protected]");
+    personalization2.setFrom(fromEmail2);
     Email cc2 = new Email();
     cc2.setName("Example User");
     cc2.setEmail("[email protected]");
@@ -110,6 +114,10 @@ public void testKitchenSink() throws IOException {
     to3.setName("Example User");
     to3.setEmail("[email protected]");
     personalization3.addTo(to3);
+    Email fromEmail3 = new Email();
+    fromEmail3.setName("Example Sender2");
+    fromEmail3.setEmail("[email protected]");
+    personalization3.setFrom(fromEmail3);
     Email cc3 = new Email();
     cc3.setName("Example User");
     cc3.setEmail("[email protected]");
@@ -247,7 +255,7 @@ public void testKitchenSink() throws IOException {
     replyTo.setEmail("[email protected]");
     mail.setReplyTo(replyTo);
 
-    Assert.assertEquals(mail.build(), "{\"from\":{\"name\":\"Example User\",\"email\":\"[email protected]\"},\"subject\":\"Hello World from the SendGrid Java Library\",\"personalizations\":[{\"to\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"cc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"bcc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"subject\":\"Hello World from the Personalized SendGrid Java Library\",\"headers\":{\"X-Mock\":\"true\",\"X-Test\":\"test\"},\"substitutions\":{\"%city%\":\"Denver\",\"%name%\":\"Example User\"},\"custom_args\":{\"type\":\"marketing\",\"user_id\":\"343\"},\"send_at\":1443636843},{\"to\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"cc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"bcc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"subject\":\"Hello World from the Personalized SendGrid Java Library\",\"headers\":{\"X-Mock\":\"true\",\"X-Test\":\"test\"},\"substitutions\":{\"%city%\":\"Denver\",\"%name%\":\"Example User\"},\"custom_args\":{\"type\":\"marketing\",\"user_id\":\"343\"},\"send_at\":1443636843},{\"to\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"cc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"bcc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"subject\":\"Hello World from the Personalized SendGrid Java Library\",\"headers\":{\"X-Mock\":\"true\",\"X-Test\":\"test\"},\"custom_args\":{\"type\":\"marketing\",\"user_id\":\"343\"},\"dynamic_template_data\":{\"city\":\"Denver\",\"items\":[{\"price\":\"$ 59.95\",\"text\":\"New Line Sneakers\"},{\"text\":\"Old Line Sneakers\"}],\"name\":\"Example User\"},\"send_at\":1443636843}],\"content\":[{\"type\":\"text/plain\",\"value\":\"some text here\"},{\"type\":\"text/html\",\"value\":\"<html><body>some text here</body></html>\"}],\"attachments\":[{\"content\":\"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3JhcyBwdW12\",\"type\":\"application/pdf\",\"filename\":\"balance_001.pdf\",\"disposition\":\"attachment\",\"content_id\":\"Balance Sheet\"},{\"content\":\"BwdW\",\"type\":\"image/png\",\"filename\":\"banner.png\",\"disposition\":\"inline\",\"content_id\":\"Banner\"}],\"template_id\":\"13b8f94f-bcae-4ec6-b752-70d6cb59f932\",\"sections\":{\"%section1%\":\"Substitution Text for Section 1\",\"%section2%\":\"Substitution Text for Section 2\"},\"headers\":{\"X-Test1\":\"1\",\"X-Test2\":\"2\"},\"categories\":[\"May\",\"2016\"],\"custom_args\":{\"campaign\":\"welcome\",\"weekday\":\"morning\"},\"send_at\":1443636842,\"asm\":{\"group_id\":99,\"groups_to_display\":[4,5,6,7,8]},\"ip_pool_name\":\"23\",\"mail_settings\":{\"bcc\":{\"enable\":true,\"email\":\"[email protected]\"},\"bypass_list_management\":{\"enable\":true},\"footer\":{\"enable\":true,\"text\":\"Footer Text\",\"html\":\"<html><body>Footer Text</body></html>\"},\"sandbox_mode\":{\"enable\":true},\"spam_check\":{\"enable\":true,\"threshold\":1,\"post_to_url\":\"https://spamcatcher.sendgrid.com\"}},\"tracking_settings\":{\"click_tracking\":{\"enable\":true,\"enable_text\":false},\"open_tracking\":{\"enable\":true,\"substitution_tag\":\"Optional tag to replace with the open image in the body of the message\"},\"subscription_tracking\":{\"enable\":true,\"text\":\"text to insert into the text/plain portion of the message\",\"html\":\"<html><body>html to insert into the text/html portion of the message</body></html>\",\"substitution_tag\":\"Optional tag to replace with the open image in the body of the message\"},\"ganalytics\":{\"enable\":true,\"utm_source\":\"some source\",\"utm_term\":\"some term\",\"utm_content\":\"some content\",\"utm_campaign\":\"some name\",\"utm_medium\":\"some medium\"}},\"reply_to\":{\"name\":\"Example User\",\"email\":\"[email protected]\"}}");
+    Assert.assertEquals(mail.build(), "{\"from\":{\"name\":\"Example User\",\"email\":\"[email protected]\"},\"subject\":\"Hello World from the SendGrid Java Library\",\"personalizations\":[{\"to\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"cc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"bcc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"subject\":\"Hello World from the Personalized SendGrid Java Library\",\"headers\":{\"X-Mock\":\"true\",\"X-Test\":\"test\"},\"substitutions\":{\"%city%\":\"Denver\",\"%name%\":\"Example User\"},\"custom_args\":{\"type\":\"marketing\",\"user_id\":\"343\"},\"send_at\":1443636843},{\"to\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"from\":{\"name\":\"Example Sender\",\"email\":\"[email protected]\"},\"cc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"bcc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"subject\":\"Hello World from the Personalized SendGrid Java Library\",\"headers\":{\"X-Mock\":\"true\",\"X-Test\":\"test\"},\"substitutions\":{\"%city%\":\"Denver\",\"%name%\":\"Example User\"},\"custom_args\":{\"type\":\"marketing\",\"user_id\":\"343\"},\"send_at\":1443636843},{\"to\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"from\":{\"name\":\"Example Sender2\",\"email\":\"[email protected]\"},\"cc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"bcc\":[{\"name\":\"Example User\",\"email\":\"[email protected]\"},{\"name\":\"Example User\",\"email\":\"[email protected]\"}],\"subject\":\"Hello World from the Personalized SendGrid Java Library\",\"headers\":{\"X-Mock\":\"true\",\"X-Test\":\"test\"},\"custom_args\":{\"type\":\"marketing\",\"user_id\":\"343\"},\"dynamic_template_data\":{\"city\":\"Denver\",\"items\":[{\"price\":\"$ 59.95\",\"text\":\"New Line Sneakers\"},{\"text\":\"Old Line Sneakers\"}],\"name\":\"Example User\"},\"send_at\":1443636843}],\"content\":[{\"type\":\"text/plain\",\"value\":\"some text here\"},{\"type\":\"text/html\",\"value\":\"<html><body>some text here</body></html>\"}],\"attachments\":[{\"content\":\"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3JhcyBwdW12\",\"type\":\"application/pdf\",\"filename\":\"balance_001.pdf\",\"disposition\":\"attachment\",\"content_id\":\"Balance Sheet\"},{\"content\":\"BwdW\",\"type\":\"image/png\",\"filename\":\"banner.png\",\"disposition\":\"inline\",\"content_id\":\"Banner\"}],\"template_id\":\"13b8f94f-bcae-4ec6-b752-70d6cb59f932\",\"sections\":{\"%section1%\":\"Substitution Text for Section 1\",\"%section2%\":\"Substitution Text for Section 2\"},\"headers\":{\"X-Test1\":\"1\",\"X-Test2\":\"2\"},\"categories\":[\"May\",\"2016\"],\"custom_args\":{\"campaign\":\"welcome\",\"weekday\":\"morning\"},\"send_at\":1443636842,\"asm\":{\"group_id\":99,\"groups_to_display\":[4,5,6,7,8]},\"ip_pool_name\":\"23\",\"mail_settings\":{\"bcc\":{\"enable\":true,\"email\":\"[email protected]\"},\"bypass_list_management\":{\"enable\":true},\"footer\":{\"enable\":true,\"text\":\"Footer Text\",\"html\":\"<html><body>Footer Text</body></html>\"},\"sandbox_mode\":{\"enable\":true},\"spam_check\":{\"enable\":true,\"threshold\":1,\"post_to_url\":\"https://spamcatcher.sendgrid.com\"}},\"tracking_settings\":{\"click_tracking\":{\"enable\":true,\"enable_text\":false},\"open_tracking\":{\"enable\":true,\"substitution_tag\":\"Optional tag to replace with the open image in the body of the message\"},\"subscription_tracking\":{\"enable\":true,\"text\":\"text to insert into the text/plain portion of the message\",\"html\":\"<html><body>html to insert into the text/html portion of the message</body></html>\",\"substitution_tag\":\"Optional tag to replace with the open image in the body of the message\"},\"ganalytics\":{\"enable\":true,\"utm_source\":\"some source\",\"utm_term\":\"some term\",\"utm_content\":\"some content\",\"utm_campaign\":\"some name\",\"utm_medium\":\"some medium\"}},\"reply_to\":{\"name\":\"Example User\",\"email\":\"[email protected]\"}}");
   }
 
   @Test

diff --git a/use-cases/README.md b/use-cases/README.md
@@ -5,6 +5,7 @@ Please [open an issue](https://github.com/sendgrid/sendgrid-ruby/issues) or [mak
 # Email Use Cases
 * [Transactional Templates](transactional-templates.md)
 * [Legacy Templates](legacy-templates.md)
+* [Personalizations](personalizations.md)
 
 # Twilio Use Cases
 * [Twilio Setup](twilio-setup.md)

diff --git a/use-cases/personalizations.md b/use-cases/personalizations.md
@@ -0,0 +1,48 @@
+# Personalizations
+
+This example goes over how to send multiple emails using personalizations with the helper class. 
+
+A similar example can be found in `examples/helpers/mail/MultipleEmailsMultipleRecipients.java`, and further documentation can be found [here](https://docs.sendgrid.com/for-developers/sending-email/personalizations).
+
+```java
+import com.sendgrid.*;
+import java.io.IOException;
+
+public class Example {
+    public static void main(String[] args) {
+        final Mail mail = new Mail();
+
+        // Note that the domain of the from addresses should be the same
+        mail.setFrom(new Email("[email protected]", "Example User"));
+        mail.setSubject("I'm the original subject");
+        mail.addContent(new Content("text/plain", "and this is some content"));
+        mail.addContent(new Content("text/html", "<strong>and this is some content</strong>"));
+
+        final Personalization personalization1 = new Personalization();
+        personalization1.addTo(new Email("[email protected]", "Example User1"));
+        personalization1.addCc(new Email("[email protected]", "Example User2"));
+        mail.addPersonalization(personalization1);
+
+        final Personalization personalization2 = new Personalization();
+        personalization2.addTo(new Email("[email protected]", "Example User3"));
+        personalization2.setFrom(new Email("[email protected]", "Example User4"));
+        personalization2.setSubject(new Subject("I'm the personalized subject"));
+        personalization2.addBcc(new Email("[email protected]", "Example User5"));
+        mail.addPersonalization(personalization2);
+
+        SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
+        Request request = new Request();
+        try {
+            request.setMethod(Method.POST);
+            request.setEndpoint("mail/send");
+            request.setBody(mail.build());
+            Response response = sg.api(request);
+            System.out.println(response.getStatusCode());
+            System.out.println(response.getBody());
+            System.out.println(response.getHeaders());
+        } catch (IOException ex) {
+            throw ex;
+        }
+    }
+}
+```