sendgrid-actionmailer 2.4.2 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94259db52788333029d0c8fc9160c054a0e0bef5fc40b0ff4a2f825c9a337e54
-  data.tar.gz: eee118a0ebb96bf3c098f6c5ec7a28ec832c2b116b4060d7ef25df18ef36d063
+  metadata.gz: 7e7c4317fb02b1c622b8142161339d320a1a0b49e10e2f1c8cf98c9c649e432f
+  data.tar.gz: 33772e1a2200cd9bdd239792b1e4c3339d13e662944afb3782399eeeaad7ac5e
 SHA512:
-  metadata.gz: 1cb7d6f1972707fa631f27512ab36cc219373ca36725b666d05dab7ea128d270f8454cb30d45b0bc4b7d2f0460ca1ae380a2af3410c585d919461b0994d51cf1
-  data.tar.gz: f2852025eecc5f5087a7e8b41df7cae42f93b4978acf3fb4c8a613f2a3f30eefa83b300affc72234b3f398505bab759a977473ee71a4cc8766c4eb27a3762263
+  metadata.gz: df22bdee0b6fbd56a2827d56b4115ec1cc62454e0ca8dc8b32bdd165699df16895a328c1b679868eee145424535b8b0f2ed0447e8e6f70e4154b6c962ed643c9
+  data.tar.gz: 5ceb138422116c59a4dd3d76a0197a1fe4f80dbbcdaadedf5969e328bda9a4091a5bf15f268c715d0f928ff7e8b912c5ace8556b41cbefb408124a740ce48e45

data/README.md

@@ -221,6 +221,38 @@ Data to provide for feeding the new dynamic templates in Sendgrid with valueable
 
 ```mail(to: 'example@email.com', subject: 'email subject', body: 'email body',  dynamic_template_data:{ variable_1: 'foo', variable_2: 'bar'})```
 
