Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 213 lines (169 sloc) 6.108 kb
1cc3b0c @partkyle Updated to show the correct npm module name.
partkyle authored
1 # sendgrid #
6cb8ca9 @siyegen README first pass
siyegen authored
2 This nodejs module allows you to quickly and easily send emails through
3 SendGrid using nodejs.
4
4cba87a @siyegen Update README.md
siyegen authored
5 ## License ##
6 Licensed under the MIT License.
7
6cb8ca9 @siyegen README first pass
siyegen authored
8 ## Install ##
0269938 @partkyle Update README.md
partkyle authored
9
6cb8ca9 @siyegen README first pass
siyegen authored
10 ```
1cc3b0c @partkyle Updated to show the correct npm module name.
partkyle authored
11 npm install sendgrid
6cb8ca9 @siyegen README first pass
siyegen authored
12 ```
0269938 @partkyle Update README.md
partkyle authored
13
233ed85 @theycallmeswift Cleaned up and documented the tests.
theycallmeswift authored
14 ## Testing ##
15
16 In order to run the integration tests, you'll need to update the config file with your valid SendGrid credentials. Start by making a live copy of the sample:
17
18 ```
19 cp test/config.sample.js test/config.js
20 ```
21
22 Next, open up `test/config.js` and fill it in. After you have updated the configuration file with your credentials, you can run the suite using the following command:
23
24 ```
25 make test
26 ```
27
28 You can run individual tests with the following command:
29
30 ```
31 ./node_modules/.bin/mocha [path to test].js
32 ```
33
6cb8ca9 @siyegen README first pass
siyegen authored
34 ## Usage ##
6aaf039 @siyegen Update README.md
siyegen authored
35 ### It can be this easy ###
0269938 @partkyle Update README.md
partkyle authored
36
6cb8ca9 @siyegen README first pass
siyegen authored
37 ```javascript
3c950e2 @iandouglas had it the wrong way around
iandouglas authored
38 var SendGrid = require('sendgrid').SendGrid;
6cb8ca9 @siyegen README first pass
siyegen authored
39 var sendgrid = new SendGrid(user, key);
40 sendgrid.send({
41 to: 'example@example.com',
42 from: 'other@example.com',
43 subject: 'Hello World',
44 text: 'My first email through SendGrid'
2d9f73f @partkyle Updated README.md again - this time correctly.
partkyle authored
45 }, function(success, message) {
46 if (!success) {
47 console.log(message);
48 }
6cb8ca9 @siyegen README first pass
siyegen authored
49 });
50 ```
0269938 @partkyle Update README.md
partkyle authored
51
6cb8ca9 @siyegen README first pass
siyegen authored
52 And you're done!
53
54 ### Digging in ###
4cba87a @siyegen Update README.md
siyegen authored
55 There are two objects that you really need to know to get started:
6cb8ca9 @siyegen README first pass
siyegen authored
56 + SendGrid
57 + Email
58
4cba87a @siyegen Update README.md
siyegen authored
59 #### Email ####
0269938 @partkyle Update README.md
partkyle authored
60 Email is the object that will help you easily perpare your message to be sent.
61
bb6ef52 @partkyle updated comments
partkyle authored
62 NOTE: anything that is available in the Email constructor is available
63 for use in both the `sendgrid.send` and `sendgrid.smtp` functions.
64
0269938 @partkyle Update README.md
partkyle authored
65 To get started create an Email object:
ea3c2d7 @siyegen Update README.md
siyegen authored
66
6cb8ca9 @siyegen README first pass
siyegen authored
67 ```javascript
3c950e2 @iandouglas had it the wrong way around
iandouglas authored
68 var Email = require('sendgrid').Email;
6cb8ca9 @siyegen README first pass
siyegen authored
69 var email = new Email(optionalParams);
70 ```
0269938 @partkyle Update README.md
partkyle authored
71
4f2210f @partkyle fixed some typos
partkyle authored
72 You can pass in as much or as little to optionalParams as you want, as
6cb8ca9 @siyegen README first pass
siyegen authored
73 the email object has methods for manipulating all of the data.
74
75 **params structure**
ea3c2d7 @siyegen Update README.md
siyegen authored
76
6cb8ca9 @siyegen README first pass
siyegen authored
77 ```javascript
b973e10 @partkyle added documentation for files
partkyle authored
78 var optionalParams = {
79 to: [],
80 from: '',
81 smtpapi: new SmtpapiHeaders(),
82 subject: '',
83 text: '',
84 html: '',
85 bcc: [],
86 replyto: '',
87 date: new Date(),
88 files: [
89 {
3570ad0 @partkyle Update README.md
partkyle authored
90 filename: '', // required only if file.content is used.
91 contentType: '', // optional
92 path: '', //
93 url: '', // == One of these three options is required
94 content: ('' | Buffer) //
b973e10 @partkyle added documentation for files
partkyle authored
95 }
96 ],
97 file_data: {},
6cb8ca9 @siyegen README first pass
siyegen authored
98 headers: {}
b973e10 @partkyle added documentation for files
partkyle authored
99 };
6cb8ca9 @siyegen README first pass
siyegen authored
100 ```
0269938 @partkyle Update README.md
partkyle authored
101
6cb8ca9 @siyegen README first pass
siyegen authored
102 Sample for using it:
ea3c2d7 @siyegen Update README.md
siyegen authored
103
6cb8ca9 @siyegen README first pass
siyegen authored
104 ```javascript
105 var email = new Email({
0269938 @partkyle Update README.md
partkyle authored
106 to: 'walks.it.in@sample.com',
107 from: 'arsenal@sample.com',
bb6ef52 @partkyle updated comments
partkyle authored
108 subject: 'What was Wenger thinking sending Walcott on that early?',
6cb8ca9 @siyegen README first pass
siyegen authored
109 text: 'Did you see that ludicrous display last night?'
110 });
111 ```
112
113 ##### Setting data #####
4cf49c9 @partkyle Update README.md
partkyle authored
114 Here is an example of all of the functions available on the email object. The comments to the right show the current state of the variables as the functions are called. If you have specific question, see the [SendGrid API Docs](http://docs.sendgrid.com/documentation/api/). Feel free to open an issue if you find bugs or missing features.
ea3c2d7 @siyegen Update README.md
siyegen authored
115
6cb8ca9 @siyegen README first pass
siyegen authored
116 ```javascript
117 var email = new Email({
0269938 @partkyle Update README.md
partkyle authored
118 to: 'denim@sample.com',
119 from: 'roy@sample.com',
6cb8ca9 @siyegen README first pass
siyegen authored
120 subject: 'Listen',
4f2210f @partkyle fixed some typos
partkyle authored
121 text: 'Have you tried turning it off and on again'
6cb8ca9 @siyegen README first pass
siyegen authored
122 });
123
4cf49c9 @partkyle Update README.md
partkyle authored
124 /** The following examples update the 'x-smtpapi' headers **/
125
0269938 @partkyle Update README.md
partkyle authored
126 /* To Addresses */
4cf49c9 @partkyle Update README.md
partkyle authored
127 email.addTo('moo@cow.com'); // to = ['moo@cow.com']
128 email.addTo(['solid@snake.com',
129 'liquid@snake.com']); // to = ['moo@cow.com', 'solid@snake.com', 'liquid@snake.com']
0269938 @partkyle Update README.md
partkyle authored
130
131 /* Custom Email Headers */
132 email.setHeaders({full: 'hearts'}); // headers = {full: 'hearts'}
133 email.addHeaders({spin: 'attack'}); // headers = {full: 'hearts', spin: 'attack'}
134 email.setHeaders({mask: 'salesman'}); // headers = {mask: 'salesman'}
135
136 /* Substitution */
137 email.addSubVal('keep', 'secret'); // sub = {keep: ['secret']}
138 email.addSubVal('keep', 'safe'); // sub = {keep: ['secret', 'safe']}
139
140 /* Section */
141 email.setSection({'-charge-': 'This ship is useless.'}); // section = {'-charge-': 'This ship is useless.'}
142 email.addSection({'-bomber-': 'Only for sad vikings.'}); // section = {'-charge-': 'This ship is useless.',
143 // '-bomber-': 'Only for sad vikings.'}
144 email.setSection({'-beam-': 'The best is for first'}); // section = {'-beam-': 'The best is for first'}
145
146 /* Unique Args */
147 email.setUniqueArgs({cow: 'chicken'}); // unique_args = {cow: 'chicken'}
148 email.addUniqueArgs({cat: 'dog'}); // unique_args = {cow: 'chicken', cat: 'dog'}
149 email.setUniqueArgs({dad: 'proud'}); // unique_args = {dad: 'proud'}
150
151 /* Category */
152 email.setCategory('tactics'); // category = ['tactics']
153 email.addCategory('advanced'); // category = ['tactics', 'advanced']
154 email.setCategory('snowball-fight'); // category = ['snowball-fight']
155
156 /* Filters */
157 // You can set a filter using an object literal
6cb8ca9 @siyegen README first pass
siyegen authored
158 email.setFilterSetting({
159 'footer': {
160 'setting': {
161 'enable': 1,
162 'text/plain': 'You can haz footers!'
163 }
164 }
165 });
0269938 @partkyle Update README.md
partkyle authored
166
167 // Alternatively, you can add filter settings one at a time.
6cb8ca9 @siyegen README first pass
siyegen authored
168 email.addFilterSetting('footer', 'enable', 1);
fad8972 @jurias Update README.md
jurias authored
169 email.addFilterSetting('footer', 'text/html', '<strong>boo</strong>');
6cb8ca9 @siyegen README first pass
siyegen authored
170
0269938 @partkyle Update README.md
partkyle authored
171 /* Attachments */
b973e10 @partkyle added documentation for files
partkyle authored
172
173 /*
174 * You can add files directly from content in memory.
175 *
176 * It will try to guess the contentType based on the filename.
177 */
178 email.addFile({
179 filename: 'secret.txt',
180 content: new Buffer('You will never know....')
181 });
182
183 /*
184 * You can add files directly from a url.
185 *
186 * It will try to guess the contentType based on the filename.
187 */
188 email.addFile({
189 filename: 'icon.jpg',
190 url: 'http://i.imgur.com/2fDh8.jpg'
191 });
192
193 /*
194 * You can add files from a path on the filesystem.
195 *
196 * It will try to grap the filename and contentType from the path.
197 */
198 email.addFile({
199 path: '../files/resume.txt'
200 });
6cb8ca9 @siyegen README first pass
siyegen authored
201 ```
202
203 ## Tests ##
0269938 @partkyle Update README.md
partkyle authored
204
4cf49c9 @partkyle Update README.md
partkyle authored
205 * Test written in the test/lib folder can be ran as-is and should all pass.
206 * Test written in test/intergration need values in test/test.setup to be set in order to run. These require a valid SendGrid account. These tests send real emails, so be advised.
6cb8ca9 @siyegen README first pass
siyegen authored
207
0269938 @partkyle Update README.md
partkyle authored
208 `make test` will run all tests.
ea3c2d7 @siyegen Update README.md
siyegen authored
209
0269938 @partkyle Update README.md
partkyle authored
210 You can run individual tests with `mocha /path/to/test.test.js`
ea3c2d7 @siyegen Update README.md
siyegen authored
211
bb6ef52 @partkyle updated comments
partkyle authored
212 For information on how to use Sendgrid see the [SendGrid API Docs](http://docs.sendgrid.com/documentation/api/)
Something went wrong with that request. Please try again.