sendgrid-ruby 6.1.4 → 6.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. checksums.yaml +4 -4
  2. data/.codeclimate.yml +1 -1
  3. data/.gitignore +2 -0
  4. data/.rubocop.yml +6 -0
  5. data/.travis.yml +11 -20
  6. data/CHANGELOG.md +45 -0
  7. data/CONTRIBUTING.md +4 -11
  8. data/Dockerfile +14 -0
  9. data/Gemfile +0 -1
  10. data/Makefile +9 -2
  11. data/README.md +0 -1
  12. data/examples/helpers/eventwebhook/example.rb +16 -0
  13. data/lib/rack/sendgrid_webhook_verification.rb +52 -0
  14. data/lib/sendgrid-ruby.rb +5 -1
  15. data/lib/sendgrid/base_interface.rb +36 -0
  16. data/lib/sendgrid/helpers/eventwebhook/eventwebhook.rb +52 -0
  17. data/lib/sendgrid/sendgrid.rb +20 -0
  18. data/lib/sendgrid/twilio_email.rb +21 -0
  19. data/lib/sendgrid/version.rb +1 -1
  20. data/sendgrid-ruby.gemspec +2 -0
  21. data/spec/fixtures/event_webhook.rb +16 -0
  22. data/spec/rack/sendgrid_webhook_verification_spec.rb +116 -0
  23. data/spec/sendgrid/helpers/eventwebhook/eventwebhook_spec.rb +103 -0
  24. data/spec/sendgrid/sendgrid_spec.rb +11 -0
  25. data/spec/sendgrid/twilio_email_spec.rb +11 -0
  26. data/spec/spec_helper.rb +2 -0
  27. data/test/sendgrid/helpers/mail/test_mail.rb +1 -1
  28. data/test/sendgrid/test_sendgrid-ruby.rb +24 -59
  29. data/use-cases/README.md +16 -0
  30. data/use-cases/domain-authentication.md +5 -0
  31. data/use-cases/email-statistics.md +52 -0
  32. data/use-cases/legacy-templates.md +98 -0
  33. data/use-cases/sms.md +39 -0
  34. data/use-cases/transactional-templates.md +111 -0
  35. data/use-cases/twilio-email.md +13 -0
  36. data/use-cases/twilio-setup.md +54 -0
  37. metadata +57 -9
  38. data/USE_CASES.md +0 -377
  39. data/docker/Dockerfile +0 -12
  40. data/docker/README.md +0 -30
  41. data/lib/sendgrid/client.rb +0 -38
  42. data/test/prism.sh +0 -42