+### personalizations (json)
+
+Allows providing a customized [personalizations](https://sendgrid.com/docs/for-developers/sending-email/personalizations/) array for the v3 Mail Send endpoint. This allows customizing how an email is sent and also allows sending multiple different emails to different recipients with a single API call.
+
+The personalizations object supports:
+
+- "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.
+- "dynamic_template_data" - data for dynamic templates.
+
+The following should be noted about these personalization attributes:
+- to, cc, or bcc: if either to, cc, or bcc is also set when calling mail, those addresses provided to mail will be inserted as a separate personalization from the ones you provide. However, when using personalizations, you are not required to specify `to` when calling the mail function.
+- dynamic_template_data specified in the mail function will be merged with any dynamic_template_data specified in the personalizations object (with the personalizations object keys having priority).
+- Other fields set in the personalizations object will override any global parameters defined outside of personalizations.
+
+Also note that substitutions will not work with dynamic templates.
+
+Example usage:
+
+```
+mail(subject: 'default subject', 'email body', personalizations: [
+  { to: { email: 'example@example.com' }},
+  { to: { email: 'example2@example.com' }}
+])
+
+```
+
+
 ### Unsubscribe Links
 
 Sendgrid unfortunately uses <% %> for their default substitution syntax, which makes it incompatible with Rails templates. Their proposed solution is to use Personalization Substitutions with the v3 Mail Send Endpoint.  This gem makes that modification to make the following Rails friendly unsubscribe urls.

data/lib/sendgrid_actionmailer.rb

@@ -24,17 +24,15 @@ module SendGridActionMailer
         m.from = to_email(mail.from)
         m.reply_to = to_email(mail.reply_to)
         m.subject = mail.subject || ""
-        # https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/personalizations.html
-        m.add_personalization(to_personalizations(mail))
       end
 
+      add_personalizations(sendgrid_mail, mail)
       add_api_key(sendgrid_mail, mail)
       add_content(sendgrid_mail, mail)
       add_send_options(sendgrid_mail, mail)
       add_mail_settings(sendgrid_mail, mail)
       add_tracking_settings(sendgrid_mail, mail)
 
-
       response = perform_send_request(sendgrid_mail)
 
       settings[:return_response] ? response : self
@@ -75,20 +73,49 @@ module SendGridActionMailer
       end
     end
 
-    def to_personalizations(mail)
-      Personalization.new.tap do |p|
-        to_emails(mail.to).each { |to| p.add_to(to) }
-        to_emails(mail.cc).each { |cc| p.add_cc(cc) }
-        to_emails(mail.bcc).each { |bcc| p.add_bcc(bcc) }
+    def setup_personalization(mail, personalization_hash)
+      p = Personalization.new
 
+      (personalization_hash['to'] || []).each do |to|
+        p.add_to Email.new(email: to['email'], name: to['name'])
+      end
+      (personalization_hash['cc'] || []).each do |cc|
+        p.add_cc Email.new(email: cc['email'], name: cc['name'])
+      end
+      (personalization_hash['bcc'] || []).each do |bcc|
+        p.add_bcc Email.new(email: bcc['email'], name: bcc['name'])
+      end
+      (personalization_hash['headers'] || []).each do |header_key, header_value|
+        p.add_header Header.new(key: header_key, value: header_value)
+      end
+      (personalization_hash['substitutions'] || {}).each do |sub_key, sub_value|
+        p.add_substitution(Substitution.new(key: sub_key, value: sub_value))
+      end
+      (personalization_hash['custom_args'] || {}).each do |arg_key, arg_value|
+        p.add_custom_arg(CustomArg.new(key: arg_key, value: arg_value))
+      end
+      if personalization_hash['send_at']
+        p.send_at = personalization_hash['send_at']
+      end
+      if personalization_hash['subject']
+        p.subject = personalization_hash['subject']
+      end
+
+      if mail['dynamic_template_data'] || personalization_hash['dynamic_template_data']
         if mail['dynamic_template_data']
-          p.add_dynamic_template_data(json_parse(mail['dynamic_template_data'].value))
-        elsif mail['template_id'].nil?
-          p.add_substitution(Substitution.new(key: "%asm_group_unsubscribe_raw_url%", value: "<%asm_group_unsubscribe_raw_url%>"))
-          p.add_substitution(Substitution.new(key: "%asm_global_unsubscribe_raw_url%", value: "<%asm_global_unsubscribe_raw_url%>"))
-          p.add_substitution(Substitution.new(key: "%asm_preferences_raw_url%", value: "<%asm_preferences_raw_url%>"))
+          data = json_parse(mail['dynamic_template_data'].value, false)
+          data.merge!(personalization_hash['dynamic_template_data'] || {})
+        else
+          data = personalization_hash['dynamic_template_data']
         end
+        p.add_dynamic_template_data(data)
+      elsif mail['template_id'].nil?
+        p.add_substitution(Substitution.new(key: "%asm_group_unsubscribe_raw_url%", value: "<%asm_group_unsubscribe_raw_url%>"))
+        p.add_substitution(Substitution.new(key: "%asm_global_unsubscribe_raw_url%", value: "<%asm_global_unsubscribe_raw_url%>"))
+        p.add_substitution(Substitution.new(key: "%asm_preferences_raw_url%", value: "<%asm_preferences_raw_url%>"))
       end
+
+      p
     end
 
     def to_attachment(part)
@@ -139,6 +166,23 @@ module SendGridActionMailer
       JSON.parse(text.empty? ? '{}' : text.gsub(/:*\"*([\%a-zA-Z0-9_-]*)\"*(( *)=>\ *)/) { "\"#{$1}\":" }, symbolize_names: symbolize)
     end
 
+    def add_personalizations(sendgrid_mail, mail)
+      if (mail.to && mail.to.any?) || (mail.cc && mail.cc.any?) || (mail.bcc && mail.bcc.any?)
+        personalization = setup_personalization(mail, {})
+        to_emails(mail.to).each { |to| personalization.add_to(to) }
+        to_emails(mail.cc).each { |cc| personalization.add_cc(cc) }
+        to_emails(mail.bcc).each { |bcc| personalization.add_bcc(bcc) }
+        sendgrid_mail.add_personalization(personalization)
+      end
+
+      if mail['personalizations']
+        personalizations = json_parse('[' + mail['personalizations'].value + ']', false)
+        personalizations.each do |p|
+          sendgrid_mail.add_personalization(setup_personalization(mail, p))
+        end
+      end
+    end
+
     def add_send_options(sendgrid_mail, mail)
       if mail['template_id']
          sendgrid_mail.template_id = mail['template_id'].to_s

data/lib/sendgrid_actionmailer/version.rb

@@ -1,3 +1,3 @@
 module SendGridActionMailer
-  VERSION = '2.4.2'.freeze
+  VERSION = '2.5.0'.freeze
 end

data/spec/lib/sendgrid_actionmailer_spec.rb

@@ -3,6 +3,14 @@ require 'webmock/rspec'
 
 module SendGridActionMailer
   describe DeliveryMethod do
+    def stringify_keys(hash)
+      result = {}
+      hash.each_key do |key|
+        result[key.to_s] = hash[key]
+      end
+      result
+    end
+
     subject(:mailer) do
       DeliveryMethod.new(api_key: 'key')
     end
@@ -242,13 +250,37 @@ module SendGridActionMailer
         ])
       end
 
