sendgrid-ruby 6.1.4 → 6.3.3

Sign up to get free protection for your applications and to get access to all the features.
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
data/use-cases/email-statistics.md ADDED
@@ -0,0 +1,52 @@
1
+ # How to View Email Statistics
2
+
3
+ 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).
4
+
5
+ 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.
6
+
7
+ You can also use the email statistics helper to make it easier to interact with the API.
8
+
9
+ ```ruby
10
+ require 'sendgrid-ruby'
11
+ require 'date'
12
+
13
+ include SendGrid
14
+
15
+ sg_client = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']).client
16
+ stats = SendGrid::EmailStats.new(sendgrid_client: sg_client)
17
+
18
+ # Fetch stats by day, between 2 dates
19
+ from = Date.new(2017, 10, 01)
20
+ to = Date.new(2017, 10, 12)
21
+
22
+ email_stats = stats.by_day(from, to)
23
+
24
+ email_stats.metrics
25
+
26
+ if !email_stats.error?
27
+ email_stats.metrics.each do |metric|
28
+ puts "Date - #{metric.date}"
29
+ puts "Number of Requests - #{metric.requests}"
30
+ puts "Bounces - #{metric.bounces}"
31
+ puts "Opens - #{metric.opens}"
32
+ puts "Clicks - #{metric.clicks}"
33
+ end
34
+ end
35
+
36
+ # Fetch stats by week, between 2 dates for a category
37
+ from = Date.new(2017, 10, 01)
38
+ to = Date.new(2017, 10, 12)
39
+ category = 'abcd'
40
+
41
+ email_stats = stats.by_week(from, to, category)
42
+
43
+ if !email_stats.error?
44
+ email_stats.metrics.each do |metric|
45
+ puts "Date - #{metric.date}"
46
+ puts "Number of Requests - #{metric.requests}"
47
+ puts "Bounces - #{metric.bounces}"
48
+ puts "Opens - #{metric.opens}"
49
+ puts "Clicks - #{metric.clicks}"
50
+ end
51
+ end
52
+ ```
data/use-cases/legacy-templates.md ADDED
@@ -0,0 +1,98 @@
1
+ # Legacy Templates
2
+
3
+ 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.
4
+
5
+ Template ID (replace with your own):
6
+ ```text
7
+ 13b8f94f-bcae-4ec6-b752-70d6cb59f932
8
+ ```
9
+
10
+ Email Subject:
11
+ ```text
12
+ <%subject%>
13
+ ```
14
+
15
+ Template Body:
16
+ ```html
17
+ <html>
18
+ <head>
19
+ <title></title>
20
+ </head>
21
+ <body>
22
+ Hello -name-,
23
+ <br /><br/>
24
+ I'm glad you are trying out the template feature!
25
+ <br /><br/>
26
+ <%body%>
27
+ <br /><br/>
28
+ I hope you are having a great day in -city- :)
29
+ <br /><br/>
30
+ </body>
31
+ </html>
32
+ ```
33
+
34
+ ## With Mail Helper Class
35
+
36
+ ```ruby
37
+ require 'sendgrid-ruby'
38
+ include SendGrid
39
+
40
+ mail = SendGrid::Mail.new
41
+ mail.from = Email.new(email: 'test@example.com')
42
+ mail.subject = 'I\'m replacing the subject tag'
43
+ personalization = Personalization.new
44
+ personalization.add_to(Email.new(email: 'test@example.com'))
45
+ personalization.add_substitution(Substitution.new(key: '-name-', value: 'Example User'))
46
+ personalization.add_substitution(Substitution.new(key: '-city-', value: 'Denver'))
47
+ mail.add_personalization(personalization)
48
+ mail.template_id = '13b8f94f-bcae-4ec6-b752-70d6cb59f932'
49
+
50
+ sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
51
+ begin
52
+ response = sg.client.mail._("send").post(request_body: mail.to_json)
53
+ rescue Exception => e
54
+ puts e.message
55
+ end
56
+ puts response.status_code
57
+ puts response.body
58
+ puts response.parsed_body
59
+ puts response.headers
60
+ ```
61
+
62
+ ## Without Mail Helper Class
63
+
64
+ ```ruby
65
+ require 'sendgrid-ruby'
66
+ include SendGrid
67
+
68
+ data = JSON.parse('{
69
+ "personalizations": [
70
+ {
71
+ "to": [
72
+ {
73
+ "email": "test@example.com"
74
+ }
75
+ ],
76
+ "substitutions": {
77
+ "-name-": "Example User",
78
+ "-city-": "Denver"
79
+ },
80
+ "subject": "I\'m replacing the subject tag"
81
+ }
82
+ ],
83
+ "from": {
84
+ "email": "test@example.com"
85
+ },
86
+ "template_id": "13b8f94f-bcae-4ec6-b752-70d6cb59f932"
87
+ }')
88
+ sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
89
+ begin
90
+ response = sg.client.mail._("send").post(request_body: data)
91
+ rescue Exception => e
92
+ puts e.message
93
+ end
94
+ puts response.status_code
95
+ puts response.body
96
+ puts response.parsed_body
97
+ puts response.headers
98
+ ```
data/use-cases/sms.md ADDED
@@ -0,0 +1,39 @@
1
+ First, follow the [Twilio Setup](twilio-setup.md) guide for creating a Twilio account and setting up environment variables with the proper credentials.
2
+
3
+ Then, install the Twilio Helper Library. Add this line to your application's Gemfile:
4
+
5
+ ```bash
6
+ gem 'twilio-ruby'
7
+ ```
8
+
9
+ And then execute:
10
+
11
+ ```bash
12
+ bundle
13
+ ```
14
+
15
+ Or install it yourself using:
16
+
17
+ ```bash
18
+ gem install twilio-ruby
19
+ ```
20
+
21
+ Finally, send a message.
22
+
23
+ ```ruby
24
+ require 'twilio-ruby'
25
+
26
+ # put your own credentials here
27
+ account_sid = ENV['TWILIO_ACCOUNT_SID']
28
+ auth_token = ENV['TWILIO_AUTH_TOKEN']
29
+
30
+ # set up a client to talk to the Twilio REST API
31
+ @client = Twilio::REST::Client.new account_sid, auth_token
32
+ @client.api.account.messages.create(
33
+ from: '+14159341234',
34
+ to: '+16105557069',
35
+ body: 'Hey there!'
36
+ )
37
+ ```
38
+
39
+ For more information, please visit the [Twilio SMS Ruby documentation](https://www.twilio.com/docs/sms/quickstart/ruby).
data/use-cases/transactional-templates.md ADDED
@@ -0,0 +1,111 @@
1
+ # Transactional Templates
2
+
3
+ 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.
4
+
5
+ Template ID (replace with your own):
6
+ ```text
7
+ d-2c214ac919e84170b21855cc129b4a5f
8
+ ```
9
+
10
+ Email Subject:
11
+ ```text
12
+ {{subject}}
13
+ ```
14
+
15
+ Template Body:
16
+ ```html
17
+ <html>
18
+ <head>
19
+ <title></title>
20
+ </head>
21
+ <body>
22
+ Hello {{name}},
23
+ <br/><br/>
24
+ I'm glad you are trying out the template feature!
25
+ <br/><br/>
26
+ I hope you are having a great day in {{city}} :)
27
+ <br/><br/>
28
+ </body>
29
+ </html>
30
+ ```
31
+
32
+ ## With Mail Helper Class
33
+ ```ruby
34
+ require 'sendgrid-ruby'
35
+ include SendGrid
36
+
37
+ mail = Mail.new
38
+ mail.from = Email.new(email: 'test@example.com')
39
+ personalization = Personalization.new
40
+ personalization.add_to(Email.new(email: 'test@example.com'))
41
+ personalization.add_dynamic_template_data({
42
+ "subject" => "Testing Templates",
43
+ "name" => "Example User",
44
+ "city" => "Denver"
45
+ })
46
+ mail.add_personalization(personalization)
47
+ mail.template_id = 'd-2c214ac919e84170b21855cc129b4a5f'
48
+
49
+ sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
50
+ begin
51
+ response = sg.client.mail._("send").post(request_body: mail.to_json)
52
+ rescue Exception => e
53
+ puts e.message
54
+ end
55
+ puts response.status_code
56
+ puts response.body
57
+ puts response.parsed_body
58
+ puts response.headers
59
+ ```
60
+
61
+ ## Without Mail Helper Class
62
+
63
+ ```ruby
64
+ require 'sendgrid-ruby'
65
+ include SendGrid
66
+
67
+ data = JSON.parse('{
68
+ "personalizations": [
69
+ {
70
+ "to": [
71
+ {
72
+ "email": "test@example.com"
73
+ }
74
+ ],
75
+ "dynamic_template_data": {
76
+ "subject": "Testing Templates",
77
+ "name": "Example User",
78
+ "city": "Denver"
79
+ }
80
+ }
81
+ ],
82
+ "from": {
83
+ "email": "test@example.com"
84
+ },
85
+ "template_id": "d-2c214ac919e84170b21855cc129b4a5f"
86
+ }')
87
+ sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
88
+ begin
89
+ response = sg.client.mail._("send").post(request_body: data)
90
+ rescue Exception => e
91
+ puts e.message
92
+ end
93
+ puts response.status_code
94
+ puts response.body
95
+ puts response.parsed_body
96
+ puts response.headers
97
+ ```
98
+
99
+ ## Adding Attachments
100
+
101
+ ```ruby
102
+ attachment = Attachment.new
103
+ attachment.content = Base64.strict_encode64(File.open(fpath, 'rb').read)
104
+ attachment.type = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
105
+ attachment.filename = fname
106
+ attachment.disposition = 'attachment'
107
+ attachment.content_id = 'Reports Sheet'
108
+ mail.add_attachment(attachment)
109
+ ```
110
+
111
+ Attachments must be base64 encoded, using Base64's strict_encode64 where no line feeds are added.
data/use-cases/twilio-email.md ADDED
@@ -0,0 +1,13 @@
1
+ First, follow the [Twilio Setup](twilio-setup.md) guide for creating a Twilio account and setting up environment variables with the proper credentials.
2
+
3
+ Then, initialize the Twilio Email Client.
4
+
5
+ ```ruby
6
+ mail_client = TwilioEmail::API(username: ENV['TWILIO_API_KEY'], password: ENV['TWILIO_API_SECRET'])
7
+
8
+ # or
9
+
10
+ mail_client = TwilioEmail::API(username: ENV['TWILIO_ACCOUNT_SID'], password: ENV['TWILIO_AUTH_TOKEN'])
11
+ ```
12
+
13
+ This client has the same interface as the `SendGrid::API` client.
data/use-cases/twilio-setup.md ADDED
@@ -0,0 +1,54 @@
1
+ ## 1. Obtain a Free Twilio Account
2
+
3
+ Sign up for a free Twilio account [here](https://www.twilio.com/try-twilio?source=sendgrid-ruby).
4
+
5
+ ## 2. Set Up Your Environment Variables
6
+
7
+ 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).
8
+
9
+ Once you have those, follow the steps below based on your operating system.
10
+
11
+ ### Linux/Mac
12
+
13
+ ```bash
14
+ echo "export TWILIO_API_KEY='YOUR_TWILIO_API_KEY'" > twilio.env
15
+ echo "export TWILIO_API_SECRET='YOUR_TWILIO_API_SECRET'" >> twilio.env
16
+
17
+ # or
18
+
19
+ echo "export TWILIO_ACCOUNT_SID='YOUR_TWILIO_ACCOUNT_SID'" > twilio.env
20
+ echo "export TWILIO_AUTH_TOKEN='YOUR_TWILIO_AUTH_TOKEN'" >> twilio.env
21
+ ```
22
+
23
+ Then:
24
+
25
+ ```bash
26
+ echo "twilio.env" >> .gitignore
27
+ source ./twilio.env
28
+ ```
29
+
30
+ ### Windows
31
+
32
+ Temporarily set the environment variable (accessible only during the current CLI session):
33
+
34
+ ```bash
35
+ set TWILIO_API_KEY=YOUR_TWILIO_API_KEY
36
+ set TWILIO_API_SECRET=YOUR_TWILIO_API_SECRET
37
+
38
+ : or
39
+
40
+ set TWILIO_ACCOUNT_SID=YOUR_TWILIO_ACCOUNT_SID
41
+ set TWILIO_AUTH_TOKEN=YOUR_TWILIO_AUTH_TOKEN
42
+ ```
43
+
44
+ Or permanently set the environment variable (accessible in all subsequent CLI sessions):
45
+
46
+ ```bash
47
+ setx TWILIO_API_KEY "YOUR_TWILIO_API_KEY"
48
+ setx TWILIO_API_SECRET "YOUR_TWILIO_API_SECRET"
49
+
50
+ : or
51
+
52
+ setx TWILIO_ACCOUNT_SID "YOUR_TWILIO_ACCOUNT_SID"
53
+ setx TWILIO_AUTH_TOKEN "YOUR_TWILIO_AUTH_TOKEN"
54
+ ```
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: sendgrid-ruby
3
3
  version: !ruby/object:Gem::Version
4
- version: 6.1.4
4
+ version: 6.3.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Elmer Thomas
@@ -10,7 +10,7 @@ authors:
10
10
  autorequire:
11
11
  bindir: bin
12
12
  cert_chain: []
13
- date: 2020-04-15 00:00:00.000000000 Z
13
+ date: 2020-07-22 00:00:00.000000000 Z
14
14
  dependencies:
15
15
  - !ruby/object:Gem::Dependency
16
16
  name: ruby_http_client
@@ -130,6 +130,34 @@ dependencies:
130
130
  - - "~>"
131
131
  - !ruby/object:Gem::Version
132
132
  version: '5.9'
133
+ - !ruby/object:Gem::Dependency
134
+ name: rack
135
+ requirement: !ruby/object:Gem::Requirement
136
+ requirements:
137
+ - - ">="
138
+ - !ruby/object:Gem::Version
139
+ version: '0'
140
+ type: :development
141
+ prerelease: false
142
+ version_requirements: !ruby/object:Gem::Requirement
143
+ requirements:
144
+ - - ">="
145
+ - !ruby/object:Gem::Version
146
+ version: '0'
147
+ - !ruby/object:Gem::Dependency
148
+ name: simplecov
149
+ requirement: !ruby/object:Gem::Requirement
150
+ requirements:
151
+ - - ">="
152
+ - !ruby/object:Gem::Version
153
+ version: '0'
154
+ type: :development
155
+ prerelease: false
156
+ version_requirements: !ruby/object:Gem::Requirement
157
+ requirements:
158
+ - - ">="
159
+ - !ruby/object:Gem::Version
160
+ version: '0'
133
161
  description: Official Twilio SendGrid Gem to Interact with Twilio SendGrids API in
134
162
  native Ruby
135
163
  email: help@twilio.com
@@ -140,10 +168,12 @@ files:
140
168
  - ".codeclimate.yml"
141
169
  - ".env_sample"
142
170
  - ".gitignore"
171
+ - ".rubocop.yml"
143
172
  - ".travis.yml"
144
173
  - CHANGELOG.md
145
174
  - CODE_OF_CONDUCT.md
146
175
  - CONTRIBUTING.md
176
+ - Dockerfile
147
177
  - Gemfile
148
178
  - ISSUE_TEMPLATE.md
149
179
  - LICENSE.md
@@ -154,10 +184,7 @@ files:
154
184
  - TROUBLESHOOTING.md
155
185
  - UPGRADE.md
156
186
  - USAGE.md
157
- - USE_CASES.md
158
187
  - config.ru
159
- - docker/Dockerfile
160
- - docker/README.md
161
188
  - examples/accesssettings/accesssettings.rb
162
189
  - examples/alerts/alerts.rb
163
190
  - examples/apikeys/apikeys.rb
@@ -169,6 +196,7 @@ files:
169
196
  - examples/contactdb/contactdb.rb
170
197
  - examples/devices/devices.rb
171
198
  - examples/geo/geo.rb
199
+ - examples/helpers/eventwebhook/example.rb
172
200
  - examples/helpers/mail/example.rb
173
201
  - examples/helpers/settings/example.rb
174
202
  - examples/helpers/stats/example.rb
@@ -188,8 +216,10 @@ files:
188
216
  - examples/user/user.rb
189
217
  - gemfiles/Sinatra_1.gemfile
190
218
  - gemfiles/Sinatra_2.gemfile
219
+ - lib/rack/sendgrid_webhook_verification.rb
191
220
  - lib/sendgrid-ruby.rb
192
- - lib/sendgrid/client.rb
221
+ - lib/sendgrid/base_interface.rb
222
+ - lib/sendgrid/helpers/eventwebhook/eventwebhook.rb
193
223
  - lib/sendgrid/helpers/inbound/README.md
194
224
  - lib/sendgrid/helpers/inbound/app.rb
195
225
  - lib/sendgrid/helpers/inbound/config.yml
@@ -232,9 +262,14 @@ files:
232
262
  - lib/sendgrid/helpers/stats/email_stats.rb
233
263
  - lib/sendgrid/helpers/stats/metrics.rb
234
264
  - lib/sendgrid/helpers/stats/stats_response.rb
265
+ - lib/sendgrid/sendgrid.rb
266
+ - lib/sendgrid/twilio_email.rb
235
267
  - lib/sendgrid/version.rb
236
268
  - mail_helper_v3.md
237
269
  - sendgrid-ruby.gemspec
270
+ - spec/fixtures/event_webhook.rb
271
+ - spec/rack/sendgrid_webhook_verification_spec.rb
272
+ - spec/sendgrid/helpers/eventwebhook/eventwebhook_spec.rb
238
273
  - spec/sendgrid/helpers/ip_management/ip_management_spec.rb
239
274
  - spec/sendgrid/helpers/settings/mail_settings_dto_spec.rb
240
275
  - spec/sendgrid/helpers/settings/partner_settings_dto_spec.rb
@@ -244,8 +279,9 @@ files:
244
279
  - spec/sendgrid/helpers/stats/email_stats_spec.rb
245
280
  - spec/sendgrid/helpers/stats/metrics_spec.rb
246
281
  - spec/sendgrid/helpers/stats/stats_response_spec.rb
282
+ - spec/sendgrid/sendgrid_spec.rb
283
+ - spec/sendgrid/twilio_email_spec.rb
247
284
  - spec/spec_helper.rb
248
- - test/prism.sh
249
285
  - test/sendgrid/helpers/mail/test_attachment.rb
250
286
  - test/sendgrid/helpers/mail/test_category.rb
251
287
  - test/sendgrid/helpers/mail/test_email.rb
@@ -253,6 +289,14 @@ files:
253
289
  - test/sendgrid/helpers/mail/test_personalizations.rb
254
290
  - test/sendgrid/permissions/test_scopes.rb
255
291
  - test/sendgrid/test_sendgrid-ruby.rb
292
+ - use-cases/README.md
293
+ - use-cases/domain-authentication.md
294
+ - use-cases/email-statistics.md
295
+ - use-cases/legacy-templates.md
296
+ - use-cases/sms.md
297
+ - use-cases/transactional-templates.md
298
+ - use-cases/twilio-email.md
299
+ - use-cases/twilio-setup.md
256
300
  homepage: http://github.com/sendgrid/sendgrid-ruby
257
301
  licenses:
258
302
  - MIT
@@ -272,11 +316,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
272
316
  - !ruby/object:Gem::Version
273
317
  version: '0'
274
318
  requirements: []
275
- rubygems_version: 3.0.3
319
+ rubygems_version: 3.0.8
276
320
  signing_key:
277
321
  specification_version: 4
278
322
  summary: Official Twilio SendGrid Gem
279
323
  test_files:
324
+ - spec/fixtures/event_webhook.rb
325
+ - spec/rack/sendgrid_webhook_verification_spec.rb
326
+ - spec/sendgrid/helpers/eventwebhook/eventwebhook_spec.rb
280
327
  - spec/sendgrid/helpers/ip_management/ip_management_spec.rb
281
328
  - spec/sendgrid/helpers/settings/mail_settings_dto_spec.rb
282
329
  - spec/sendgrid/helpers/settings/partner_settings_dto_spec.rb
@@ -286,8 +333,9 @@ test_files:
286
333
  - spec/sendgrid/helpers/stats/email_stats_spec.rb
287
334
  - spec/sendgrid/helpers/stats/metrics_spec.rb
288
335
  - spec/sendgrid/helpers/stats/stats_response_spec.rb
336
+ - spec/sendgrid/sendgrid_spec.rb
337
+ - spec/sendgrid/twilio_email_spec.rb
289
338
  - spec/spec_helper.rb
290
- - test/prism.sh
291
339
  - test/sendgrid/helpers/mail/test_attachment.rb
292
340
  - test/sendgrid/helpers/mail/test_category.rb
293
341
  - test/sendgrid/helpers/mail/test_email.rb