node-sendgrid: SendGrid SMTP API headers library

version: 0.0.4

Copyright (c)2011, by Branko Vukelic branko@herdhound.com

Licensed under MIT license (see LICENSE)

node-sendgrid implements the standard SendGrid SMTP API headers for use with libraries like Nodemailer. It currently does not actually send emails. It is just used to generate the SMTP API headers.

You can find the original API documentation on SendGrid SMTP API documentation page. node-sendgrid tries to follow the official API as close as possible.

Status

This library has not yet been fully tested. File any issues you encounter in issue tracker.

Installation

The easiest way to install node-sendgrid is to use npm:

npm install node-sendgrid

It has no external dependencies.

Usage example

The headers API is implemented through Headers constructor:

var Headers = require('node-sendgrid').Headers;

The constructor takes a single argument which sets up the defaults.

var recipients = ['test1@example.com', 'test2@example.com'];
var headers = new Headers({
    to: recipients, 
    sub: {email: recipients},
    category: 'test'
});

You can now add more headers using headers methods (documented further below):

headers.addFilterSetting('clicktrack', 'enable', 1)

All defined headers can be accessed through the headers property of the headers object:

console.log(headers.headers);
// Outputs:
// { to: [ 'test1@example.com', 'test2@example.com' ],
//   sub: { email: [ 'test1@example.com', 'test2@example.com' ] },
//   category: 'test',
//   filters: { clicktrack: { settings: [Object] } } }

The headers are prepared for usage as a single SMTP API header by calling the toString() method. Here is an example using Nodemailer.

var mailer = require('nodemailer');
mailer.SMTP = config.email.sendgrid;
mailer.send_mail({
    to: 'test1@example.com',
    sender: 'me@mysite.com',
    ...
    headers: {'X-SMTPAPI': headers.toString()}
}, function(err, sent) {
    console.log('Email was ' + (sent && 'sent' || 'not sent');
});

The X-SMTPAPI header would look like this:

'{"to":["test1@example.com","test2@example.com"],
"sub":{"email":["test1@example.com","test2@example.com"]},
"category":"test","filters":{"clicktrack":{"settings":
{"enable":1}}}}'

Default headers

As discussed above, default headers are set by passing parameters to the constructor. The parameters are:

• to: additional recipients. This is used to send a single message to multiple recipients.
• sub: substitution variables (sub vars). Email body may contain placeholders that can be substituted using sub vars. The placeholder looks like <% myPlaceholder %>. The sub vars are key-value pairs, where the key corresponds to the name of the placeholder. If value is an array, it needs to contain the same number of items as the number of recipients.
• unique: unique arguments. Unique args are used for tracking purposes. As with sub vars, unique args are key-value pairs, and val must contain the same number of values as the number of recipients if it is an array.
• category: logging category. The name of the category under which the email will be logged.
• filters: filter settings. The filter-setting pairs that match filter name with a settings object.

Headers object methods

Headers object has a few methods that allows you to fine-tune the headers definition once the object is created using the constructor:

• addTo(to): set the to header. to can be a string or an array of strings containing recipient email addresses.
• addSubVal(key, val): set the sub vars. Sets a single key-val sub var pair.
• setUniqueArgs(args): set unique args. Sets key-value pairs of unique args to args object. Note that this overrides the default set from in the constructor.
• setCategory(category): set the category name. This overrides the category name set in the constructor.
• addFilterSetting(filter, setting, val): set a single filter setting. Sets the setting value of a setting for the filter to val.

The headers object supports one more method toString() which returns the JSON string representation of the headers object.

Filter settings

The list of filters and their settings can be found in the SendGrid documentation.