sendgrid-ruby 1.1.6 → 6.6.2

data/examples/user/user.rb

@@ -0,0 +1,290 @@
+require 'sendgrid-ruby'
+
+sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
+
+##################################################
+# Get a user's account information. #
+# GET /user/account #
+
+response = sg.client.user.account.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve your credit balance #
+# GET /user/credits #
+
+response = sg.client.user.credits.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update your account email address #
+# PUT /user/email #
+
+data = JSON.parse('{
+  "email": "example@example.com"
+}')
+response = sg.client.user.email.put(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve your account email address #
+# GET /user/email #
+
+response = sg.client.user.email.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update your password #
+# PUT /user/password #
+
+data = JSON.parse('{
+  "new_password": "new_password",
+  "old_password": "old_password"
+}')
+response = sg.client.user.password.put(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update a user's profile #
+# PATCH /user/profile #
+
+data = JSON.parse('{
+  "city": "Orange",
+  "first_name": "Example",
+  "last_name": "User"
+}')
+response = sg.client.user.profile.patch(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Get a user's profile #
+# GET /user/profile #
+
+response = sg.client.user.profile.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Cancel or pause a scheduled send #
+# POST /user/scheduled_sends #
+
+data = JSON.parse('{
+  "batch_id": "YOUR_BATCH_ID",
+  "status": "pause"
+}')
+response = sg.client.user.scheduled_sends.post(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve all scheduled sends #
+# GET /user/scheduled_sends #
+
+response = sg.client.user.scheduled_sends.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update user scheduled send information #
+# PATCH /user/scheduled_sends/{batch_id} #
+
+data = JSON.parse('{
+  "status": "pause"
+}')
+batch_id = 'test_url_param'
+response = sg.client.user.scheduled_sends._(batch_id).patch(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve scheduled send #
+# GET /user/scheduled_sends/{batch_id} #
+
+batch_id = 'test_url_param'
+response = sg.client.user.scheduled_sends._(batch_id).get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Delete a cancellation or pause of a scheduled send #
+# DELETE /user/scheduled_sends/{batch_id} #
+
+batch_id = 'test_url_param'
+response = sg.client.user.scheduled_sends._(batch_id).delete
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update Enforced TLS settings #
+# PATCH /user/settings/enforced_tls #
+
+data = JSON.parse('{
+  "require_tls": true,
+  "require_valid_cert": false
+}')
+response = sg.client.user.settings.enforced_tls.patch(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve current Enforced TLS settings. #
+# GET /user/settings/enforced_tls #
+
+response = sg.client.user.settings.enforced_tls.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update your username #
+# PUT /user/username #
+
+data = JSON.parse('{
+  "username": "test_username"
+}')
+response = sg.client.user.username.put(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve your username #
+# GET /user/username #
+
+response = sg.client.user.username.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update Event Notification Settings #
+# PATCH /user/webhooks/event/settings #
+
+data = JSON.parse('{
+  "bounce": true,
+  "click": true,
+  "deferred": true,
+  "delivered": true,
+  "dropped": true,
+  "enabled": true,
+  "group_resubscribe": true,
+  "group_unsubscribe": true,
+  "open": true,
+  "processed": true,
+  "spam_report": true,
+  "unsubscribe": true,
+  "url": "url"
+}')
+response = sg.client.user.webhooks.event.settings.patch(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve Event Webhook settings #
+# GET /user/webhooks/event/settings #
+
+response = sg.client.user.webhooks.event.settings.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Test Event Notification Settings  #
+# POST /user/webhooks/event/test #
+
+data = JSON.parse('{
+  "url": "url"
+}')
+response = sg.client.user.webhooks.event.test.post(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Create a parse setting #
+# POST /user/webhooks/parse/settings #
+
+data = JSON.parse('{
+  "hostname": "myhostname.com",
+  "send_raw": false,
+  "spam_check": true,
+  "url": "http://email.myhosthame.com"
+}')
+response = sg.client.user.webhooks.parse.settings.post(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve all parse settings #
+# GET /user/webhooks/parse/settings #
+
+response = sg.client.user.webhooks.parse.settings.get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Update a parse setting #
+# PATCH /user/webhooks/parse/settings/{hostname} #
+
+data = JSON.parse('{
+  "send_raw": true,
+  "spam_check": false,
+  "url": "http://newdomain.com/parse"
+}')
+hostname = 'test_url_param'
+response = sg.client.user.webhooks.parse.settings._(hostname).patch(request_body: data)
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieve a specific parse setting #
+# GET /user/webhooks/parse/settings/{hostname} #
+
+hostname = 'test_url_param'
+response = sg.client.user.webhooks.parse.settings._(hostname).get
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Delete a parse setting #
+# DELETE /user/webhooks/parse/settings/{hostname} #
+
+hostname = 'test_url_param'
+response = sg.client.user.webhooks.parse.settings._(hostname).delete
+puts response.status_code
+puts response.body
+puts response.headers
+
+##################################################
+# Retrieves Inbound Parse Webhook statistics. #
+# GET /user/webhooks/parse/stats #
+
+params = JSON.parse('{"aggregated_by": "day", "limit": "test_string", "start_date": "2016-01-01", "end_date": "2016-04-01", "offset": "test_string"}')
+response = sg.client.user.webhooks.parse.stats.get(query_params: params)
+puts response.status_code
+puts response.body
+puts response.headers

data/gemfiles/Sinatra_1.gemfile

@@ -0,0 +1,6 @@
+source 'http://rubygems.org'
+
+gemspec path: '..'
+
+gem 'ruby_http_client'
+gem 'sinatra', '~> 1.4'

data/gemfiles/Sinatra_2.gemfile

@@ -0,0 +1,6 @@
+source 'http://rubygems.org'
+
+gemspec path: '..'
+
+gem 'ruby_http_client'
+gem 'sinatra', '>= 2.0.0.rc2'

data/lib/rack/sendgrid_webhook_verification.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Rack
+  # Middleware that verifies webhooks from SendGrid using the EventWebhook
+  # verifier.
+  #
+  # The middleware takes a public key with which to set up the request
+  # validator and any number of paths. When a path matches the incoming request
+  # path, the request will be verified using the signature and timestamp of the
+  # request.
+  #
+  # Example:
+  #
+  # require 'rack'
+  # use Rack::SendGridWebhookVerification, ENV['PUBLIC_KEY'], /\/emails/
+  #
+  # The above appends this middleware to the stack, using a public key saved in
+  # the ENV and only against paths that match /\/emails/. If the request
+  # validates then it gets passed on to the action as normal. If the request
+  # doesn't validate then the middleware responds immediately with a 403 status.
+  class SendGridWebhookVerification
+    def initialize(app, public_key, *paths)
+      @app = app
+      @public_key = public_key
+      @path_regex = Regexp.union(paths)
+    end
+
+    def call(env)
+      return @app.call(env) unless env['PATH_INFO'].match(@path_regex)
+
+      request = Rack::Request.new(env)
+
+      event_webhook = SendGrid::EventWebhook.new
+      ec_public_key = event_webhook.convert_public_key_to_ecdsa(@public_key)
+      verified = event_webhook.verify_signature(
+        ec_public_key,
+        request.body.read,
+        request.env[SendGrid::EventWebhookHeader::SIGNATURE],
+        request.env[SendGrid::EventWebhookHeader::TIMESTAMP]
+      )
+
+      request.body.rewind
+
+      if verified
+        @app.call(env)
+      else
+        [
+          403,
+          { 'Content-Type' => 'text/plain' },
+          ['SendGrid Request Verification Failed.']
+        ]
+      end
+    end
+  end
+end

data/lib/sendgrid/base_interface.rb

@@ -0,0 +1,40 @@
+require 'ruby_http_client'
+require_relative 'version'
+
+# Initialize the HTTP client
+class BaseInterface
+  attr_accessor :client
+  attr_reader :request_headers, :host, :version, :impersonate_subuser, :http_options
+
+  # * *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
+  #   - +http_options+ -> http options that you want to be globally applied to each request
+  #
+  def initialize(auth:, host:, request_headers: nil, version: nil, impersonate_subuser: nil, http_options: {})
+    @auth = auth
+    @host = host
+    @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
+    @http_options = http_options
+    @client = SendGrid::Client.new(host: "#{@host}/#{@version}",
+                                   request_headers: @request_headers,
+                                   http_options: @http_options)
+  end
+end

data/lib/sendgrid/helpers/eventwebhook/eventwebhook.rb

@@ -0,0 +1,50 @@
+require 'base64'
+require 'digest'
+require 'openssl'
+
+module SendGrid
+  # This class allows you to use the Event Webhook feature. Read the docs for
+  # more details: https://sendgrid.com/docs/for-developers/tracking-events/event
+  class EventWebhook
+    # * *Args* :
+    #   - +public_key+ -> verification key under Mail Settings
+    #
+    def convert_public_key_to_ecdsa(public_key)
+      verify_engine
+      OpenSSL::PKey::EC.new(Base64.decode64(public_key))
+    end
+
+    # * *Args* :
+    #   - +public_key+ -> elliptic curve public key
+    #   - +payload+ -> event payload in the request body
+    #   - +signature+ -> signature value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header
+    #   - +timestamp+ -> timestamp value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header
+    def verify_signature(public_key, payload, signature, timestamp)
+      verify_engine
+      timestamped_playload = "#{timestamp}#{payload}"
+      payload_digest = Digest::SHA256.digest(timestamped_playload)
+      decoded_signature = Base64.decode64(signature)
+      public_key.dsa_verify_asn1(payload_digest, decoded_signature)
+    rescue StandardError
+      false
+    end
+
+    def verify_engine
+      # JRuby does not fully support ECDSA: https://github.com/jruby/jruby-openssl/issues/193
+      raise NotSupportedError, "Event Webhook verification is not supported by JRuby" if RUBY_PLATFORM == "java"
+    end
+
+    class Error < ::RuntimeError
+    end
+
+    class NotSupportedError < Error
+    end
+  end
+
+  # This class lists headers that get posted to the webhook. Read the docs for
+  # more details: https://sendgrid.com/docs/for-developers/tracking-events/event
+  class EventWebhookHeader
+    SIGNATURE = "HTTP_X_TWILIO_EMAIL_EVENT_WEBHOOK_SIGNATURE".freeze
+    TIMESTAMP = "HTTP_X_TWILIO_EMAIL_EVENT_WEBHOOK_TIMESTAMP".freeze
+  end
+end

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

@@ -0,0 +1,98 @@
+**This helper is a stand alone module to help get you started consuming and processing Inbound Parse data.**
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start for Local Testing with Sample Data](#quick-start-for-local-testing-with-sample-data)
+- [Quick Start for Local Testing with Real Data](#quick-start-for-local-testing-with-real-data)
+- [Code Walkthrough](#code-walkthrough)
+  - [app.rb](#apprb)
+  - [config.yml](#configyml)
+  - [send.rb & /sample_data](#sendrb--sampledata)
+- [Contributing](#contributing)
+
+<a name="quick_start_local_sample"></a>
+
+
+# Installation
+
+In addition to the installation instructions in
+[the main readme](../../../../README.md#installation),
+you must also add sinatra to your Gemfile:
+
+```
+gem 'sinatra', '>= 1.4.7', '< 3'
+```
+
+
+# Quick Start for Local Testing with Sample Data
+
+```bash
+git clone https://github.com/sendgrid/sendgrid-ruby.git
+cd sendgrid-ruby
+bundle install
+```
+
+Run the Inbound Parse listener in your terminal:
+
+```ruby
+rackup
+```
+
+In another terminal, run the test data sender:
+
+```bash
+cd [path to sendgrid-ruby]
+bundle install
+ruby ./lib/sendgrid/helpers/inbound/send.rb ./lib/sendgrid/helpers/inbound/sample_data/default_data.txt
+```
+
+More sample data can be found [here](sample_data).
+
+View the results in the first terminal.
+
+<a name="quick_start_local_real"></a>
+# Quick Start for Local Testing with Real Data
+
+[Setup your MX records.](https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html#-Setup) Depending on your domain name host, you may need to wait up to 48 hours for the settings to propagate.
+
+Run the Inbound Parse listener in your terminal:
+
+```bash
+git clone https://github.com/sendgrid/sendgrid-ruby.git
+cd sendgrid-ruby
+bundle install
+rackup
+```
+
+In another terminal, use [ngrok](https://ngrok.com/) to allow external access to your machine:
+```bash
+ngrok http 9292
+```
+
+Update your Twilio SendGrid Incoming Parse settings: [Settings Page](https://app.sendgrid.com/settings/parse) | [Docs](https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html#-Pointing-to-a-Hostname-and-URL)
+
+- For the HOSTNAME field, use the domain that you changed the MX records (e.g. inbound.yourdomain.com)
+- For the URL field, use the URL generated by ngrok + /inbound, e.g http://XXXXXXX.ngrok.io/inbound
+
+Next, send an email to [anything]@inbound.yourdomain.com, then look at the terminal where you started the Inbound Parse listener.
+
+<a name="code_walkthrough"></a>
+# Code Walkthrough
+
+## app.rb
+
+This module runs a [Sinatra](http://www.sinatrarb.com/) server, that by default (you can change those settings [here](config.yml)), listens for POSTs on http://localhost:9292. When the server receives the POST, it parses and prints the key/value data.
+
+## config.yml
+
+This module loads application environment variables (located in [config.yml](config.yml)).
+
+## send.rb & /sample_data
+
+This module is used to send sample test data. It is useful for testing and development, particularly while you wait for your MX records to propagate.
+
+<a name="contributing"></a>
+# Contributing
+
+If you would like to contribute to this project, please see our [contributing guide](../../../../CONTRIBUTING.md). Thanks!

data/lib/sendgrid/helpers/inbound/app.rb

@@ -0,0 +1,32 @@
+begin
+  require 'sinatra'
+rescue LoadError
+  puts <<-NOTE
+    As of sengrid verison 6, sinatra is no longer specified as a dependency of
+    the sendgrid gem. All the functionality of the inbound server is still the same
+    and fully supported, but you just need to include the sinatra dependency in your gemfile
+    yourself, like so:
+
+        gem 'sinatra', '>= 1.4.7', '< 3'
+  NOTE
+  raise
+end
+require 'logger'
+require 'json'
+require 'yaml'
+
+class Main < Sinatra::Base
+  configure :production, :development do
+    enable :logging
+    set :config, YAML.load_file("#{File.dirname(__FILE__)}/config.yml")
+  end
+
+  get '/' do
+    redirect to('index.html')
+  end
+
+  post settings.config['endpoint'] do
+    filtered = params.select { |k, _v| settings.config['keys'].include?(k) }
+    logger.info JSON.pretty_generate(filtered)
+  end
+end

data/lib/sendgrid/helpers/inbound/config.yml

@@ -0,0 +1,26 @@
+# Incoming Parse endpoint for receiver
+endpoint: '/inbound'
+
+# List all Incoming Parse fields you would like parsed
+# Reference: https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html
+keys:
+ - from
+ - attachments
+ - headers
+ - text
+ - envelope
+ - to
+ - html
+ - sender_ip
+ - attachment-info
+ - subject
+ - dkim
+ - SPF
+ - charsets
+ - content-ids
+ - spam_report
+ - spam_score
+ - email
+
+# URL that the sender will POST to
+host: 'http://127.0.0.1:9292/inbound'

data/lib/sendgrid/helpers/inbound/public/index.html

@@ -0,0 +1,10 @@
+<html>
+  <head>
+    <title>Twilio SendGrid Incoming Parse</title>
+  </head>
+  <body>
+    <h1>You have successfuly launched the server!</h1>
+
+       Check out <a href="https://github.com/sendgrid/sendgrid-ruby/tree/HEAD/sendgrid/helpers/inbound">the documentation</a> on how to use this software to utilize the SendGrid Inbound Parse webhook.
+  </body>
+</html>

data/lib/sendgrid/helpers/inbound/sample_data/default_data.txt

@@ -0,0 +1,58 @@
+--xYzZY
+Content-Disposition: form-data; name="headers"
+
+MIME-Version: 1.0
+Received: by 0.0.0.0 with HTTP; Wed, 10 Aug 2016 18:10:13 -0700 (PDT)
+From: Example User <test@example.com>
+Date: Wed, 10 Aug 2016 18:10:13 -0700
+Subject: Inbound Parse Test Data
+To: inbound@inbound.example.com
+Content-Type: multipart/alternative; boundary=001a113df448cad2d00539c16e89
+
+--xYzZY
+Content-Disposition: form-data; name="dkim"
+
+{@sendgrid.com : pass}
+--xYzZY
+Content-Disposition: form-data; name="to"
+
+inbound@inbound.example.com
+--xYzZY
+Content-Disposition: form-data; name="html"
+
+<html><body><strong>Hello Twilio SendGrid!</body></html>
+
+--xYzZY
+Content-Disposition: form-data; name="from"
+
+Example User <test@example.com>
+--xYzZY
+Content-Disposition: form-data; name="text"
+
+Hello Twilio SendGrid!
+
+--xYzZY
+Content-Disposition: form-data; name="sender_ip"
+
+0.0.0.0
+--xYzZY
+Content-Disposition: form-data; name="envelope"
+
+{"to":["inbound@inbound.example.com"],"from":"test@example.com"}
+--xYzZY
+Content-Disposition: form-data; name="attachments"
+
+0
+--xYzZY
+Content-Disposition: form-data; name="subject"
+
+Testing non-raw
+--xYzZY
+Content-Disposition: form-data; name="charsets"
+
+{"to":"UTF-8","html":"UTF-8","subject":"UTF-8","from":"UTF-8","text":"UTF-8"}
+--xYzZY
+Content-Disposition: form-data; name="SPF"
+
+pass
+--xYzZY--