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
@@ -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
+ ```
@@ -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
+ ```
@@ -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).
@@ -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.
@@ -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.
@@ -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