sendgrid-ruby 5.3.0 → 6.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (47) hide show
  1. checksums.yaml +4 -4
  2. data/.github/PULL_REQUEST_TEMPLATE +3 -1
  3. data/CHANGELOG.md +25 -0
  4. data/CODE_OF_CONDUCT.md +11 -11
  5. data/CONTRIBUTING.md +17 -22
  6. data/LICENSE.txt +1 -1
  7. data/README.md +25 -12
  8. data/Rakefile +1 -1
  9. data/TROUBLESHOOTING.md +21 -15
  10. data/UPGRADE.md +5 -0
  11. data/USAGE.md +1103 -1101
  12. data/USE_CASES.md +248 -18
  13. data/examples/helpers/mail/example.rb +7 -7
  14. data/examples/ips/ips.rb +13 -0
  15. data/examples/mail/mail.rb +2 -2
  16. data/examples/scopes/scopes.rb +49 -3
  17. data/examples/{whitelabel/whitelabel.rb → senderauthentication/senderauthentication.rb} +27 -27
  18. data/examples/suppression/suppression.rb +10 -10
  19. data/lib/sendgrid-ruby.rb +2 -0
  20. data/lib/sendgrid/client.rb +12 -9
  21. data/lib/sendgrid/helpers/inbound/README.md +22 -5
  22. data/lib/sendgrid/helpers/inbound/app.rb +13 -1
  23. data/lib/sendgrid/helpers/inbound/public/index.html +1 -1
  24. data/lib/sendgrid/helpers/inbound/sample_data/default_data.txt +2 -2
  25. data/lib/sendgrid/helpers/inbound/sample_data/raw_data.txt +2 -2
  26. data/lib/sendgrid/helpers/inbound/sample_data/raw_data_with_attachments.txt +2 -2
  27. data/lib/sendgrid/helpers/inbound/send.rb +2 -2
  28. data/lib/sendgrid/helpers/ip_management/ip_management.rb +17 -0
  29. data/lib/sendgrid/helpers/mail/README.md +1 -1
  30. data/lib/sendgrid/helpers/mail/attachment.rb +24 -1
  31. data/lib/sendgrid/helpers/mail/category.rb +0 -8
  32. data/lib/sendgrid/helpers/mail/content.rb +3 -16
  33. data/lib/sendgrid/helpers/mail/email.rb +3 -16
  34. data/lib/sendgrid/helpers/mail/mail.rb +8 -40
  35. data/lib/sendgrid/helpers/permissions/scope.rb +28 -0
  36. data/lib/sendgrid/helpers/permissions/scopes.yml +309 -0
  37. data/lib/sendgrid/helpers/settings/README.md +1 -1
  38. data/lib/sendgrid/helpers/stats/stats_response.rb +1 -1
  39. data/lib/sendgrid/version.rb +1 -1
  40. data/mail_helper_v3.md +9 -9
  41. data/sendgrid-ruby.gemspec +3 -3
  42. data/spec/sendgrid/helpers/ip_management/ip_management_spec.rb +12 -0
  43. data/test/sendgrid/helpers/mail/test_attachment.rb +35 -0
  44. data/test/sendgrid/helpers/mail/test_mail.rb +29 -21
  45. data/test/sendgrid/permissions/test_scopes.rb +38 -0
  46. data/test/sendgrid/test_sendgrid-ruby.rb +15 -7
  47. metadata +17 -6