-      context 'send options' do
-        it 'sets a template_id' do
+      context 'template_id' do
+        before do
           mail['template_id'] = '1'
+        end
+
+        it 'sets a template_id' do
           mailer.deliver!(mail)
           expect(client.sent_mail['template_id']).to eq('1')
         end
 
+        it 'does not set unsubscribe substitutions' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'].first).to_not have_key('substitutions')
+        end
+      end
+
+      context 'without dynamic template data or a template id' do
+        it 'sets unsubscribe substitutions' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'].first).to have_key('substitutions')
+          substitutions = client.sent_mail['personalizations'].first['substitutions']
+          expect(substitutions).to eq({
+            '%asm_group_unsubscribe_raw_url%' => '<%asm_group_unsubscribe_raw_url%>',
+            '%asm_global_unsubscribe_raw_url%' => '<%asm_global_unsubscribe_raw_url%>',
+            '%asm_preferences_raw_url%' => '<%asm_preferences_raw_url%>'
+          })
+        end
+      end
+
+      context 'send options' do
+
         it 'sets sections' do
           mail['sections'] = {'%foo%' => 'bar'}
           mailer.deliver!(mail)
@@ -386,11 +418,20 @@ module SendGridActionMailer
         end
 
         context 'dynamic template data' do
+          let(:template_data) do
+            { variable_1: '1', variable_2: '2' }
+          end
+          
+          before { mail['dynamic_template_data'] = template_data }
+
           it 'sets dynamic_template_data' do
-            template_data = { variable_1: '1', variable_2: '2' }
-            mail['dynamic_template_data'] = template_data
             mailer.deliver!(mail)
-            expect(client.sent_mail['personalizations'].first['dynamic_template_data']).to eq(template_data)
+            expect(client.sent_mail['personalizations'].first['dynamic_template_data']).to eq({'variable_1' => '1', 'variable_2' => '2'})
+          end
+
+          it 'does not set unsubscribe substitutions' do
+            mailer.deliver!(mail)
+            expect(client.sent_mail['personalizations'].first).to_not have_key('substitutions')
           end
         end
 
@@ -509,6 +550,211 @@ module SendGridActionMailer
           expect(content['content_id'].class).to eq(String)
         end
       end
