sendgrid-ruby 1.1.6 → 6.0.4

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2020, Twilio SendGrid, Inc. <help@twilio.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Makefile

@@ -0,0 +1,7 @@
+.PHONY: install test
+
+install:
+	gem install bundler:1.14.6; bundle install
+
+test:
+	bundle exec rake spec

data/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!--
+We appreciate the effort for this pull request but before that please make sure you read the contribution guidelines, then fill out the blanks below.
+
+Please format the PR title appropriately based on the type of change:
+  <type>[!]: <description>
+Where <type> is one of: docs, chore, feat, fix, test.
+Add a '!' after the type for breaking changes (e.g. feat!: new breaking feature).
+
+**All third-party contributors acknowledge that any contributions they provide will be made under the same open-source license that the open-source project is provided under.**
+
+Please enter each Issue number you are resolving in your PR after one of the following words [Fixes, Closes, Resolves]. This will auto-link these issues and close them when this PR is merged!
+e.g.
+Fixes #1
+Closes #2
+-->
+
+# Fixes #
+
+A short description of what this PR does.
+
+### Checklist
+- [ ] I acknowledge that all my contributions will be made under the project's license
+- [ ] I have made a material change to the repo (functionality, testing, spelling, grammar)
+- [ ] I have read the [Contribution Guidelines](CONTRIBUTING.md) and my PR follows them
+- [ ] I have titled the PR appropriately
+- [ ] I have updated my branch with the master branch
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have added necessary documentation about the functionality in the appropriate .md file
+- [ ] I have added inline documentation to the code I modified
+
+If you have questions, please file a [support ticket](https://twilio.com/help/contact), or create a GitHub Issue in this repository.

data/README.md

@@ -1,296 +1,232 @@
-# SendGrid::Ruby
+![Twilio SendGrid Logo](https://github.com/sendgrid/sendgrid-python/raw/master/twilio_sendgrid_logo.png)
 
-This Gem allows you to quickly and easily send emails through SendGrid's Web API using native Ruby.
+[![Travis Badge](https://travis-ci.org/sendgrid/sendgrid-ruby.svg?branch=master)](https://travis-ci.org/sendgrid/sendgrid-ruby) 
+[![Gem Version](https://badge.fury.io/rb/sendgrid-ruby.svg)](https://badge.fury.io/rb/sendgrid-ruby)
+[![Email Notifications Badge](https://dx.sendgrid.com/badge/ruby)](https://dx.sendgrid.com/newsletter/ruby)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE.md)
+[![Twitter Follow](https://img.shields.io/twitter/follow/sendgrid.svg?style=social&label=Follow)](https://twitter.com/sendgrid)
+[![GitHub contributors](https://img.shields.io/github/contributors/sendgrid/sendgrid-ruby.svg)](https://github.com/sendgrid/sendgrid-ruby/graphs/contributors)
+[![Open Source Helpers](https://www.codetriage.com/sendgrid/sendgrid-ruby/badges/users.svg)](https://www.codetriage.com/sendgrid/sendgrid-ruby)
 
-You can read our official documentation on the Web API's Mail feature [here](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
+**NEW:** Subscribe to email [notifications](https://dx.sendgrid.com/newsletter/ruby) for releases and breaking changes.
 
-[![BuildStatus](https://travis-ci.org/sendgrid/sendgrid-ruby.svg?branch=master)](https://travis-ci.org/sendgrid/sendgrid-ruby)
+**This library allows you to quickly and easily use the Twilio SendGrid Web API v3 via Ruby.**
 
+Version 3.X.X+ of this library provides full support for all Twilio SendGrid [Web API v3](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html) endpoints, including the new [v3 /mail/send](https://sendgrid.com/blog/introducing-v3mailsend-sendgrids-new-mail-endpoint).
 
-## Installation
+This library represents the beginning of a new path for Twilio SendGrid. We want this library to be community driven and Twilio SendGrid led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/sendgrid/sendgrid-ruby/issues) and [pull requests](https://github.com/sendgrid/sendgrid-ruby/blob/master/CONTRIBUTING.md) or simply upvote or comment on existing issues or pull requests.
 
-Add this line to your application's Gemfile:
+Please browse the rest of this README for further details.
 
-    gem 'sendgrid-ruby'
+We appreciate your continued support, thank you!
 
-And then execute:
+# Table of Contents
 
-    $ bundle
+* [Announcements](#announcements)
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Processing Inbound Email](#inbound)
+* [Usage](#usage)
+* [Use Cases](#use_cases)
+* [Announcements](#announcements)
+* [Roadmap](#roadmap)
+* [How to Contribute](#contribute)
+* [Troubleshooting](#troubleshooting)
+* [About](#about)
+* [License](#license)
 
-Or install it yourself using:
+<a name="announcements"></a>
+# Announcements
 
-    $ gem install sendgrid-ruby
+**NEW:** If you're a software engineer who is passionate about #DeveloperExperience and/or #OpenSource, [this is an incredible opportunity to join our #DX team](https://sendgrid.com/careers/role/1421152/?gh_jid=1421152) as a Developer Experience Engineer and work with [@thinkingserious](https://github.com/thinkingserious) and [@aroach](https://github.com/aroach)! Tell your friends :)
 
-## Usage
 
-Create a new client with your SendGrid Username and Password.
+<a name="installation"></a>
+# Installation
 
-```ruby
-require 'sendgrid-ruby'
-
-# As a hash
-client = SendGrid::Client.new(api_user: 'SENDGRID_USERNAME', api_key: 'SENDGRID_PASSWORD')
+## Prerequisites
 
-# Or as a block
-client = SendGrid::Client.new do |c|
-  c.api_user = 'SENDGRID_USERNAME'
-  c.api_key = 'SENDGRID_PASSWORD'
-end
+- Ruby version >= 2.2 (except version [2.6.0](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md#ruby-versions))
+- The Twilio SendGrid service, starting at the [free level](https://sendgrid.com/free?source=sendgrid-ruby)
 
-# or as a block with the API key only #
-client = SendGrid::Client.new do |c|
-  c.api_key = 'SENDGRID_APIKEY'
-end
-```
+## Setup Environment Variables
 
-Create a new Mail object and send:
-```ruby
-mail = SendGrid::Mail.new do |m|
-  m.to = 'test@sendgrid.com'
-  m.from = 'taco@cat.limo'
-  m.subject = 'Hello world!'
-  m.text = 'I heard you like pineapple.'
-end
-
-res = client.send(mail)
-puts res.code
-puts res.body
-# 200
-# {"message"=>"success"}
-```
+Update the development environment with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys), for example:
 
-You can also create a Mail object with a hash:
-```ruby
-res = client.send(SendGrid::Mail.new(to: 'example@example.com', from: 'taco@cat.limo', subject: 'Hello world!', text: 'Hi there!', html: '<b>Hi there!</b>'))
-puts res.code
-puts res.body
-# 200
-# {"message"=>"success"}
+```bash
+echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
+echo "sendgrid.env" >> .gitignore
+source ./sendgrid.env
 ```
+## Install Package
 
-#### Attachments
+Add this line to your application's Gemfile:
 
-Attachments can be added to a Mail object with the `add_attachment` method. The first parameter is the path to the file, the second (optional) parameter is the desired name of the file. If a file name is not provided, it will use the original filename.
-```ruby
-mail.add_attachment('/tmp/report.pdf', 'july_report.pdf')
+```bash
+gem 'sendgrid-ruby'
 ```
 
-#### Inline Content
+And then execute:
 
-Inline content can be added to a Mail object with the `add_content` method. The first parameter is the path to the file, the second parameter is the cid to be referenced in the html. 
-```ruby
-mail = SendGrid::Mail.new do |m|
-  m.to = 'test@sendgrid.com'
-  m.from = 'taco@cat.limo'
-  m.subject = 'Hello world!'
-  m.text = 'I heard you like the beach.'
-  m.html = 'I heard you like the beach <div><img src="cid:beach"></div>'
-end
-mail.add_content('/tmp/beach.jpg', 'beach')
-result = client.send(mail)
+```bash
+bundle
 ```
 
-#### Available Params
+Or install it yourself using:
 
-```ruby
-params = {
-	:to,
-	:to_name,
-	:from,
-	:from_name,
-	:subject,
-	:text,
-	:html,
-	:cc,
-	:cc_name,
-	:bcc,
-	:bcc_name,
-	:reply_to,
-	:date,
-	:smtpapi,
-	:attachments,
-	:template
-}
+```bash
+gem install sendgrid-ruby
 ```
 
-#### Setting Params
-
-Params can be set in the usual Ruby ways, including a block or a hash.
-
-````ruby
-mail = SendGrid::Mail.new do |m|
-  m.to = 'rbin@sendgrid.com'
-  m.from = 'taco@rbin.codes'
-end
-
-client.send(SendGrid::Mail.new(to: 'rbin@sendgrid.com', from: 'taco@cat.limo'))
-````
-
-#### :to
-
-Using the **:to** param, we can pass a single email address as a string, or an array of email address strings.
+## Dependencies
 
-````ruby
-mail = SendGrid::Mail.new
-mail.to = 'taco@rbin.codes'
-# or
-mail.to = ['Example Dude <example@email.com>', 'john@email.com']
-# or
-mail.to = ['rbin@sendgrid.com', 'taco@cat.limo']
-````
+- [Ruby-HTTP-Client](https://github.com/sendgrid/ruby-http-client)
 
-#### :from
+<a name="quick-start"></a>
+# Quick Start
 
-```ruby
-mail = SendGrid::Mail.new
-mail.from = 'me@sendgrid.com'
-```
-
-#### :cc
-
-As with **:to**, **:cc** can take a single string or an array of strings.
-
-```ruby
-mail = SendGrid::Mail.new
-mail.cc = ['robin@sendgrid.com', 'taco@cat.limo']
-```
+## Hello Email
 
-#### :bcc
+The following is the minimum needed code to send an email with the [/mail/send Helper](https://github.com/sendgrid/sendgrid-ruby/tree/master/lib/sendgrid/helpers/mail) ([here](https://github.com/sendgrid/sendgrid-ruby/blob/master/examples/helpers/mail/example.rb#L21) is a full example):
 
-As with **:to** and **:cc**, **:bcc** can take a single string or an array of strings.
+### With Mail Helper Class
 
 ```ruby
-mail = SendGrid::Mail.new
-mail.bcc = ['robin@sendgrid.com', 'taco@cat.limo']
-```
+require 'sendgrid-ruby'
+include SendGrid
 
-#### :subject
+from = SendGrid::Email.new(email: 'test@example.com')
+to = SendGrid::Email.new(email: 'test@example.com')
+subject = 'Sending with Twilio SendGrid is Fun'
+content = SendGrid::Content.new(type: 'text/plain', value: 'and easy to do anywhere, even with Ruby')
+mail = SendGrid::Mail.new(from, subject, to, content)
 
-```ruby
-mail = SendGrid::Mail.new
-mail.subject = 'This is a subject string'
+sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
+response = sg.client.mail._('send').post(request_body: mail.to_json)
+puts response.status_code
+puts response.body
+puts response.parsed_body
+puts response.headers
 ```
 
-### Email Bodies:
-#### :text
+For more complex scenarios, please do not use the above constructor and instead build your own personalization object as [demonstrated here](https://github.com/sendgrid/sendgrid-ruby/blob/master/examples/helpers/mail/example.rb#L21).
 
-Using the **:text** param allows us to add plain text to our email body.
+### Without Mail Helper Class
 
-```ruby
-mail = SendGrid::Mail.new
-mail.text = 'WHATTUP KITTY CAT!?'
-```
-
-#### :html
+The following is the minimum needed code to send an email without the /mail/send Helper ([here](https://github.com/sendgrid/sendgrid-ruby/blob/master/examples/mail/mail.rb#L26) is a full example):
 
-Using the **:html** param allows us to add html content to our email body.
 ```ruby
-mail = SendGrid::Mail.new
-mail.html = '<html><body>Stuff in here, yo!</body></html>'
-```
-
-#### :template
-
-The **:template** param allows us to specify a template object for this email to use. The initialized `Template` will automatically be included in the `smtpapi` header and passed to SendGrid.
+require 'sendgrid-ruby'
+include SendGrid
+
+data = JSON.parse('{
+  "personalizations": [
+    {
+      "to": [
+        {
+          "email": "test@example.com"
+        }
+      ],
+      "subject": "Sending with Twilio SendGrid is Fun"
+    }
+  ],
+  "from": {
+    "email": "test@example.com"
+  },
+  "content": [
+    {
+      "type": "text/plain",
+      "value": "and easy to do anywhere, even with Ruby"
+    }
+  ]
+}')
+sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
+response = sg.client.mail._("send").post(request_body: data)
+puts response.status_code
+puts response.body
+puts response.parsed_body
+puts response.headers
+```
+
+## General v3 Web API Usage (With Fluent Interface)
 
 ```ruby
-template = SendGrid::Template.new('MY_TEMPLATE_ID')
-mail.template = template
+require 'sendgrid-ruby'
+sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
+response = sg.client.suppression.bounces.get()
+puts response.status_code
+puts response.body
+puts response.parsed_body
+puts response.headers
 ```
 
-## Working with Templates
-
-Another easy way to use the [SendGrid Templating](https://sendgrid.com/docs/API_Reference/Web_API_v3/Template_Engine/index.html) system is with the `Recipient`, `Mail`, `Template`, and `TemplateMailer` objects.
-
-Create some `Recipients`
+## General v3 Web API Usage (Without Fluent Interface)
 
 ```ruby
-users = User.where(email: ['first@gmail.com', 'second@gmail.com'])
-
-recipients = []
-
-users.each do |user|
-  recipient = SendGrid::Recipient.new(user.email)
-  recipient.add_substitution('first_name', user.first_name)
-  recipient.add_substitution('city', user.city)
-
-  recipients << recipient
-end
+require 'sendgrid-ruby'
+sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
+response = sg.client._("suppression/bounces").get()
+puts response.status_code
+puts response.body
+puts response.parsed_body
+puts response.headers
 ```
 
-Create a `Template`
+<a name="inbound"></a>
+# Processing Inbound Email
 
-```ruby
-template = SendGrid::Template.new('MY_TEMPLATE_ID')
-```
+Please see [our helper](https://github.com/sendgrid/sendgrid-ruby/tree/master/lib/sendgrid/helpers/inbound) for utilizing our Inbound Parse webhook.
 
-Create a `Client`
+<a name="usage"></a>
+# Usage
 
-```ruby
-client = SendGrid::Client.new(api_user: my_user, api_key: my_key)
-```
+- [Twilio SendGrid Docs](https://sendgrid.com/docs/API_Reference/index.html)
+- [Library Usage Docs](https://github.com/sendgrid/sendgrid-ruby/tree/master/USAGE.md)
+- [Example Code](https://github.com/sendgrid/sendgrid-ruby/tree/master/examples)
+- [How-to: Migration from v2 to v3](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html)
+- [v3 Web API Mail Send Helper](https://github.com/sendgrid/sendgrid-ruby/tree/master/lib/sendgrid/helpers/mail) - build a request object payload for a v3 /mail/send API call.
+- [Settings Helper](https://github.com/sendgrid/sendgrid-ruby/tree/master/lib/sendgrid/helpers/settings)
 
-Initialize mail defaults and create the `TemplateMailer`
+<a name="use_cases"></a>
+# Use Cases
 
-```ruby
-mail_defaults = {
-  from: 'admin@email.com',
-  html: '<h1>I like email</h1>',
-  text: 'I like email',
-  subject: 'Email is great',
-}
-
-mailer = SendGrid::TemplateMailer.new(client, template, recipients)
-```
+[Examples of common API use cases](https://github.com/sendgrid/sendgrid-ruby/blob/master/USE_CASES.md), such as how to send an email with a transactional template.
 
-Mail it!
+<a name="announcements"></a>
+# Announcements
 
-```ruby
-mailer.mail(mail_defaults)
-```
+Please see our announcement regarding [breaking changes](https://github.com/sendgrid/sendgrid-ruby/issues/94). Your support is appreciated!
 
-## Using SendGrid's X-SMTPAPI Header
+All updates to this library are documented in our [CHANGELOG](https://github.com/sendgrid/sendgrid-ruby/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-ruby/releases). You may also subscribe to email [release notifications](https://dx.sendgrid.com/newsletter/ruby) for releases and breaking changes.
 
-<blockquote>
-To utilize the X-SMTPAPI header, we have directly integrated the <a href="https://github.com/SendGridJP/smtpapi-ruby">SendGridJP/smtpapi-ruby</a> gem.
-For more information, view our <a href=https://sendgrid.com/docs/API_Reference/SMTP_API/index.html>SMTPAPI docs page</a>.
-</blockquote>
+<a name="roadmap"></a>
+# Roadmap
 
-```ruby
+If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/sendgrid/sendgrid-ruby/issues) and [pull requests](https://github.com/sendgrid/sendgrid-ruby/pulls). We would love to hear your feedback.
 
-header = Smtpapi::Header.new
-header.add_to(['john.doe@example.com', 'jane.doe@example.com'])
-header.add_substitution('keep', ['secret'])        # sub = {keep: ['secret']}
-header.add_substitution('other', ['one', 'two'])   # sub = {keep: ['secret'], other: ['one', 'two']}
-header.add_unique_arg("unique_code", "8675309")
-header.add_category("Newsletter")
-header.add_filter('templates', 'enable', 1)	   # necessary for each time the template engine is used
-header.add_filter('templates', 'template_id', '1234-5678-9100-abcd')
-header.set_ip_pool("marketing_ip_pool")
-mail.smtpapi = header
+<a name="contribute"></a>
+# How to Contribute
 
-```
-## Testing ##
+We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/sendgrid/sendgrid-ruby/tree/master/CONTRIBUTING.md) guide for details.
 
-`bundle exec rake test`
+- [Feature Request](https://github.com/sendgrid/sendgrid-ruby/tree/master/CONTRIBUTING.md#feature_request)
+- [Bug Reports](https://github.com/sendgrid/sendgrid-ruby/tree/master/CONTRIBUTING.md#submit_a_bug_report)
+- [Sign the CLA to Create a Pull Request](https://github.com/sendgrid/sendgrid-ruby/tree/master/CONTRIBUTING.md#cla)
+- [Improvements to the Codebase](https://github.com/sendgrid/sendgrid-ruby/tree/master/CONTRIBUTING.md#improvements_to_the_codebase)
+- [Review Pull Requests](https://github.com/sendgrid/sendgrid-ruby/blob/master/CONTRIBUTING.md#code-reviews)
 
-## Deploying ##
+<a name="troubleshooting"></a>
+# Troubleshooting
 
-1. Confirm tests pass `bundle exec rake test`
-2. Bump the version in `lib/sendgrid/version.rb` and `spec/lib/sendgrid_spec.rb`
-3. Update CHANGELOG.md
-4. Commit Version bump vX.X.X
-5. `rake release`
-6. Push changes to GitHub
-7. Release tag on GitHub vX.X.X
+Please see our [troubleshooting guide](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md) for common library issues.
 
-## Contributing ##
+<a name="about"></a>
+# About
 
-1. Fork it ( https://github.com/[my-github-username]/sendgrid-ruby/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+sendgrid-ruby is guided and supported by the [Developer Experience Team](mailto:dx@sendgrid.com).
 
-***Hit up [@rbin](http://twitter.com/rbin) or [@sendgrid](http://twitter.com/sendgrid) on Twitter with any issues.***
+sendgrid-ruby is maintained and funded by SendGrid, Inc. The names and logos for sendgrid-ruby are trademarks of SendGrid, Inc.
 
+<a name="license"></a>
+# License
+[The MIT License (MIT)](LICENSE.md)

data/Rakefile

@@ -1,8 +1,15 @@
+require 'rake/testtask'
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/sendgrid/test*.rb', 'test/sendgrid/helpers/mail/test*.rb', 'test/sendgrid/helpers/permissions/test*.rb']
+  t.verbose = true
+end
+
 RSpec::Core::RakeTask.new(:spec)
 
-task test: :spec
+desc "Run tests"
+task default: [:spec, :test]
 
-task default: :test