sendgrid_ruby 0.0.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +22 -0
- data/.travis.yml +10 -0
- data/Gemfile +4 -0
- data/LICENSE.txt +22 -0
- data/README.md +347 -0
- data/Rakefile +11 -0
- data/lib/sendgrid_ruby/email.rb +319 -0
- data/lib/sendgrid_ruby/version.rb +3 -0
- data/lib/sendgrid_ruby.rb +31 -0
- data/sendgrid_ruby.gemspec +25 -0
- data/test/file1.txt +1 -0
- data/test/file2.txt +1 -0
- data/test/file3.txt +1 -0
- data/test/gif +0 -0
- data/test/gif.gif +0 -0
- data/test/sendgrid_ruby/email.rb +506 -0
- data/test/sendgrid_ruby.rb +130 -0
- metadata +124 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: de1314e5105ecfc087659fd6ceedc9c61ec51545
|
4
|
+
data.tar.gz: eedb261cf51d403b09dfbdfc5edd64fba1a878d3
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 67a3bc99c2bffbc1df7ea30f78983ac6c79266b57f3b3ecd9d68073b412fdf3985ea69b0b3ffad6682313ee07de68cc97a59bba324439de6e881a8ae912a9f6c
|
7
|
+
data.tar.gz: bb1c2b20b7ca2484704bc2b042a1cc3461be145419c48d37a3749d262a23205ebf1880f520e21c3d43bacefed6c1084939d068506d45a344b8909fa81ae8e0dd
|
data/.gitignore
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
*.gem
|
2
|
+
*.rbc
|
3
|
+
.bundle
|
4
|
+
.config
|
5
|
+
.yardoc
|
6
|
+
Gemfile.lock
|
7
|
+
InstalledFiles
|
8
|
+
_yardoc
|
9
|
+
coverage
|
10
|
+
doc/
|
11
|
+
lib/bundler/man
|
12
|
+
pkg
|
13
|
+
rdoc
|
14
|
+
spec/reports
|
15
|
+
test/tmp
|
16
|
+
test/version_tmp
|
17
|
+
tmp
|
18
|
+
*.bundle
|
19
|
+
*.so
|
20
|
+
*.o
|
21
|
+
*.a
|
22
|
+
mkmf.log
|
data/.travis.yml
ADDED
data/Gemfile
ADDED
data/LICENSE.txt
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
MIT License
|
2
|
+
|
3
|
+
Copyright (c) 2014 SendGrid JP
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
6
|
+
a copy of this software and associated documentation files (the
|
7
|
+
"Software"), to deal in the Software without restriction, including
|
8
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
9
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
10
|
+
permit persons to whom the Software is furnished to do so, subject to
|
11
|
+
the following conditions:
|
12
|
+
|
13
|
+
The above copyright notice and this permission notice shall be
|
14
|
+
included in all copies or substantial portions of the Software.
|
15
|
+
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
19
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
20
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
21
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
22
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,347 @@
|
|
1
|
+
# sendgrid_ruby
|
2
|
+
|
3
|
+
This gem allows you to quickly and easily send emails through SendGrid using Ruby.
|
4
|
+
|
5
|
+
[![Build Status](https://travis-ci.org/SendGridJP/sendgrid-ruby.svg?branch=master)](https://travis-ci.org/SendGridJP/sendgrid-ruby)
|
6
|
+
|
7
|
+
```Ruby
|
8
|
+
email = SendgridRuby::Email.new
|
9
|
+
email.add_to('foo@bar.com')
|
10
|
+
.add_to('dude@bar.com')
|
11
|
+
.set_from(me@bar.com)
|
12
|
+
.set_subject("Subject goes here")
|
13
|
+
.set_text("Hello World!")
|
14
|
+
.set_html("<strong>Hello World!</strong><br />")
|
15
|
+
|
16
|
+
sendgrid = SendgridRuby::Sendgrid.new('username', 'password')
|
17
|
+
sendgrid.send(email)
|
18
|
+
```
|
19
|
+
|
20
|
+
## Installation
|
21
|
+
|
22
|
+
Add this line to your application's Gemfile:
|
23
|
+
|
24
|
+
gem 'sendgrid_ruby'
|
25
|
+
|
26
|
+
And then execute:
|
27
|
+
|
28
|
+
$ bundle
|
29
|
+
|
30
|
+
Or install it yourself as:
|
31
|
+
|
32
|
+
$ gem install sendgrid_ruby
|
33
|
+
|
34
|
+
## Example App
|
35
|
+
|
36
|
+
There is a [sendgridjp-ruby-example app](https://github.com/sendgridjp/sendgridjp-ruby-example) to help jumpstart your development.
|
37
|
+
|
38
|
+
## Usage
|
39
|
+
|
40
|
+
To begin using this gem, initialize the SendGrid object with your SendGrid credentials.
|
41
|
+
|
42
|
+
```Ruby
|
43
|
+
sendgrid = SendgridRuby::Sendgrid.new('username', 'password')
|
44
|
+
```
|
45
|
+
|
46
|
+
Create a new SendGrid Email object and add your message details.
|
47
|
+
|
48
|
+
```Ruby
|
49
|
+
mail = SendgirdRuby::Email.new
|
50
|
+
mail.add_to('foo@bar.com')
|
51
|
+
.setFrom('me@bar.com')
|
52
|
+
.setSubject('Subject goes here')
|
53
|
+
.setText('Hello World!')
|
54
|
+
.setHtml('<strong>Hello World!</strong>')
|
55
|
+
```
|
56
|
+
|
57
|
+
Send it.
|
58
|
+
|
59
|
+
```Ruby
|
60
|
+
response = sendgrid.send(mail)
|
61
|
+
```
|
62
|
+
|
63
|
+
### add_to
|
64
|
+
|
65
|
+
You can add one or multiple TO addresses using `add_to`.
|
66
|
+
|
67
|
+
```Ruby
|
68
|
+
mail = SendgridRuby::Email.new
|
69
|
+
mail.add_to('foo@bar.com')
|
70
|
+
.add_to('another@another.com')
|
71
|
+
sendgrid.send(mail)
|
72
|
+
```
|
73
|
+
|
74
|
+
### set_tos
|
75
|
+
|
76
|
+
If you prefer, you can add multiple TO addresses as an array using the `set_tos` method. This will unset any previous `add_to`s you appended.
|
77
|
+
|
78
|
+
```Ruby
|
79
|
+
mail = SendgridRuby::Email.new
|
80
|
+
emails = ["foo@bar.com", "another@another.com", "other@other.com"]
|
81
|
+
mail.set_tos(emails)
|
82
|
+
sendgrid.send(mail)
|
83
|
+
```
|
84
|
+
|
85
|
+
### get_tos
|
86
|
+
|
87
|
+
Sometimes you might find yourself wanting to list the currently set Tos. You can do that with `get_tos`.
|
88
|
+
|
89
|
+
```Ruby
|
90
|
+
mail = SendgridRuby::Email.new
|
91
|
+
mail.add_to('foo@bar.com')
|
92
|
+
mail.get_tos
|
93
|
+
```
|
94
|
+
|
95
|
+
### remove_to
|
96
|
+
|
97
|
+
You might also find yourself wanting to remove a single TO from your set list of TOs. You can do that with `remove_to`. You can pass a string or regex to the remove_to method.
|
98
|
+
|
99
|
+
```Ruby
|
100
|
+
mail = SendgridRuby::Email.new
|
101
|
+
mail.add_to('foo@bar.com')
|
102
|
+
mail.remove_to('foo@bar.com')
|
103
|
+
```
|
104
|
+
|
105
|
+
### set_from
|
106
|
+
|
107
|
+
```Ruby
|
108
|
+
mail = SendgridRuby::Email.new
|
109
|
+
mail.set_from('foo@bar.com')
|
110
|
+
sendgrid.send(mail)
|
111
|
+
```
|
112
|
+
|
113
|
+
### set_from_name
|
114
|
+
|
115
|
+
```Ruby
|
116
|
+
mail = SendgridRuby::Email.new
|
117
|
+
mail.set_from('foo@bar.com')
|
118
|
+
mail.set_from_name('Foo Bar')
|
119
|
+
mail.set_from('other@example.com')
|
120
|
+
mail.set_from_name('Other Guy')
|
121
|
+
sendgrid.send($mail)
|
122
|
+
```
|
123
|
+
|
124
|
+
### set_reply_to
|
125
|
+
|
126
|
+
```Ruby
|
127
|
+
mail = SendgridRuby::Email.new
|
128
|
+
mail.set_reply_to('foo@bar.com')
|
129
|
+
sendgrid.send(mail)
|
130
|
+
```
|
131
|
+
|
132
|
+
### Bcc
|
133
|
+
|
134
|
+
Use multiple `add_to`s as a superior alternative to `set_bcc`.
|
135
|
+
|
136
|
+
```Ruby
|
137
|
+
mail = SendgridRuby::Email.new
|
138
|
+
mail.add_to('foo@bar.com')
|
139
|
+
.add_to('someotheraddress@bar.com')
|
140
|
+
.add_to('another@another.com')
|
141
|
+
...
|
142
|
+
```
|
143
|
+
|
144
|
+
### set_subject
|
145
|
+
|
146
|
+
```Ruby
|
147
|
+
mail = SendgridRuby::Email.new
|
148
|
+
mail.set_subject('This is a subject')
|
149
|
+
sendgrid.send(mail)
|
150
|
+
```
|
151
|
+
|
152
|
+
### set_text
|
153
|
+
|
154
|
+
```Ruby
|
155
|
+
mail = SendgridRuby::Email.new
|
156
|
+
mail.set_text('This is some text')
|
157
|
+
sendgrid.send(mail)
|
158
|
+
```
|
159
|
+
|
160
|
+
### set_html
|
161
|
+
|
162
|
+
```Ruby
|
163
|
+
mail = SendgridRuby::Email.new
|
164
|
+
mail.set_html('<h1>This is an html email</h1>')
|
165
|
+
sendgrid.send(mail)
|
166
|
+
```
|
167
|
+
|
168
|
+
### Categories ###
|
169
|
+
|
170
|
+
Categories are used to group email statistics provided by SendGrid.
|
171
|
+
|
172
|
+
To use a category, simply set the category name. Note: there is a maximum of 10 categories per email.
|
173
|
+
|
174
|
+
```Ruby
|
175
|
+
mail = SendgridRuby::Email.new
|
176
|
+
mail.add_to('foo@bar.com')
|
177
|
+
...
|
178
|
+
.add_category("Category 1")
|
179
|
+
.add_category("Category 2")
|
180
|
+
```
|
181
|
+
|
182
|
+
### Attachments ###
|
183
|
+
|
184
|
+
Attachments are currently file based only.
|
185
|
+
|
186
|
+
File attachments are limited to 7 MB per file.
|
187
|
+
|
188
|
+
```Ruby
|
189
|
+
mail = SendgridRuby::Email.new
|
190
|
+
mail.add_to('foo@bar.com')
|
191
|
+
...
|
192
|
+
.add_attachment("../path/to/file.txt")
|
193
|
+
```
|
194
|
+
|
195
|
+
If you use the multiple add_to, each user will receive a personalized email showing **only* their email. This is more friendly and more personal.
|
196
|
+
|
197
|
+
So just remember, when thinking 'bcc', instead use multiple `addTo`s.
|
198
|
+
|
199
|
+
### From-Name and Reply-To
|
200
|
+
|
201
|
+
There are two handy helper methods for setting the From-Name and Reply-To for a
|
202
|
+
message
|
203
|
+
|
204
|
+
```Ruby
|
205
|
+
mail = SendgridRuby::Email.new
|
206
|
+
mail.add_to('foo@bar.com')
|
207
|
+
.set_reply_to('someone.else@example.com')
|
208
|
+
.set_from_name('John Doe')
|
209
|
+
...
|
210
|
+
```
|
211
|
+
|
212
|
+
### Substitutions ###
|
213
|
+
|
214
|
+
Substitutions can be used to customize multi-recipient emails, and tailor them for the user
|
215
|
+
|
216
|
+
```Ruby
|
217
|
+
mail = SendgridRuby::Email.new
|
218
|
+
mail.add_to('john@somewhere.com')
|
219
|
+
.add_to("harry@somewhere.com")
|
220
|
+
.add_to("Bob@somewhere.com")
|
221
|
+
...
|
222
|
+
.set_html("Hey name, we've seen that you've been gone for a while")
|
223
|
+
.add_substitution("name", ["John", "Harry", "Bob"])
|
224
|
+
```
|
225
|
+
|
226
|
+
### Sections ###
|
227
|
+
|
228
|
+
Sections can be used to further customize messages for the end users. A section is only useful in conjunction with a substition value.
|
229
|
+
|
230
|
+
```Ruby
|
231
|
+
mail = SendgridRuby::Email.new
|
232
|
+
mail.add_to('john@somewhere.com')
|
233
|
+
.add_to("harry@somewhere.com")
|
234
|
+
.add_to("Bob@somewhere.com")
|
235
|
+
...
|
236
|
+
.set_html("Hey name, you work at place")
|
237
|
+
.add_substitution("name", ["John", "Harry", "Bob"])
|
238
|
+
.add_substitution("place", ["office", "office", "home"])
|
239
|
+
.add_section("office", "an office")
|
240
|
+
.add_section("home", "your house")
|
241
|
+
```
|
242
|
+
|
243
|
+
### Unique Arguments ###
|
244
|
+
|
245
|
+
Unique Arguments are used for tracking purposes
|
246
|
+
|
247
|
+
```Ruby
|
248
|
+
mail = SendgridRuby::Email.new
|
249
|
+
mail.add_to('foo@bar.com')
|
250
|
+
...
|
251
|
+
.add_unique_arg("Customer", "Someone")
|
252
|
+
.add_unique_arg("location", "Somewhere")
|
253
|
+
.set_unique_args({'cow' => 'chicken'})
|
254
|
+
```
|
255
|
+
|
256
|
+
### Filter Settings ###
|
257
|
+
|
258
|
+
Filter Settings are used to enable and disable apps, and to pass parameters to those apps.
|
259
|
+
|
260
|
+
```Ruby
|
261
|
+
mail = SendgridRuby::Email.new
|
262
|
+
mail.add_to('foo@bar.com')
|
263
|
+
...
|
264
|
+
.add_filter("gravatar", "enable", 1)
|
265
|
+
.add_filter("footer", "enable", 1)
|
266
|
+
.add_filter("footer", "text/plain", "Here is a plain text footer")
|
267
|
+
.add_filter("footer", "text/html", "<p style='color:red;'>Here is an HTML footer</p>")
|
268
|
+
```
|
269
|
+
|
270
|
+
### Headers ###
|
271
|
+
|
272
|
+
You can add standard email message headers as necessary.
|
273
|
+
|
274
|
+
```Ruby
|
275
|
+
mail = SendgridRuby::Email.new
|
276
|
+
mail.add_to('foo@bar.com')
|
277
|
+
...
|
278
|
+
.add_header('X-Sent-Using', 'SendGrid-API')
|
279
|
+
.add_header('X-Transport', 'web')
|
280
|
+
```
|
281
|
+
|
282
|
+
### Output debug log ###
|
283
|
+
|
284
|
+
You can output the log for debug to $stderr
|
285
|
+
|
286
|
+
```Ruby
|
287
|
+
mail = SendgridRuby::Email.new
|
288
|
+
mail.add_to('foo@bar.com')
|
289
|
+
...
|
290
|
+
.add_header('X-Sent-Using', 'SendGrid-API')
|
291
|
+
.add_header('X-Transport', 'web')
|
292
|
+
|
293
|
+
sendgrid = SendgridRuby::Sendgrid.new(sendgrid_username, sendgrid_password)
|
294
|
+
sendgrid.debug_output = true
|
295
|
+
sendgrid.send(mail)
|
296
|
+
```
|
297
|
+
|
298
|
+
### Sending to 1,000s of emails in one batch
|
299
|
+
|
300
|
+
Sometimes you might want to send 1,000s of emails in one request. You can do that. It is recommended you break each batch up in 1,000 increements. So if you need to send to 5,000 emails, then you'd break this into a loop of 1,000 emails at a time.
|
301
|
+
|
302
|
+
```Ruby
|
303
|
+
sendgrid = SendgridRuby::Sendgrid.new(sendgrid_username, sendgrid_password)
|
304
|
+
mail = SendgridRuby::Email.new
|
305
|
+
|
306
|
+
recipients = ["alpha@mailinator.com", "beta@mailinator.com", "zeta@mailinator.com"]
|
307
|
+
names = ["Alpha", "Beta", "Zeta"]
|
308
|
+
|
309
|
+
email.set_from("from@mailinator.com")
|
310
|
+
.set_subject('[sendgrid-ruby-batch-email]')
|
311
|
+
.set_tos($recipients)
|
312
|
+
.add_substitution("name", $names)
|
313
|
+
.set_text("Hey name, we have an email for you")
|
314
|
+
.set_html("<h1>Hey name, we have an email for you</h1>")
|
315
|
+
|
316
|
+
result = sendgrid.send(mail)
|
317
|
+
```
|
318
|
+
|
319
|
+
### Ignoring SSL certificate verification
|
320
|
+
|
321
|
+
You can optionally ignore verification of SSL certificate when using the Web API.
|
322
|
+
|
323
|
+
```Ruby
|
324
|
+
options = {"turn_off_ssl_verification" => true}
|
325
|
+
sendgrid = SendgridRuby::Sendgrid.new(SENDGRID_USERNAME, SENDGRID_PASSWORD, options)
|
326
|
+
|
327
|
+
mail = SendgridRuby::Email.new
|
328
|
+
...
|
329
|
+
result = sendgrid.send(email)
|
330
|
+
```
|
331
|
+
|
332
|
+
## Contributing
|
333
|
+
|
334
|
+
1. Fork it ( http://github.com/<my-github-username>/sendgrid/fork )
|
335
|
+
2. Create your feature branch (`git checkout -b my-new-feature`)
|
336
|
+
3. Commit your changes (`git commit -am 'Add some feature'`)
|
337
|
+
4. Push to the branch (`git push origin my-new-feature`)
|
338
|
+
5. Create new Pull Request
|
339
|
+
|
340
|
+
## Running Test
|
341
|
+
|
342
|
+
The existing tests in the `test` directory can be run using unit test.
|
343
|
+
|
344
|
+
````bash
|
345
|
+
rake test
|
346
|
+
```
|
347
|
+
|
data/Rakefile
ADDED