A NodeJS implementation of the SendGrid Api.


This nodejs module allows you to quickly and easily send emails through SendGrid using nodejs.

npm install sendgrid-nodejs
var SendGrid = require('sendgrid-nodejs').SendGrid;
var sendgrid = new SendGrid(user, key);
  to: '',
  from: '',
  subject: 'Hello World',
  text: 'My first email through SendGrid'

And you're done!

There are two objects that you really need to know to get started:

  • SendGrid
  • Email

Email is the object that will help you easily perpare your message to be sent. To get started create an Email object

var email = new Email(optionalParams);

You can pass in as much or as litle to optionalParams as you want, as the email object has methods for manipulating all of the data.

params structure

var default_mail_params = {
  to: [],
  from: '',
  smtpapi: new SmtpapiHeaders(),
  subject: '',
  text: '',
  html: '',
  bcc: [],
  replyto: '',
  date: new Date(),
  files: {},
  file_data: {},
  headers: {}

Sample for using it:

var email = new Email({
  to: '',
  from: '',
  subject: 'Hey',
  text: 'Did you see that ludicrous display last night?'

In general setting a value will override it while adding that value will add it to the existing values but will override existing keys with the new value.

var email = new Email({
  to: '',
  from: '',
  subject: 'Listen',
  text: 'Haved you tried turning it off and on again'
// Add other to addresses 
// addTo also takes an array 
email.addTo(['', '']);
// setHeaders will override any header values already set 
email.setHeaders({customHeader: 'some-value'});
// addHeaders will add to existing headers, overriding existing keys 
email.addHeaders({customHeaderTwo: 'Another value'});
// Adding substitution values 
email.addSubVal('key', value);
// Setting unique args will override any values already set 
email.setUniqueArgs({cow: 'chicken'});
// Adding unique args will add to existing values, overriding existing 
email.addUniqueArgs({cat: 'dog'});
// Setting/Adding a category 
// Setting/Adding a Section 
email.setSection({'-section-': 'text name'});
email.addSection({'-other-': 'person name'});
// Setting a Filter, takes an object literal 
  'footer': {
    'setting': {
      'enable': 1,
      'text/plain': 'You can haz footers!'
// Adding a filter via addFilterSetting 
email.addFilterSetting('footer', 'enable', 1);
email.addFilterSetting('footer', 'text/hmtl', '<strong>boo</strong>');
// Adding a file 
email.addFile('secret.txt', '/path/to/file');

More examples can be find in the test 

If you're interested in seeing some sample code or just want to run the test then here's what you need to know. Test written in the test/lib folder can be ran as in and should all pass. Test written in test/intergration need the values in test/test.setup to be set in order to run and will require a SendGrid account, as these test will send actual emails.


make test

will run all tests, otherwise you can run individual tests by running

mocha /path/to/test.test.js

For information on how to use Sendgrid see: SendGrid API Docs