This nodejs module allows you to quickly and easily send emails through SendGrid using nodejs.
var sendgrid = require('sendgrid')(sendgrid_api_key);
sendgrid.send({
to: '[email protected]',
from: '[email protected]',
subject: 'Hello World',
text: 'My first email through SendGrid.'
}, function(err, json) {
if (err) { return console.error(err); }
console.log(json);
});
The following recommended installation requires npm. If you are unfamiliar with npm, see the npm docs. Npm comes installed with Node.js since node version 0.8.x therefore you likely already have it.
Add the following to your package.json
file:
{
...
"dependencies": {
...
"sendgrid": "^1.9.2"
}
}
Install sendgrid-nodejs and its dependencies:
npm install
You can also install sendgrid locally with the following command:
npm install sendgrid
There is a sendgrid-nodejs-example app to help jumpstart your development.
To begin using this library, initialize the SendGrid object with your SendGrid credentials OR a SendGrid API Key. API Key is the preferred method. To configure API keys, visit https://app.sendgrid.com/settings/api_keys.
var sendgrid = require('sendgrid')(sendgrid_api_key);
// OR
var sendgrid = require('sendgrid')(api_user, api_password);
Create a new JavaScript object with your message details.
var payload = {
to : '[email protected]',
from : '[email protected]',
subject : 'Saying Hi',
text : 'This is my first email through SendGrid'
}
Send it.
sendgrid.send(payload, function(err, json) {
if (err) { console.error(err); }
console.log(json);
});
Email helps you more powerfully prepare your message to be sent.
To get started create an Email object where params
is a javascript object. You can pass in as much or as little to params
as you want.
var sendgrid = require('sendgrid')(api_user, api_password);
var email = new sendgrid.Email(params);
Here is a sample for using it.
var sendgrid = require('sendgrid')(api_user, api_password);
var email = new sendgrid.Email({
to: '[email protected]',
from: '[email protected]',
subject: 'Subject goes here',
text: 'Hello world'
});
sendgrid.send(email, function(err, json) {
if (err) { return console.error(err); }
console.log(json);
});
var params = {
smtpapi: new sendgrid.smtpapi(),
to: [],
toname: [],
from: '',
fromname: '',
subject: '',
text: '',
html: '',
bcc: [],
cc: [],
replyto: '',
date: '',
files: [
{
filename: '', // required only if file.content is used.
contentType: '', // optional
cid: '', // optional, used to specify cid for inline content
path: '', //
url: '', // == One of these three options is required
content: ('' | Buffer) //
}
],
file_data: {},
headers: {}
};
NOTE: anything that is available in the Email constructor is available for use in the sendgrid.send
function.
You can set params like you would for any standard JavaScript object.
var sendgrid = require('sendgrid')(api_user, api_password);
var email = new sendgrid.Email({to: '[email protected]'});
email.to = "[email protected]";
email.replyto = "[email protected]";
email.subject = "This is a subject";
You can add one or multiple TO addresses using addTo
.
var email = new sendgrid.Email();
email.addTo('[email protected]');
email.addTo('[email protected]');
sendgrid.send(email, function(err, json) { });
NOTE: This is different than setting an array on to
. The array on to
will show everyone the to addresses it was sent to. Using addTo will not. Usually, you'll want to use addTo
.
var email = new sendgrid.Email();
email.setTos(['[email protected]', '[email protected]']);
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setFrom('[email protected]');
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setFromName('Bob Bar');
sendgrid.send(email, function(err, json) { });
You can add one or multiple CC addresses using addCc
.
var email = new sendgrid.Email();
email.addCc('[email protected]');
email.addCc('[email protected]');
sendgrid.send(email, function(err, json) { });
You can multiple CC addresses using setCcs
.
var email = new sendgrid.Email();
email.setCcs(['[email protected]', '[email protected]']);
sendgrid.send(email, function(err, json) { });
You can add one or multiple BCC addresses using addBcc
.
var email = new sendgrid.Email();
email.addBcc('[email protected]');
email.addBcc('[email protected]');
sendgrid.send(email, function(err, json) { });
You can multiple BCC addresses using setBccs
.
var email = new sendgrid.Email();
email.setBccs(['[email protected]', '[email protected]']);
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setSubject('Some subject');
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setText('Some text');
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setHtml('<h1>Some html</h1>');
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setDate('Wed, 17 Dec 2014 19:21:16 +0000');
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setSendAt(1409348513);
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.setSendEachAt([1409348513, 1409348514]);
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.addSendEachAt(1409348513);
email.addSendEachAt(1409348514);
sendgrid.send(email, function(err, json) { });
You can add custom headers. This will ADD rather than SET headers.
var email = new sendgrid.Email();
email.setHeaders({full: 'hearts'}); // headers = {full: 'hearts'}
email.addHeader('spin', 'attack'); // headers = {full: 'hearts', spin: 'attack'}
email.addHeader('mask', 'salesman'); // headers = {full: 'hearts', spin: 'attack', mask: 'salesman'}
sendgrid.send(email, function(err, json) { });
You can set custom headers.
var email = new sendgrid.Email();
email.setHeaders({full: 'hearts'}); // headers = {full: 'hearts'}
email.setHeaders({mask: 'salesman'}); // headers = {mask: 'salesman'}
sendgrid.send(email, function(err, json) { });
var email = new sendgrid.Email();
email.addSubstitution('keep', 'secret'); // sub = {keep: ['secret']}
email.addSubstitution('other', ['one', 'two']); // sub = {keep: ['secret'], other: ['one', 'two']}
var email = new sendgrid.Email();
email.setSubstitutions({keep: ['secret'], other: ['one', 'two']}); // sub = {keep: ['secret'], other: ['one', 'two']});
var email = new sendgrid.Email();
email.addSection('-charge-', 'This ship is useless.'); // section = {'-charge-': 'This ship is useless.'}
var email = new sendgrid.Email();
email.setSections({'-charge-': 'This ship is useless.'}); // section = {'-charge-': 'This ship is useless.'}
var email = new sendgrid.Email();
email.setUniqueArgs({cow: 'chicken'}); // unique_args = {cow: 'chicken'}
email.addUniqueArg('cat', 'dog'); // unique_args = {cow: 'chicken', cat: 'dog'}
var email = new sendgrid.Email();
email.setUniqueArgs({cow: 'chicken'}); // unique_args = {cow: 'chicken'}
email.setUniqueArgs({dad: 'proud'}); // unique_args = {dad: 'proud'}
var email = new sendgrid.Email();
email.addCategory('tactics'); // category = ['tactics']
email.addCategory('advanced'); // category = ['tactics', 'advanced']
var email = new sendgrid.Email();
email.setCategories(['tactics']); // category = ['tactics']
email.setCategories(['snowball-fight']); // category = ['snowball-fight']
Alternatively, you can add filter settings one at a time.
var email = new sendgrid.Email();
email.addFilter('footer', 'enable', 1);
email.addFilter('footer', 'text/html', '<strong>boo</strong>');
You can set a filter using an object literal.
var email = new sendgrid.Email();
email.setFilters({
'footer': {
'settings': {
'enable': 1,
'text/html': '<strong>You can haz footers!</strong>'
}
}
});
You can set an ASM Group ID using an integer.
var email = new sendgrid.Email();
email.setASMGroupID(123); // asm_group_id = 123
You can add files directly from content in memory. It will try to guess the contentType based on the filename.
email.addFile({
filename: 'secret.txt',
content: new Buffer('You will never know....')
});
You can add files directly from a url. It will try to guess the contentType based on the filename. Note: filename
is required when using a url.
email.addFile({
filename: 'icon.jpg',
url: 'http://i.imgur.com/2fDh8.jpg'
});
You can add files from a path on the filesystem. It will try to grap the filename and contentType from the path.
email.addFile({
path: '../files/resume.txt'
});
You can tag files for use as inline HTML content. It will mark the file for inline disposition using the specified "cid".
email.addFile({
cid: 'the_logo', // should match cid value in html
path: '../files/logo.png'
});
email.addHtml('<div>Our logo:<img src="cid:the_logo"></div>');
You can easily use SendGrid's template engine.
var email = new sendgrid.Email();
email.addTo('[email protected]');
email.subject = "Send with templates app";
email.from = '[email protected]';
email.text = 'Hi there!';
email.html = '<h1>Hi there!</h1>';
// add filter settings one at a time
email.addFilter('templates', 'enable', 1);
email.addFilter('templates', 'template_id', '09c6ab89-9157-4710-8ca4-db7927c631d6');
// or set a filter using an object literal.
email.setFilters({
'templates': {
'settings': {
'enable': 1,
'template_id' : '09c6ab89-9157-4710-8ca4-db7927c631d6',
}
}
});
You may change the URL sendgrid-nodejs uses to send email by supplying various parameters to options
, all parameters are optional:
var sendgrid = require('sendgrid')('username', 'password', { "protocol" : "http", "host" : "sendgrid.org", "endpoint" : "/send", "port" : "80" });
A full URI may also be provided:
var sendgrid = require('sendgrid')('username', 'password', { "uri" : "http://sendgrid.org:80/send" });
sendgrid-nodejs uses the node request module. You can pass in options to be merged. This enables you to use your own https.Agent, node-tunnel or the request proxy url. Please note that sendgrid requires https.
var sendgrid = require('sendgrid')('username', 'password', {
proxy: "http://localproxy:3128" });
or
var https = require('https');
var agent = new https.Agent();
// Set Max Sockets to 500
agent.maxSockets = 500;
var sendgrid = require('sendgrid')('username', 'password', { web: {
pool: agent } });
When filing an issue please include your package.json
and the output of
npm ls sendgrid
to help us isolate and repro the issue
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
The existing tests can be run using Mocha with the following command:
npm test
You can run individual tests with the following command:
./node_modules/.bin/mocha [path to test].js
In order to run the integration tests, you'll need to update the environment file with your valid SendGrid credentials. Start by making a live copy of the example:
cp .env.example .env.test
Next, open up .env.test
and fill it in. After you have updated the environment file with your credentials, you can run the suite using the following command:
npm test
- Confirm tests pass
- Bump the version in
README.md
,package.json
,test/lib/sendgrid.test.js
- Update
CHANGELOG.md
- Confirm tests pass
- Commit
Version bump vX.X.X
npm publish
- Push changes to GitHub
- Release tag on GitHub
vX.X.X
Licensed under the MIT License.