sendgrid-ruby 5.1.0 → 5.2.0

data/USE_CASES.md

@@ -2,9 +2,11 @@ This documentation provides examples for specific use cases. Please [open an iss
 
 # Table of Contents
 
-* [Transactional Templates](#transactional_templates)
+* [Transactional Templates](#transactional-templates)
+* [How to Setup a Domain Whitelabel](#domain-whitelabel)
+* [How to View Email Statistics](#email-statistics)
 
-<a name="transactional_templates"></a>
+<a name="transactional-templates"></a>
 # Transactional Templates
 
 For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing.
@@ -110,4 +112,32 @@ end
 puts response.status_code
 puts response.body
 puts response.headers
-```
+```
+
+## Adding Attachments
+
+```ruby
+attachment = Attachment.new
+attachment.content = Base64.strict_encode64(File.open(fpath, 'rb').read)
+attachment.type = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+attachment.filename = fname
+attachment.disposition = 'attachment'
+attachment.content_id = 'Reports Sheet'
+mail.add_attachment(attachment)
+
+```
+Attachments must be base64 encoded, using Base64's strict_encode64 where no line feeds are added.
+
+<a name="domain-whitelabel"></a>
+# How to Setup a Domain Whitelabel
+
+You can find documentation for how to setup a domain whitelabel via the UI [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/setup_domain_whitelabel.html) and via API [here](https://github.com/sendgrid/sendgrid-ruby/blob/master/USAGE.md#whitelabel).
+
+Find more information about all of SendGrid's whitelabeling related documentation [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/index.html).
+
+<a name="email-statistics"></a>
+# How to View Email Statistics
+
+You can find documentation for how to view your email statistics via the UI [here](https://app.sendgrid.com/statistics) and via API [here](https://github.com/sendgrid/sendgrid-ruby/blob/master/USAGE.md#stats).
+
+Alternatively, we can post events to a URL of your choice via our [Event Webhook](https://sendgrid.com/docs/API_Reference/Webhooks/event.html) about events that occur as SendGrid processes your email.

data/examples/helpers/stats/example.rb

@@ -0,0 +1,42 @@
+require 'sendgrid-ruby'
+require 'date'
+
+include SendGrid
+
+sg_client = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']).client
+stats = SendGrid::EmailStats.new(sendgrid_client: sg_client)
+
+# Fetch stats by day, between 2 dates
+from = Date.new(2017, 10, 01)
+to = Date.new(2017, 10, 12)
+
+email_stats = stats.by_day(from, to)
+
+email_stats.metrics
+
+if !email_stats.error?
+  email_stats.metrics.each do |metric|
+    puts "Date - #{metric.date}"
+    puts "Number of Requests - #{metric.requests}"
+    puts "Bounces - #{metric.bounces}"
+    puts "Opens - #{metric.opens}"
+    puts "Clicks - #{metric.clicks}"
+  end
+end
+
+# Fetch stats by week, between 2 dates for a category
+from = Date.new(2017, 10, 01)
+to = Date.new(2017, 10, 12)
+category = 'abcd'
+
+email_stats = stats.by_week(from, to, category)
+
+if !email_stats.error?
+  email_stats.metrics.each do |metric|
+    puts "Date - #{metric.date}"
+    puts "Number of Requests - #{metric.requests}"
+    puts "Bounces - #{metric.bounces}"
+    puts "Opens - #{metric.opens}"
+    puts "Clicks - #{metric.clicks}"
+  end
+end

data/lib/sendgrid-ruby.rb

@@ -22,3 +22,6 @@ require_relative 'sendgrid/helpers/mail/subscription_tracking'
 require_relative 'sendgrid/helpers/mail/substitution'
 require_relative 'sendgrid/helpers/mail/tracking_settings'
 require_relative 'sendgrid/helpers/settings/settings'
+require_relative 'sendgrid/helpers/stats/email_stats'
+require_relative 'sendgrid/helpers/stats/stats_response'
+require_relative 'sendgrid/helpers/stats/metrics'

data/lib/sendgrid/helpers/mail/email.rb

@@ -3,8 +3,12 @@ require 'json'
 module SendGrid
   class Email
     def initialize(email: nil, name: nil)
-      @email = email
-      @name = name
+      if name
+        @email = email
+        @name = name
+      else
+        @email, @name = split_email(email)
+      end
     end
 
     def email=(email)
@@ -23,6 +27,11 @@ module SendGrid
       @name
     end
 
+    def split_email(email)
+      split = /(?:(?<address>.+)\s)?<?(?<email>.+@[^>]+)>?/.match(email)
+      return split[:email], split[:address]
+    end
+
     def to_json(*)
       {
         'email' => self.email,

data/lib/sendgrid/helpers/settings/README.md

@@ -1,4 +1,4 @@
-**This module allows you to quickly and easily build a Settings object for retreiving or updating you SendGrid Settings.**
+**This module allows you to quickly and easily build a Settings object for retrieving or updating you SendGrid Settings.**
 
 # Quick Start
 
@@ -11,4 +11,4 @@ ruby examples/helpers/settings/example.rb
 ## Usage
 
 - See the [example](https://github.com/sendgrid/sendgrid-ruby/tree/master/examples/helpers/settings) for a complete working example.
-- [Documentation](https://sendgrid.com/docs/API_Reference/Web_API_v3/Settings/index.html)
+- [Documentation](https://sendgrid.com/docs/API_Reference/Web_API_v3/Settings/index.html)

data/lib/sendgrid/helpers/stats/email_stats.rb

@@ -0,0 +1,46 @@
+require 'json'
+
+module SendGrid
+  class EmailStats
+    def initialize(args)
+      @sendgrid_client = args[:sendgrid_client]
+    end
+
+    def by_day(start_date, end_date, categories = nil, subusers = nil)
+      get('day', start_date, end_date, categories, subusers)
+    end
+
+    def by_week(start_date, end_date, categories = nil, subusers = nil)
+      get('week', start_date, end_date, categories, subusers)
+    end
+
+    def by_month(start_date, end_date, categories = nil, subusers = nil)
+      get('month', start_date, end_date, categories, subusers)
+    end
+
+    def get(aggregated_by, start_date, end_date, categories = nil, subusers = nil)
+      params = query_params(aggregated_by, start_date, end_date, categories, subusers)
+
+      response_body = @sendgrid_client.stats.get(query_params: params).body
+      build_response(response_body)
+    end
+
+    private
+
+    def query_params(aggregated_by, start_date, end_date, categories, subusers)
+      params = {
+        aggregated_by: aggregated_by,
+        start_date: start_date,
+        end_date: end_date
+      }
+      params.merge(categories: categories) if categories
+      params.merge(subusers: subusers) if subusers
+      params
+    end
+
+    def build_response(response_body)
+      response_json = JSON.parse(response_body)
+      StatsResponse.new(response_json)
+    end
+  end
+end

data/lib/sendgrid/helpers/stats/metrics.rb

@@ -0,0 +1,35 @@
+require 'json'
+
+module SendGrid
+  class Metrics
+    attr_reader :blocks, :bounce_drops,
+      :bounces, :clicks, :deferred, :delivered,
+      :invalid_emails, :opens, :processed, :requests,
+      :spam_report_drops, :spam_reports, :unique_clicks,
+      :unique_opens, :unsubscribe_drops, :unsubscribes
+
+    def initialize(args={})
+      @date = args['date']
+      @blocks = args['blocks']
+      @bounce_drops = args['bounce_drops']
+      @bounces = args['bounces']
+      @clicks = args['clicks']
+      @deferred = args['deferred']
+      @delivered = args['delivered']
+      @invalid_emails = args['invalid_emails']
+      @opens = args['opens']
+      @processed = args['processed']
+      @requests = args['requests']
+      @spam_report_drops = args['spam_report_drops']
+      @spam_reports = args['spam_reports']
+      @unique_clicks = args['unique_clicks']
+      @unique_opens = args['unique_opens']
+      @unsubscribe_drops = args['unsubscribe_drops']
+      @unsubscribes = args['unsubscribes']
+    end
+
+    def date
+      Date.parse(@date)
+    end
+  end
+end

data/lib/sendgrid/helpers/stats/stats_response.rb

@@ -0,0 +1,31 @@
+require 'json'
+
+module SendGrid
+  class StatsResponse
+    def initialize(args)
+      @errors = args['errors'] if args.is_a? Hash
+      @stats = args if args.is_a? Array
+    end
+
+    def errors
+      @errors.map do |error|
+        error['message']
+      end
+    end
+
+    def error?
+      !@errors.nil?
+    end
+
+    def metrics
+      @stats.flat_map do |stat|
+        starting_date = stat['date']
+        all_stats_for_date = stat['stats']
+
+        metrics = all_stats_for_date.map do |metric|
+          Metrics.new(metric['metrics'].merge('date' => starting_date))
+        end
+      end
+    end
+  end
+end

data/lib/sendgrid/version.rb

@@ -1,3 +1,3 @@
 module SendGrid
-  VERSION = '5.1.0'
+  VERSION = '5.2.0'
 end

data/mail_helper_v3.md

@@ -16,9 +16,14 @@ to = SendGrid::Email.new('test@example.com', 'Example User')
 subject = 'Sending with SendGrid is Fun'
 plain_text_content = 'and easy to do anywhere, even with Ruby'
 html_content = '<strong>and easy to do anywhere, even with Ruby</strong>'
-msg = SendGrid::Mail.create_single_email(from, to, subject, plain_text_content, html_content)
+msg = SendGrid::Mail.create(from: from,
+                            tos: to,
+                            subject: subject,
+                            plain_text_content: plain_text_content,
+                            html_content: html_content,
+                            substitutions: {})
 
-client = SendGrid::ClientFactory.new(api_key: ENV['SENDGRID_API_KEY'])
+client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
 
 begin
     response = client.send_email(msg)
@@ -38,7 +43,7 @@ The following code assumes you are storing the API key in an [environment variab
 require 'sendgrid-ruby'
 
 from = SendGrid::Email.new('test@example.com', 'Example User')
-tos = [ 
+tos = [
     SendGrid::Email.new('test1@example.com', 'Example User1'),
     SendGrid::Email.new('test2@example.com', 'Example User2'),
     SendGrid::Email.new('test3@example.com', 'Example User3')
@@ -46,13 +51,14 @@ tos = [
 subject = 'Sending with SendGrid is Fun'
 plain_text_content = 'and easy to do anywhere, even with Ruby'
 html_content = '<strong>and easy to do anywhere, even with Ruby</strong>'
-msg = SendGrid::Mail.create_single_email_to_multiple_recipients(from,
-                                                           tos,
-                                                           subject,
-                                                           plain_text_content,
-                                                           html_content)
+msg = SendGrid::Mail.create(from: from,
+                            tos: tos,
+                            subject: subject,
+                            plain_text_content: plain_text_content,
+                            html_content: html_content,
+                            substitutions: {})
 
-client = SendGrid::ClientFactory.new(api_key: ENV['SENDGRID_API_KEY'])
+client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
 
 begin
     response = client.send_email(msg)
@@ -72,7 +78,7 @@ The following code assumes you are storing the API key in an [environment variab
 require 'sendgrid-ruby'
 
 from = SendGrid::Email.new('test@example.com', 'Example User')
-tos = [ 
+tos = [
     SendGrid::Email.new('test1@example.com', 'Example User1'),
     SendGrid::Email.new('test2@example.com', 'Example User2'),
     SendGrid::Email.new('test3@example.com', 'Example User3')
@@ -92,14 +98,14 @@ values = [
 substitutions = {
     '-name1-' => values
 }
-msg = SendGrid::Mail.create_multiple_emails_to_multiple_recipients(from,
-                                                              tos,
-                                                              subjects,
-                                                              plain_text_content,
-                                                              html_content,
-                                                              substitutions)
+msg = SendGrid::Mail.create(from: from,
+                            tos: tos,
+                            subject: subjects,
+                            plain_text_content: plain_text_content,
+                            html_content: html_content,
+                            substitutions: substitutions)
 
-client = SendGrid::ClientFactory.new(api_key: ENV['SENDGRID_API_KEY'])
+client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
 
 begin
     response = client.send_email(msg)
@@ -116,33 +122,33 @@ puts response.headers
 The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 ```ruby
-client = SendGrid::ClientFactory.new(api_key: ENV['SENDGRID_API_KEY'])
+client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
 
 from = SendGrid::Email.new('test@example.com', 'Example User')
 to = SendGrid::Email.new('test@example.com', 'Example User')
 subject = 'Sending with SendGrid is Fun'
 plain_text_content = 'and easy to do anywhere, even with Ruby'
 html_content = '<strong>and easy to do anywhere, even with Ruby</strong>'
-msg = SendGrid::SendGridMessage.new(from, to, subject, plain_text_content, html_content)
+msg = SendGrid::Message.new(from, to, subject, plain_text_content, html_content)
 
 # For a detailed description of each of these settings, please see the [documentation](https://sendgrid.com/docs/API_Reference/api_v3.html).
 
 msg.add_to(SendGrid::Email.new('test1@example.com', 'Example User1'))
-to_emails = [ 
+to_emails = [
     SendGrid::Email.new('test2@example.com', 'Example User2'),
     SendGrid::Email.new('test3@example.com', 'Example User3')
 ];
 msg.add_tos(to_emails)
 
 msg.add_cc(SendGrid::Email.new('test4@example.com', 'Example User4'))
-cc_emails = [ 
+cc_emails = [
     SendGrid::Email.new('test5@example.com', 'Example User5'),
     SendGrid::Email.new('test6@example.com', 'Example User6')
 ];
 msg.add_ccs(cc_emails)
 
 msg.add_bcc(SendGrid::Email.new('test7@example.com', 'Example User7'))
-bcc_emails = [ 
+bcc_emails = [
     SendGrid::Email.new('test8@example.com', 'Example User8'),
     SendGrid::Email.new('test9@example.com', 'Example User9')
 ];
@@ -179,21 +185,21 @@ msg.set_subject('this subject overrides the Global Subject on the default Person
 # If you need to add more [Personalizations](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/personalizations.html), here is an example of adding another Personalization by passing in a personalization index.
 
 msg.add_to(SendGrid::Email.new('test10@example.com', 'Example User10'), 1)
-to_emails = [ 
+to_emails = [
     SendGrid::Email.new('test11@example.com', 'Example User11'),
     SendGrid::Email.new('test12@example.com', 'Example User12')
 ];
 msg.add_tos(to_emails, 1)
 
 msg.add_cc(SendGrid::Email.new('test13@example.com', 'Example User13'), 1)
-cc_emails = [ 
+cc_emails = [
     SendGrid::Email.new('test14@example.com', 'Example User14'),
     SendGrid::Email.new('test15@example.com', 'Example User15')
 ];
 msg.add_ccs(cc_emails, 1)
 
 msg.add_bcc(SendGrid::Email.new('test16@example.com', 'Example User16'), 1)
-bcc_emails = [ 
+bcc_emails = [
     SendGrid::Email.new('test17@example.com', 'Example User17'),
     SendGrid::Email.new('test18@example.com', 'Example User18')
 ];
@@ -292,16 +298,18 @@ puts response.headers
 The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key). If you don't have your key stored in an environment variable, you can assign it directly to `api_key` for testing purposes.
 
 ```ruby
-client = SendGrid::ClientFactory.new(api_key: ENV['SENDGRID_API_KEY'])
+client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
 
 from = SendGrid::Email.new('test@example.com', 'Example User')
 to = SendGrid::Email.new('test@example.com', 'Example User')
 subject = 'Sending with SendGrid is Fun'
 plain_text_content = 'and easy to do anywhere, even with Ruby'
 html_content = '<strong>and easy to do anywhere, even with Ruby</strong>'
-msg = SendGrid::SendGridMessage.new(from, to, subject, plain_text_content, html_content)
+msg = SendGrid::Message.new(from, to, subject, plain_text_content, html_content)
+bytes = File.read('/path/to/the/attachment.pdf')
+encoded = Base64.encode64(bytes)
 msg.add_attachment('balance_001.pdf',
-                   'base64 encoded content',
+                   encoded,
                    'application/pdf',
                    'attachment',
                    'Balance Sheet')
@@ -355,14 +363,14 @@ I hope you are having a great day in -city- :)
 ```
 
 ```ruby
-client = SendGrid::ClientFactory.new(api_key: ENV['SENDGRID_API_KEY'])
+client = SendGrid::Client.new(api_key: ENV['SENDGRID_API_KEY'])
 
 from = SendGrid::Email.new('test@example.com', 'Example User')
 to = SendGrid::Email.new('test@example.com', 'Example User')
 subject = 'Sending with SendGrid is Fun'
 plain_text_content = 'and easy to do anywhere, even with Ruby'
 html_content = '<strong>and easy to do anywhere, even with Ruby</strong>'
-msg = SendGrid::SendGridMessage.new(from, to, subject, plain_text_content, html_content)
+msg = SendGrid::Message.new(from, to, subject, plain_text_content, html_content)
 
 substitutions = [
     '-name-' => 'Example User',

data/spec/sendgrid/helpers/stats/email_stats_spec.rb

@@ -0,0 +1,112 @@
+require 'spec_helper'
+
+describe SendGrid::EmailStats do
+  let(:sg_client) { SendGrid::API.new(api_key: 'abcd').client }
+  let(:stats) { SendGrid::EmailStats.new(sendgrid_client: sg_client) }
+  let(:sg_response) { double('SendGrid::Response') }
+
+  let(:sample_response) do
+    [{
+      "date" => "2017-10-01",
+      "stats" => [
+        {"metrics" =>
+          {
+            "blocks" => 101,
+            "bounce_drops" => 102,
+            "bounces" => 103,
+            "clicks" => 104,
+            "deferred" => 105,
+            "delivered" => 106,
+            "invalid_emails" => 107,
+            "opens" => 108,
+            "processed" => 109,
+            "requests" => 110,
+            "spam_report_drops" => 111,
+            "spam_reports" => 112,
+            "unique_clicks" => 113,
+            "unique_opens" => 114,
+            "unsubscribe_drops" => 115,
+            "unsubscribes" => 116
+          }
+        }
+      ]
+    }]
+  end
+
+  let(:error_response) do
+    {
+      "errors" => [
+        {
+          "message" => "end_date should be a YYYY-MM-DD formatted date"
+        }
+      ]
+    }
+  end
+
+  describe '.new' do
+    it 'initializes with SendGrid::Client' do
+      expect(stats).to be_a SendGrid::EmailStats
+    end
+  end
+
+  describe 'successful response' do
+    before do
+      allow_any_instance_of(SendGrid::Response).to receive(:body) { sample_response.to_json }
+    end
+
+    describe '#by_day' do
+      it 'fetches data aggregated by day' do
+        day_stats = stats.by_day('2017-10-01', '2017-10-02')
+        day_metrics = day_stats.metrics.first
+
+        expect(day_metrics).to be_a SendGrid::Metrics
+        expect(day_metrics.date.to_s).to eq('2017-10-01')
+        expect(day_metrics.requests).to eq(110)
+        expect(day_metrics.clicks).to eq(104)
+        expect(day_metrics.bounces).to eq(103)
+        expect(day_metrics.opens).to eq(108)
+      end
+    end
+
+    describe '#by_week' do
+      it 'fetches data aggregated by week' do
+        day_stats = stats.by_week('2017-10-01', '2017-10-12')
+        day_metrics = day_stats.metrics.first
+
+        expect(day_metrics).to be_a SendGrid::Metrics
+        expect(day_metrics.date.to_s).to eq('2017-10-01')
+        expect(day_metrics.requests).to eq(110)
+        expect(day_metrics.clicks).to eq(104)
+        expect(day_metrics.bounces).to eq(103)
+        expect(day_metrics.opens).to eq(108)
+      end
+    end
+
+    describe '#by_month' do
+      it 'fetches data aggregated by month' do
+        day_stats = stats.by_month('2017-10-01', '2017-11-01')
+        day_metrics = day_stats.metrics.first
+
+        expect(day_metrics).to be_a SendGrid::Metrics
+        expect(day_metrics.date.to_s).to eq('2017-10-01')
+        expect(day_metrics.requests).to eq(110)
+        expect(day_metrics.clicks).to eq(104)
+        expect(day_metrics.bounces).to eq(103)
+        expect(day_metrics.opens).to eq(108)
+      end
+    end
+  end
+
+  describe 'error response' do
+    before do
+      allow_any_instance_of(SendGrid::Response).to receive(:body) { error_response.to_json }
+    end
+
+    it 'fetches data aggregated by month' do
+      day_stats = stats.by_month('2017-10-01', '2017-10-02')
+
+      expect(day_stats.errors).to include('end_date should be a YYYY-MM-DD formatted date')
+      expect(day_stats.error?).to be_truthy
+    end
+  end
+end