feat: add support for Twilio Email

USE_CASES.md

@@ -11,14 +11,8 @@ This documentation provides examples for specific use cases. Please [open an iss
   * [Adding Attachments](#adding-attachments)
 * [How to Setup a Domain Authentication](#how-to-setup-a-domain-authentication)
 * [How to View Email Statistics](#how-to-view-email-statistics)
-* [Send a SMS Message](#send-a-sms-message)
-  * [1. Obtain a Free Twilio Account](#1-obtain-a-free-twilio-account)
-  * [2. Update Your Environment Variables](#2-update-your-environment-variables)
-    * [Mac](#mac)
-    * [Windows](#windows)
-  * [3. Install the Twilio Helper Library](#3-install-the-twilio-helper-library)
-  * [4. Setup Work](#4-setup-work)
-  * [5. Send an SMS](#5-send-an-sms)
+* [Send an Email With Twilio Email (Pilot)](#send-an-email-with-twilio-email-pilot)
+* [Send an SMS Message](#send-an-sms-message)
 
 <a name="transactional-templates"></a>
 # Transactional Templates
@@ -299,59 +293,98 @@ end
 
 ```
 
-<a name="sms"></a>
-# Send a SMS Message
+# Send an Email With Twilio Email (Pilot)
 
-Following are the steps to add Twilio SMS to your app:
-
-## 1. Obtain a Free Twilio Account
+### 1. Obtain a Free Twilio Account
 
 Sign up for a free Twilio account [here](https://www.twilio.com/try-twilio?source=sendgrid-ruby).
 
-## 2. Update Your Environment Variables
+### 2. Set Up Your Environment Variables
+
+The Twilio API allows for authentication using with either an API key/secret or your Account SID/Auth Token. You can create an API key [here](https://twil.io/get-api-key) or obtain your Account SID and Auth Token [here](https://twil.io/console).
 
-You can obtain your Account Sid and Auth Token from [twilio.com/console](https://twilio.com/console).
+Once you have those, follow the steps below based on your operating system.
 
-### Mac
+#### Linux/Mac
 
 ```bash
+echo "export TWILIO_API_KEY='YOUR_TWILIO_API_KEY'" > twilio.env
+echo "export TWILIO_API_SECRET='YOUR_TWILIO_API_SECRET'" >> twilio.env
+
+# or
+
 echo "export TWILIO_ACCOUNT_SID='YOUR_TWILIO_ACCOUNT_SID'" > twilio.env
 echo "export TWILIO_AUTH_TOKEN='YOUR_TWILIO_AUTH_TOKEN'" >> twilio.env
+```
+
+Then:
+
+```bash
 echo "twilio.env" >> .gitignore
 source ./twilio.env
 ```
 
-### Windows
+#### Windows
 
 Temporarily set the environment variable (accessible only during the current CLI session):
 
 ```bash
+set TWILIO_API_KEY=YOUR_TWILIO_API_KEY
+set TWILIO_API_SECRET=YOUR_TWILIO_API_SECRET
+
+: or
+
 set TWILIO_ACCOUNT_SID=YOUR_TWILIO_ACCOUNT_SID
 set TWILIO_AUTH_TOKEN=YOUR_TWILIO_AUTH_TOKEN
 ```
 
-Permanently set the environment variable (accessible in all subsequent CLI sessions):
+Or permanently set the environment variable (accessible in all subsequent CLI sessions):
 
 ```bash
+setx TWILIO_API_KEY "YOUR_TWILIO_API_KEY"
+setx TWILIO_API_SECRET "YOUR_TWILIO_API_SECRET"
+
+: or
+
 setx TWILIO_ACCOUNT_SID "YOUR_TWILIO_ACCOUNT_SID"
 setx TWILIO_AUTH_TOKEN "YOUR_TWILIO_AUTH_TOKEN"
 ```
 
-## 3. Install the Twilio Helper Library
-
-To install using [Bundler][bundler] grab the latest stable version:
+### 3. Initialize the Twilio Email Client
 
 ```ruby
-gem 'twilio-ruby', '~> 5.23.1'
+mail_client = TwilioEmail::API(username: ENV['TWILIO_API_KEY'], password: ENV['TWILIO_API_SECRET'])
+
+# or
+
+mail_client = TwilioEmail::API(username: ENV['TWILIO_ACCOUNT_SID'], password: ENV['TWILIO_AUTH_TOKEN'])
 ```
 
-To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install:
+This client has the same interface as the `SendGrid::API` client.
+
+# Send an SMS Message
+
+First, follow the above steps for creating a Twilio account and setting up environment variables with the proper credentials.
+
+Then, install the Twilio Helper Library. Add this line to your application's Gemfile:
+
+```bash
+gem 'twilio-ruby'
+```
+
+And then execute:
 
 ```bash
-gem install twilio-ruby -v 5.23.1
+bundle
 ```
 
-## 4. Setup Work
+Or install it yourself using:
+
+```bash
+gem install twilio-ruby
+```
+
+Finally, send a message.
 
 ```ruby
 require 'twilio-ruby'
@@ -362,11 +395,6 @@ auth_token = ENV['TWILIO_AUTH_TOKEN']
 
 # set up a client to talk to the Twilio REST API
 @client = Twilio::REST::Client.new account_sid, auth_token
-```
-
-## 5. Send an SMS
-
-```ruby
 @client.api.account.messages.create(
   from: '+14159341234',
   to: '+16105557069',

lib/sendgrid-ruby.rb

@@ -1,4 +1,6 @@
-require_relative 'sendgrid/client'
+require_relative 'sendgrid/base_interface'
+require_relative 'sendgrid/sendgrid'
+require_relative 'sendgrid/twilio_email'
 require_relative 'sendgrid/version'
 require_relative 'sendgrid/helpers/ip_management/ip_management'
 require_relative 'sendgrid/helpers/mail/asm'

lib/sendgrid/base_interface.rb

@@ -0,0 +1,36 @@
+require 'ruby_http_client'
+require_relative 'version'
+
+# Initialize the HTTP client
+class BaseInterface
+  attr_accessor :client
+  attr_reader :request_headers, :host, :version, :impersonate_subuser
+  # * *Args* :
+  #   - +auth+ -> authorization header value
+  #   - +host+ -> the base URL for the API
+  #   - +request_headers+ -> any headers that you want to be globally applied
+  #   - +version+ -> the version of the API you wish to access,
+  #                  currently only "v3" is supported
+  #   - +impersonate_subuser+ -> the subuser to impersonate, will be passed
+  #                              in the "On-Behalf-Of" header
+  #
+  def initialize(auth:, host:, request_headers: nil, version: nil, impersonate_subuser: nil)
+    @auth = auth
+    @host = host
+    @version = version ? version : 'v3'
+    @impersonate_subuser = impersonate_subuser
+    @user_agent = "sendgrid/#{SendGrid::VERSION};ruby"
+    @request_headers = JSON.parse('
+        {
+          "Authorization": "' + @auth + '",
+          "Accept": "application/json",
+          "User-Agent": "' + @user_agent + '"
+        }
+    ')
+    @request_headers['On-Behalf-Of'] = @impersonate_subuser if @impersonate_subuser
+
+    @request_headers = @request_headers.merge(request_headers) if request_headers
+    @client = SendGrid::Client.new(host: "#{@host}/#{@version}",
+                                   request_headers: @request_headers)
+  end
+end

lib/sendgrid/sendgrid.rb

@@ -0,0 +1,20 @@
+# Quickly and easily access the Twilio SendGrid API.
+module SendGrid
+  class API < BaseInterface
+    # * *Args* :
+    #   - +api_key+ -> your Twilio SendGrid API key
+    #   - +host+ -> the base URL for the API
+    #   - +request_headers+ -> any headers that you want to be globally applied
+    #   - +version+ -> the version of the API you wish to access,
+    #                  currently only "v3" is supported
+    #   - +impersonate_subuser+ -> the subuser to impersonate, will be passed
+    #                              in the "On-Behalf-Of" header
+    #
+    def initialize(api_key:, host: nil, request_headers: nil, version: nil, impersonate_subuser: nil)
+      auth = "Bearer #{api_key}"
+      host = 'https://api.sendgrid.com' unless host
+
+      super(auth: auth, host: host, request_headers: request_headers, version: version, impersonate_subuser: impersonate_subuser)
+    end
+  end
+end

lib/sendgrid/twilio_email.rb

@@ -0,0 +1,21 @@
+# Quickly and easily access the Twilio Email API.
+module TwilioEmail
+  class API < BaseInterface
+    # * *Args* :
+    #   - +username+ -> your Twilio Email API key SID or Account SID
+    #   - +password+ -> your Twilio Email API key secret or Account Auth Token
+    #   - +host+ -> the base URL for the API
+    #   - +request_headers+ -> any headers that you want to be globally applied
+    #   - +version+ -> the version of the API you wish to access,
+    #                  currently only "v3" is supported
+    #   - +impersonate_subuser+ -> the subuser to impersonate, will be passed
+    #                              in the "On-Behalf-Of" header
+    #
+    def initialize(username:, password:, host: nil, request_headers: nil, version: nil, impersonate_subuser: nil)
+      auth = "Basic #{Base64.strict_encode64("#{username}:#{password}")}"
+      host = 'https://email.twilio.com' unless host
+
+      super(auth: auth, host: host, request_headers: request_headers, version: version, impersonate_subuser: impersonate_subuser)
+    end
+  end
+end

spec/sendgrid/sendgrid_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe SendGrid::API do
+  describe '.new' do
+    it 'initializes correctly' do
+      mail_client = SendGrid::API.new(api_key: 'fake_key')
+      expect(mail_client.request_headers['Authorization']).to eq('Bearer fake_key')
+      expect(mail_client.host).to eq('https://api.sendgrid.com')
+    end
+  end
+end

spec/sendgrid/twilio_email_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe TwilioEmail::API do
+  describe '.new' do
+    it 'initializes correctly' do
+      mail_client = TwilioEmail::API.new(username: 'username', password: 'password')
+      expect(mail_client.request_headers['Authorization']).to eq('Basic dXNlcm5hbWU6cGFzc3dvcmQ=')
+      expect(mail_client.host).to eq('https://email.twilio.com')
+    end
+  end
+end