+
+      context 'with personalizations' do
+        let(:personalizations) do
+          [
+            {
+              'to' => [
+                {'email' => 'john1@example.com', 'name' => 'John 1'},
+                {'email' => 'john2@example.com', 'name' =>  'John 2'},
+              ]
+            },
+            {
+              'to' => [
+                {'email' => 'john3@example.com', 'name' => 'John 3'},
+                {'email' => 'john4@example.com'}
+              ],
+              'cc' => [
+                {'email' => 'cc@example.com'}
+              ],
+              'bcc' => [
+                {'email' => 'bcc@example.com'}
+              ],
+              'substitutions' => {
+                '%fname%' => 'Bob'
+              },
+              'subject' => 'personalized subject',
+              'send_at' => 1443636843,
+              'custom_args' => {
+                'user_id' => '343'
+              },
+              'headers' => {
+                'X-Test' => true
+              }
+            }
+          ]
+        end
+
+        before do
+          mail.to = nil
+          mail.cc = nil
+          mail.bcc = nil
+          mail['personalizations'] = personalizations
+        end
+
+        it 'sets the provided to address personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'].length).to eq(2)
+          expect(client.sent_mail['personalizations'][0]['to']).to eq(personalizations[0]['to'])
+          expect(client.sent_mail['personalizations'][1]['to']).to eq(personalizations[1]['to'])
+        end
+
+        it 'sets the provided cc address personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][0]).to_not have_key('cc')
+          expect(client.sent_mail['personalizations'][1]['cc']).to eq(personalizations[1]['cc'])
+        end
+
+        it 'sets the provided bcc address personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][0]).to_not have_key('bcc')
+          expect(client.sent_mail['personalizations'][1]['bcc']).to eq(personalizations[1]['bcc'])
+        end
+
+        it 'sets the provided subject personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][0]).to_not have_key('subject')
+          expect(client.sent_mail['personalizations'][1]['subject']).to eq(personalizations[1]['subject'])
+        end
+
+        it 'sets the provided headers personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][0]).to_not have_key('headers')
+          expect(client.sent_mail['personalizations'][1]['headers']).to eq(personalizations[1]['headers'])
+        end
+
+        it 'sets the provided custom_arg personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][0]).to_not have_key('custom_args')
+          expect(client.sent_mail['personalizations'][1]['custom_args']).to eq(personalizations[1]['custom_args'])
+        end
+
+        it 'sets the provided send_at personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][0]).to_not have_key('send_at')
+          expect(client.sent_mail['personalizations'][1]['send_at']).to eq(personalizations[1]['send_at'])
+        end
+
+        it 'sets the provided substitution personalizations' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][1]['substitutions']).to include(personalizations[1]['substitutions'])
+        end
+
+        it 'adds to the unsubscribe link substitutions' do
+          mailer.deliver!(mail)
+          expect(client.sent_mail['personalizations'][0]['substitutions']).to eq({
+            '%asm_group_unsubscribe_raw_url%' => '<%asm_group_unsubscribe_raw_url%>',
+            '%asm_global_unsubscribe_raw_url%' => '<%asm_global_unsubscribe_raw_url%>',
+            '%asm_preferences_raw_url%' => '<%asm_preferences_raw_url%>'
+          })
+          expect(client.sent_mail['personalizations'][1]['substitutions']).to include({
+            '%asm_group_unsubscribe_raw_url%' => '<%asm_group_unsubscribe_raw_url%>',
+            '%asm_global_unsubscribe_raw_url%' => '<%asm_global_unsubscribe_raw_url%>',
+            '%asm_preferences_raw_url%' => '<%asm_preferences_raw_url%>'
+          })
+        end
+
+        context 'with symbols used as keys' do
+          let(:personalizations) do
+            [
+              {
+                to: [
+                  { email: 'john1@example.com', name: 'John 1'}
+                ]
+              }
+            ]
+          end
+
+          it 'still works' do
+            mailer.deliver!(mail)
+            expect(client.sent_mail['personalizations'].length).to eq(1)
+            expected_to = personalizations[0][:to].map { |t| stringify_keys(t) }
+            expect(client.sent_mail['personalizations'][0]['to']).to eq(expected_to)
+          end
+        end
+
+        context 'dynamic template data passed into a personalizaiton' do
+          let(:personalization_data) do
+            {
+              'variable_1' => '1', 'variable_2' => '2'
+            }
+          end
+
+          let(:personalizations_with_dynamic_data) do
+            personalizations.tap do |p|
+              p[1]['dynamic_template_data'] = personalization_data
+            end
+          end
+
+          before do
+            mail['personalizations'] = nil
+            mail['personalizations'] = personalizations_with_dynamic_data
+          end
+
+          it 'sets the provided dynamic template data personalizations' do
+            mailer.deliver!(mail)
+            expect(client.sent_mail['personalizations'][0]).to_not have_key('dynamic_template_data')
+            expect(client.sent_mail['personalizations'][1]['dynamic_template_data']).to eq(personalization_data)
+          end
+
+          context 'dynamic template data is also set on the mail object' do
+            let(:mail_template_data) do
+              { 'variable_3' => '1', 'variable_4' => '2' }
+            end
+
+            before { mail['dynamic_template_data'] = mail_template_data }
+
+            it 'sets dynamic_template_data where not also provided as a personalization' do
+              mailer.deliver!(mail)
+              expect(client.sent_mail['personalizations'][0]['dynamic_template_data']).to eq(mail_template_data)
+            end
+
+            it 'merges the template data with a personalizations dynamic data' do
+              mailer.deliver!(mail)
+              expect(client.sent_mail['personalizations'][1]['dynamic_template_data']).to eq(
+                mail_template_data.merge(personalization_data)
+              )
+            end
+          end
+        end
+
+        context 'when to is set on mail object' do
+          before { mail.to = 'test@sendgrid.com' }
+
+          it 'adds that to address as a separate personalization' do
+            mailer.deliver!(mail)
+            expect(client.sent_mail['personalizations'].length).to eq(3)
+            expect(client.sent_mail['personalizations'][0]['to']).to eq([{"email"=>"test@sendgrid.com"}])
+            expect(client.sent_mail['personalizations'][1]['to']).to eq(personalizations[0]['to'])
+            expect(client.sent_mail['personalizations'][2]['to']).to eq(personalizations[1]['to'])
+          end
+        end
+
+        context 'when cc is set on mail object' do
+          before { mail.cc = 'test@sendgrid.com' }
+
+          it 'adds that cc address as a separate personalization' do
+            mailer.deliver!(mail)
+            expect(client.sent_mail['personalizations'].length).to eq(3)
+            expect(client.sent_mail['personalizations'][0]['cc']).to eq([{"email"=>"test@sendgrid.com"}])
+            expect(client.sent_mail['personalizations'][1]['cc']).to eq(personalizations[0]['cc'])
+            expect(client.sent_mail['personalizations'][2]['cc']).to eq(personalizations[1]['cc'])
+          end
+        end
+
+        context 'when bcc is set on mail object' do
+          before { mail.bcc = 'test@sendgrid.com' }
+
+          it 'adds that bcc address as a separate personalization' do
+            mailer.deliver!(mail)
+            expect(client.sent_mail['personalizations'].length).to eq(3)
+            expect(client.sent_mail['personalizations'][0]['bcc']).to eq([{"email"=>"test@sendgrid.com"}])
+            expect(client.sent_mail['personalizations'][1]['bcc']).to eq(personalizations[0]['bcc'])
+            expect(client.sent_mail['personalizations'][2]['bcc']).to eq(personalizations[1]['bcc'])
+          end
+        end
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sendgrid-actionmailer
 version: !ruby/object:Gem::Version
-  version: 2.4.2
+  version: 2.5.0
 platform: ruby
 authors:
 - Eddie Zaneski