sendgrid-ruby 5.3.0 → 6.0.0

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 (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
@@ -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).
@@ -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'))
@@ -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 #
@@ -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
@@ -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