data/USE_CASES.md CHANGED
@@ -3,15 +3,127 @@ This documentation provides examples for specific use cases. Please [open an iss
3
3
  # Table of Contents
4
4
 
5
5
  * [Transactional Templates](#transactional-templates)
6
- * [How to Setup a Domain Whitelabel](#domain-whitelabel)
7
- * [How to View Email Statistics](#email-statistics)
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)
8
22
 
9
23
  <a name="transactional-templates"></a>
10
- # (LEGACY) Transactional Templates
24
+ # Transactional Templates
11
25
 
12
- IF YOU ARE USING OUR NEW TEMPLATES, PLEASE SEE [THIS ISSUE](https://github.com/sendgrid/sendgrid-ruby/issues/301).
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.
13
27
 
14
- For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing.
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.
15
127
 
16
128
  Template ID (replace with your own):
17
129
 
@@ -51,7 +163,7 @@ I hope you are having a great day in -city- :)
51
163
  require 'sendgrid-ruby'
52
164
  include SendGrid
53
165
 
54
- mail = Mail.new
166
+ mail = SendGrid::Mail.new
55
167
  mail.from = Email.new(email: 'test@example.com')
56
168
  mail.subject = 'I\'m replacing the subject tag'
57
169
  personalization = Personalization.new
@@ -59,7 +171,6 @@ personalization.add_to(Email.new(email: 'test@example.com'))
59
171
  personalization.add_substitution(Substitution.new(key: '-name-', value: 'Example User'))
60
172
  personalization.add_substitution(Substitution.new(key: '-city-', value: 'Denver'))
61
173
  mail.add_personalization(personalization)
62
- mail.add_content(Content.new(type: 'text/html', value: 'I\'m replacing the <strong>body tag</strong>'))
63
174
  mail.template_id = '13b8f94f-bcae-4ec6-b752-70d6cb59f932'
64
175
 
65
176
  sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
@@ -98,12 +209,6 @@ data = JSON.parse('{
98
209
  "from": {
99
210
  "email": "test@example.com"
100
211
  },
101
- "content": [
102
- {
103
- "type": "text/html",
104
- "value": "I\'m replacing the <strong>body tag</strong>"
105
- }
106
- ],
107
212
  "template_id": "13b8f94f-bcae-4ec6-b752-70d6cb59f932"
108
213
  }')
109
214
  sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
@@ -132,16 +237,141 @@ mail.add_attachment(attachment)
132
237
  ```
133
238
  Attachments must be base64 encoded, using Base64's strict_encode64 where no line feeds are added.
134
239
 
135
- <a name="domain-whitelabel"></a>
136
- # How to Setup a Domain Whitelabel
240
+ <a name="domain-authentication"></a>
241
+ # How to Setup a Domain Authentication
137
242
 
138
- You can find documentation for how to setup a domain whitelabel via the UI [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/setup_domain_whitelabel.html) and via API [here](https://github.com/sendgrid/sendgrid-ruby/blob/master/USAGE.md#whitelabel).
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).
139
244
 
140
- Find more information about all of SendGrid's whitelabeling related documentation [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/index.html).
245
+ Find more information about all of SendGrid's authentication related documentation [here](https://sendgrid.com/docs/ui/account-and-settings/).
141
246
 
142
247
  <a name="email-statistics"></a>
143
248
  # How to View Email Statistics
144
249
 
145
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).
146
251
 
147
- 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 SendGrid processes your email.
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).
data/examples/helpers/mail/example.rb CHANGED
@@ -4,10 +4,10 @@ require 'json'
4
4
 
5
5
  def hello_world
6
6
  from = Email.new(email: 'test@example.com')
7
- subject = 'Hello World from the SendGrid Ruby Library'
7
+ subject = 'Hello World from the Twilio SendGrid Ruby Library'
8
8
  to = Email.new(email: 'test@example.com')
9
9
  content = Content.new(type: 'text/plain', value: 'some text here')
10
- mail = Mail.new(from, subject, to, content)
10
+ mail = SendGrid::Mail.new(from, subject, to, content)
11
11
  # puts JSON.pretty_generate(mail.to_json)
12
12
  puts mail.to_json
13
13
 
@@ -19,9 +19,9 @@ def hello_world
19
19
  end
20
20
 
21
21
  def kitchen_sink
22
- mail = Mail.new
22
+ mail = SendGrid::Mail.new
23
23
  mail.from = Email.new(email: 'test@example.com')
24
- mail.subject = 'Hello World from the SendGrid Ruby Library'
24
+ mail.subject = 'Hello World from the Twilio SendGrid Ruby Library'
25
25
  personalization = Personalization.new
26
26
  personalization.add_to(Email.new(email: 'test1@example.com', name: 'Example User'))
27
27
  personalization.add_to(Email.new(email: 'test2@example.com', name: 'Example User'))
@@ -29,7 +29,7 @@ def kitchen_sink
29
29
  personalization.add_cc(Email.new(email: 'test4@example.com', name: 'Example User'))
30
30
  personalization.add_bcc(Email.new(email: 'test5@example.com', name: 'Example User'))
31
31
  personalization.add_bcc(Email.new(email: 'test6@example.com', name: 'Example User'))
32
- personalization.subject = 'Hello World from the Personalized SendGrid Ruby Library'
32
+ personalization.subject = 'Hello World from the Personalized Twilio SendGrid Ruby Library'
33
33
  personalization.add_header(Header.new(key: 'X-Test', value: 'True'))
34
34
  personalization.add_header(Header.new(key: 'X-Mock', value: 'False'))
35
35
  personalization.add_substitution(Substitution.new(key: '%name%', value: 'Example User'))
@@ -46,7 +46,7 @@ def kitchen_sink
46
46
  personalization2.add_cc(Email.new(email: 'test4@example.com', name: 'Example User'))
47
47
  personalization2.add_bcc(Email.new(email: 'test5@example.com', name: 'Example User'))
48
48
  personalization2.add_bcc(Email.new(email: 'test6@example.com', name: 'Example User'))
49
- personalization2.subject = 'Hello World from the Personalized SendGrid Ruby Library'
49
+ personalization2.subject = 'Hello World from the Personalized Twilio SendGrid Ruby Library'
50
50
  personalization2.add_header(Header.new(key: 'X-Test', value: 'True'))
51
51
  personalization2.add_header(Header.new(key: 'X-Mock', value: 'False'))
52
52
  personalization2.add_substitution(Substitution.new(key: '%name%', value: 'Example User'))
@@ -129,7 +129,7 @@ def dynamic_template_data_hello_world
129
129
  mail = Mail.new
130
130
  mail.template_id = '' # a non-legacy template id
131
131
  mail.from = Email.new(email: 'test@example.com')
132
- subject = 'Dynamic Template Data Hello World from the SendGrid Ruby Library'
132
+ subject = 'Dynamic Template Data Hello World from the Twilio SendGrid Ruby Library'
133
133
  mail.subject = subject
134
134
  personalization = Personalization.new
135
135
  personalization.add_to(Email.new(email: 'test1@example.com', name: 'Example User'))
data/examples/ips/ips.rb CHANGED
@@ -23,6 +23,19 @@ puts response.status_code
23
23
  puts response.body
24
24
  puts response.headers
25
25
 
26
+ ##################################################
27
+ # Retrieve unassigned IPs #
28
+ # GET /ips #
29
+
30
+ params = {}
31
+ response = sg.client.ips.get(query_params: params)
32
+ all_ips = JSON.parse(response.body)
33
+ unassigned_ips = all_ips.select {|ip| ip.subusers.empty?}
34
+ puts response.status_code
35
+ puts response.body
36
+ puts unassigned_ips
37
+ puts response.headers
38
+
26
39
  ##################################################
27
40
  # Create an IP pool. #
28
41
  # POST /ips/pools #
data/examples/mail/mail.rb CHANGED
@@ -79,8 +79,8 @@ data = JSON.parse('{
79
79
  },
80
80
  "footer": {
81
81
  "enable": true,
82
- "html": "<p>Thanks</br>The SendGrid Team</p>",
83
- "text": "Thanks,/n The SendGrid Team"
82
+ "html": "<p>Thanks</br>The Twilio SendGrid Team</p>",
83
+ "text": "Thanks,/n The Twilio SendGrid Team"
84
84
  },
85
85
  "sandbox_mode": {
86
86
  "enable": false
data/examples/scopes/scopes.rb CHANGED
@@ -1,9 +1,7 @@
1
- require 'sendgrid-ruby'
2
-
1
+ require_relative '../../lib/sendgrid-ruby.rb'
3
2
 
4
3
  sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
5
4
 
6
-
7
5
  ##################################################
8
6
  # Retrieve a list of scopes for which this user has access. #
9
7
  # GET /scopes #
@@ -13,3 +11,51 @@ puts response.status_code
13
11
  puts response.body
14
12
  puts response.headers
15
13
 
14
+ ##################################################
15
+ # Update the name & scopes of an API Key #
16
+ # PUT /api_keys/{api_key_id} #
17
+
18
+
19
+ scopes = [
20
+ "user.profile.read",
21
+ "user.profile.update"
22
+ ]
23
+
24
+ data = {
25
+ "name": "A New Hope",
26
+ "scopes": scopes
27
+ }
28
+ api_key_id = "test_url_param"
29
+ response = sg.client.api_keys._(api_key_id).put(request_body: data)
30
+ puts response.status_code
31
+ puts response.body
32
+ puts response.headers
33
+
34
+ # The above method shows how to update the scopes
35
+ # To get various scopes that each of the endpoint has, use the following
36
+
37
+ # To get all admin permissions
38
+ scopes = SendGrid::Scope.admin_permissions
39
+
40
+ # To get all read only permissions
41
+ scopes = SendGrid::Scope.read_only_permissions
42
+
43
+ # There are two methods for each endpoints, namely
44
+ # {endpoint}_read_only_permissions and {endpoint}_full_access_permissions
45
+
46
+ # These are the endpoints :
47
+ # alerts, api_keys, asm_groups, billing, categories, credentials, stats, ips, mail_settings, mail,
48
+ # marketing_campaigns, partner_settings, scheduled_sends, subusers, suppression, teammates,
49
+ # templates, tracking_settings, user_settings, webhooks, whitelabel, access_settings
50
+
51
+ # read only permissions for alerts
52
+ scopes = SendGrid::Scope.alerts_read_only_permissions
53
+
54
+ # full access permissions for alerts
55
+ scopes = SendGrid::Scope.alerts_full_access_permissions
56
+
57
+ # read only permissions for billing
58
+ scopes = SendGrid::Scope.billing_read_only_permissions
59
+
60
+ # full access permissions for billing
61
+ scopes = SendGrid::Scope.billing_full_access_permissions