@@ -1,377 +0,0 @@
1
- This documentation provides examples for specific use cases. Please [open an issue](https://github.com/sendgrid/sendgrid-ruby/issues) or make a pull request for any use cases you would like us to document here. Thank you!
2
-
3
- # Table of Contents
4
-
5
- * [Transactional Templates](#transactional-templates)
6
- * [With Mail Helper Class](#with-mail-helper-class)
7
- * [Without Mail Helper Class](#without-mail-helper-class)
8
- * [Legacy Templates](#legacy-templates)
9
- * [With Mail Helper Class](#with-mail-helper-class-1)
10
- * [Without Mail Helper Class](#without-mail-helper-class-1)
11
- * [Adding Attachments](#adding-attachments)
12
- * [How to Setup a Domain Authentication](#how-to-setup-a-domain-authentication)
13
- * [How to View Email Statistics](#how-to-view-email-statistics)
14
- * [Send a SMS Message](#send-a-sms-message)
15
- * [1. Obtain a Free Twilio Account](#1-obtain-a-free-twilio-account)
16
- * [2. Update Your Environment Variables](#2-update-your-environment-variables)
17
- * [Mac](#mac)
18
- * [Windows](#windows)
19
- * [3. Install the Twilio Helper Library](#3-install-the-twilio-helper-library)
20
- * [4. Setup Work](#4-setup-work)
21
- * [5. Send an SMS](#5-send-an-sms)
22
-
23
- <a name="transactional-templates"></a>
24
- # Transactional Templates
25
-
26
- For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html) in the UI or via the API. Following is the template content we used for testing.
27
-
28
- Template ID (replace with your own):
29
-
30
- ```text
31
- d-2c214ac919e84170b21855cc129b4a5f
32
- ```
33
- Email Subject:
34
- ```text
35
- {{subject}}
36
- ```
37
-
38
- Template Body:
39
-
40
- ```html
41
- <html>
42
- <head>
43
- <title></title>
44
- </head>
45
- <body>
46
- Hello {{name}},
47
- <br/><br/>
48
- I'm glad you are trying out the template feature!
49
- <br/><br/>
50
- I hope you are having a great day in {{city}} :)
51
- <br/><br/>
52
- </body>
53
- </html>
54
- ```
55
-
56
- ## With Mail Helper Class
57
- ```ruby
58
- require 'sendgrid-ruby'
59
- include SendGrid
60
-
61
- mail = Mail.new
62
- mail.from = Email.new(email: 'test@example.com')
63
- personalization = Personalization.new
64
- personalization.add_to(Email.new(email: 'test@example.com'))
65
- personalization.add_dynamic_template_data({
66
- "subject" => "Testing Templates",
67
- "name" => "Example User",
68
- "city" => "Denver"
69
- })
70
- mail.add_personalization(personalization)
71
- mail.template_id = 'd-2c214ac919e84170b21855cc129b4a5f'
72
-
73
- sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
74
- begin
75
- response = sg.client.mail._("send").post(request_body: mail.to_json)
76
- rescue Exception => e
77
- puts e.message
78
- end
79
- puts response.status_code
80
- puts response.body
81
- puts response.parsed_body
82
- puts response.headers
83
- ```
84
-
85
- ## Without Mail Helper Class
86
-
87
- ```ruby
88
- require 'sendgrid-ruby'
89
- include SendGrid
90
-
91
- data = JSON.parse('{
92
- "personalizations": [
93
- {
94
- "to": [
95
- {
96
- "email": "test@example.com"
97
- }
98
- ],
99
- "dynamic_template_data": {
100
- "subject": "Testing Templates",
101
- "name": "Example User",
102
- "city": "Denver"
103
- }
104
- }
105
- ],
106
- "from": {
107
- "email": "test@example.com"
108
- },
109
- "template_id": "d-2c214ac919e84170b21855cc129b4a5f"
110
- }')
111
- sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
112
- begin
113
- response = sg.client.mail._("send").post(request_body: data)
114
- rescue Exception => e
115
- puts e.message
116
- end
117
- puts response.status_code
118
- puts response.body
119
- puts response.parsed_body
120
- puts response.headers
121
- ```
122
-
123
- <a name="legacy-templates"></a>
124
- # Legacy Templates
125
-
126
- For this example, we assume you have created a [legacy template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing.
127
-
128
- Template ID (replace with your own):
129
-
130
- ```text
131
- 13b8f94f-bcae-4ec6-b752-70d6cb59f932
132
- ```
133
-
134
- Email Subject:
135
-
136
- ```text
137
- <%subject%>
138
- ```
139
-
140
- Template Body:
141
-
142
- ```html
143
- <html>
144
- <head>
145
- <title></title>
146
- </head>
147
- <body>
148
- Hello -name-,
149
- <br /><br/>
150
- I'm glad you are trying out the template feature!
151
- <br /><br/>
152
- <%body%>
153
- <br /><br/>
154
- I hope you are having a great day in -city- :)
155
- <br /><br/>
156
- </body>
157
- </html>
158
- ```
159
-
160
- ## With Mail Helper Class
161
-
162
- ```ruby
163
- require 'sendgrid-ruby'
164
- include SendGrid
165
-
166
- mail = SendGrid::Mail.new
167
- mail.from = Email.new(email: 'test@example.com')
168
- mail.subject = 'I\'m replacing the subject tag'
169
- personalization = Personalization.new
170
- personalization.add_to(Email.new(email: 'test@example.com'))
171
- personalization.add_substitution(Substitution.new(key: '-name-', value: 'Example User'))
172
- personalization.add_substitution(Substitution.new(key: '-city-', value: 'Denver'))
173
- mail.add_personalization(personalization)
174
- mail.template_id = '13b8f94f-bcae-4ec6-b752-70d6cb59f932'
175
-
176
- sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
177
- begin
178
- response = sg.client.mail._("send").post(request_body: mail.to_json)
179
- rescue Exception => e
180
- puts e.message
181
- end
182
- puts response.status_code
183
- puts response.body
184
- puts response.parsed_body
185
- puts response.headers
186
- ```
187
-
188
- ## Without Mail Helper Class
189
-
190
- ```ruby
191
- require 'sendgrid-ruby'
192
- include SendGrid
193
-
194
- data = JSON.parse('{
195
- "personalizations": [
196
- {
197
- "to": [
198
- {
199
- "email": "test@example.com"
200
- }
201
- ],
202
- "substitutions": {
203
- "-name-": "Example User",
204
- "-city-": "Denver"
205
- },
206
- "subject": "I\'m replacing the subject tag"
207
- }
208
- ],
209
- "from": {
210
- "email": "test@example.com"
211
- },
212
- "template_id": "13b8f94f-bcae-4ec6-b752-70d6cb59f932"
213
- }')
214
- sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
215
- begin
216
- response = sg.client.mail._("send").post(request_body: data)
217
- rescue Exception => e
218
- puts e.message
219
- end
220
- puts response.status_code
221
- puts response.body
222
- puts response.parsed_body
223
- puts response.headers
224
- ```
225
-
226
- ## Adding Attachments
227
-
228
- ```ruby
229
- attachment = Attachment.new
230
- attachment.content = Base64.strict_encode64(File.open(fpath, 'rb').read)
231
- attachment.type = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
232
- attachment.filename = fname
233
- attachment.disposition = 'attachment'
234
- attachment.content_id = 'Reports Sheet'
235
- mail.add_attachment(attachment)
236
-
237
- ```
238
- Attachments must be base64 encoded, using Base64's strict_encode64 where no line feeds are added.
239
-
240
- <a name="domain-authentication"></a>
241
- # How to Setup a Domain Authentication
242
-
243
- You can find documentation for how to setup a domain authentication via the UI [here](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#sender-authentication).
244
-
245
- Find more information about all of SendGrid's authentication related documentation [here](https://sendgrid.com/docs/ui/account-and-settings/).
246
-
247
- <a name="email-statistics"></a>
248
- # How to View Email Statistics
249
-
250
- 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).
251
-
252
- 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 Twilio SendGrid processes your email.
253
-
254
- You can also use the email statistics helper to make it easier to interact with the API.
255
-
256
- ```ruby
257
- require 'sendgrid-ruby'
258
- require 'date'
259
-
260
- include SendGrid
261
-
262
- sg_client = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']).client
263
- stats = SendGrid::EmailStats.new(sendgrid_client: sg_client)
264
-
265
- # Fetch stats by day, between 2 dates
266
- from = Date.new(2017, 10, 01)
267
- to = Date.new(2017, 10, 12)
268
-
269
- email_stats = stats.by_day(from, to)
270
-
271
- email_stats.metrics
272
-
273
- if !email_stats.error?
274
- email_stats.metrics.each do |metric|
275
- puts "Date - #{metric.date}"
276
- puts "Number of Requests - #{metric.requests}"
277
- puts "Bounces - #{metric.bounces}"
278
- puts "Opens - #{metric.opens}"
279
- puts "Clicks - #{metric.clicks}"
280
- end
281
- end
282
-
283
- # Fetch stats by week, between 2 dates for a category
284
- from = Date.new(2017, 10, 01)
285
- to = Date.new(2017, 10, 12)
286
- category = 'abcd'
287
-
288
- email_stats = stats.by_week(from, to, category)
289
-
290
- if !email_stats.error?
291
- email_stats.metrics.each do |metric|
292
- puts "Date - #{metric.date}"
293
- puts "Number of Requests - #{metric.requests}"
294
- puts "Bounces - #{metric.bounces}"
295
- puts "Opens - #{metric.opens}"
296
- puts "Clicks - #{metric.clicks}"
297
- end
298
- end
299
-
300
- ```
301
-
302
- <a name="sms"></a>
303
- # Send a SMS Message
304
-
305
- Following are the steps to add Twilio SMS to your app:
306
-
307
- ## 1. Obtain a Free Twilio Account
308
-
309
- Sign up for a free Twilio account [here](https://www.twilio.com/try-twilio?source=sendgrid-ruby).
310
-
311
- ## 2. Update Your Environment Variables
312
-
313
- You can obtain your Account Sid and Auth Token from [twilio.com/console](https://twilio.com/console).
314
-
315
- ### Mac
316
-
317
- ```bash
318
- echo "export TWILIO_ACCOUNT_SID='YOUR_TWILIO_ACCOUNT_SID'" > twilio.env
319
- echo "export TWILIO_AUTH_TOKEN='YOUR_TWILIO_AUTH_TOKEN'" >> twilio.env
320
- echo "twilio.env" >> .gitignore
321
- source ./twilio.env
322
- ```
323
-
324
- ### Windows
325
-
326
- Temporarily set the environment variable (accessible only during the current CLI session):
327
-
328
- ```bash
329
- set TWILIO_ACCOUNT_SID=YOUR_TWILIO_ACCOUNT_SID
330
- set TWILIO_AUTH_TOKEN=YOUR_TWILIO_AUTH_TOKEN
331
- ```
332
-
333
- Permanently set the environment variable (accessible in all subsequent CLI sessions):
334
-
335
- ```bash
336
- setx TWILIO_ACCOUNT_SID "YOUR_TWILIO_ACCOUNT_SID"
337
- setx TWILIO_AUTH_TOKEN "YOUR_TWILIO_AUTH_TOKEN"
338
- ```
339
-
340
- ## 3. Install the Twilio Helper Library
341
-
342
- To install using [Bundler][bundler] grab the latest stable version:
343
-
344
- ```ruby
345
- gem 'twilio-ruby', '~> 5.23.1'
346
- ```
347
-
348
- To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install:
349
-
350
- ```bash
351
- gem install twilio-ruby -v 5.23.1
352
- ```
353
-
354
- ## 4. Setup Work
355
-
356
- ```ruby
357
- require 'twilio-ruby'
358
-
359
- # put your own credentials here
360
- account_sid = ENV['TWILIO_ACCOUNT_SID']
361
- auth_token = ENV['TWILIO_AUTH_TOKEN']
362
-
363
- # set up a client to talk to the Twilio REST API
364
- @client = Twilio::REST::Client.new account_sid, auth_token
365
- ```
366
-
367
- ## 5. Send an SMS
368
-
369
- ```ruby
370
- @client.api.account.messages.create(
371
- from: '+14159341234',
372
- to: '+16105557069',
373
- body: 'Hey there!'
374
- )
375
- ```
376
-
377
- For more information, please visit the [Twilio SMS Ruby documentation](https://www.twilio.com/docs/sms/quickstart/ruby).
@@ -1,12 +0,0 @@
1
- FROM ruby:2.5.1-jessie
2
-
3
- # Clone sendgrid-ruby
4
- WORKDIR /sources
5
- RUN git clone https://github.com/sendgrid/sendgrid-ruby.git
6
-
7
- # Bundle
8
- WORKDIR /sources/sendgrid-ruby
9
- RUN bundle install
10
-
11
- # Install prism
12
- RUN curl https://raw.githubusercontent.com/stoplightio/prism/master/install.sh | sh
@@ -1,30 +0,0 @@
1
- # Docker image for sendgrid-ruby
2
-
3
- ## Quickstart
4
- 1. [Install Docker](https://docs.docker.com/engine/installation/) on your machine.
5
- 2. Run `docker run --rm -it sendgrid/sendgrid-ruby irb`.
6
- 3. Run `require './lib/sendgrid-ruby.rb'`.
7
-
8
- ## Poke around
9
-
10
- If you would like to just poke around in the image and check some examples:
11
- ```sh
12
- docker run --rm -it sendgrid/sendgrid-ruby bash
13
- ```
14
-
15
- If you want to mount your fork or specific version of the gem:
16
- ```sh
17
- docker run --rm -v /path/to/local/sendgrid-ruby:/sources/sendgrid-ruby -it sendgrid/sendgrid-ruby bash
18
- ```
19
-
20
- ## Running tests
21
-
22
- If you would like to run the tests present in the image:
23
- ```sh
24
- docker run --rm sendgrid/sendgrid-ruby rake
25
- ```
26
-
27
- If you want to run tests on your fork or a specific version, mount the codebase onto the image:
28
- ```sh
29
- docker run --rm -v /path/to/local/sendgrid-ruby:/sources/sendgrid-ruby sendgrid/sendgrid-ruby rake
30
- ```
@@ -1,38 +0,0 @@
1
- # Quickly and easily access the Twilio SendGrid API.
2
- require 'ruby_http_client'
3
- require_relative 'version'
4
-
5
- module SendGrid
6
- # Initialize the HTTP client
7
- class API
8
- attr_accessor :client
9
- attr_reader :request_headers, :host, :version, :impersonate_subuser
10
- # * *Args* :
11
- # - +api_key+ -> your Twilio SendGrid API key
12
- # - +host+ -> the base URL for the API
13
- # - +request_headers+ -> any headers that you want to be globally applied
14
- # - +version+ -> the version of the API you wish to access,
15
- # currently only "v3" is supported
16
- #
17
- def initialize(api_key: '', host: nil, request_headers: nil, version: nil, impersonate_subuser: nil)
18
- @api_key = api_key
19
- @host = host ? host : 'https://api.sendgrid.com'
20
- @version = version ? version : 'v3'
21
- @impersonate_subuser = impersonate_subuser
22
- @user_agent = "sendgrid/#{SendGrid::VERSION};ruby"
23
- @request_headers = JSON.parse('
24
- {
25
- "Authorization": "Bearer ' + @api_key + '",
26
- "Accept": "application/json",
27
- "User-Agent": "' + @user_agent + '"
28
- }
29
- ')
30
- @request_headers['On-Behalf-Of'] = @impersonate_subuser if @impersonate_subuser
31
-
32
-
33
- @request_headers = @request_headers.merge(request_headers) if request_headers
34
- @client = Client.new(host: "#{@host}/#{@version}",
35
- request_headers: @request_headers)
36
- end
37
- end
38
- end