---

layout: page

weight: 0

title: Node.js

navigation:

show: true

---

<p>If you are using Node.js and would like to send email through SendGrid, use the SendGrid nodejs module. Full documentation for this module can be found on <a

href="http://github.com/sendgrid/sendgrid-nodejs">github</a>.</p>

{% codeblock lang:javascript %}

var sendgrid = require('sendgrid')(api_user, api_key);

sendgrid.send({

to: 'example@example.com',

from: 'other@example.com',

subject: 'Hello World',

text: 'My first email through SendGrid.'

}, function(err, json) {

if (err) { return console.error(err); }

console.log(json);

});

{% endcodeblock %}

{% anchor h3 %}

Installation

{% endanchor %}

<p>Detailed instructions for installing are available at the <a href="https://github.com/sendgrid/sendgrid-nodejs#installation">sendgrid-nodejs installation instructions</a>.</p>

{% codeblock %}

npm install sendgrid

{% endcodeblock %}

{% anchor h3 %}

Usage

{% endanchor %}

<p>For the most up to date usage examples, visit the <a href="https://github.com/sendgrid/sendgrid-nodejs#usage">sendgrid-nodejs library usage instructions</a>.</p>

<p>Email is the object that will help you easily prepare your message to be sent.</p>

{% info %}

Anything that is available in the Email constructor is available for use in both the sendgrid.send and sendgrid.smtp functions.

{% endinfo %}

<p>To get started create an Email object:</p>

{% codeblock lang:javascript %}

var Email = require('sendgrid').Email;

var email = new Email(optionalParams);

{% endcodeblock %}

<p>You can pass in as many or as few optionalParams as you want, as the email object has methods for manipulating all of the data.</p>

<p>Here is how the parameters are structured:</p>

{% codeblock lang:javascript %}

var optionalParams = {

to: [],

from: '',

smtpapi: new SmtpapiHeaders(),

subject: '',

text: '',

html: '',

bcc: [],

replyto: '',

date: new Date(),

files: [

{

filename: '', // required only if file.content is used.

contentType: '', // optional

path: '', //

url: '', // == One of these three options is required

content: ('' | Buffer) //

}

],

file_data: {},

headers: {}

};

{% endcodeblock %}

<p>And here is a sample for using it:</p>

{% codeblock lang:javascript %}

var email = new Email({

to: 'walks.it.in@sample.com',

from: 'arsenal@sample.com',

subject: 'What was Wenger thinking sending Walcott on that early?',

text: 'Did you see that ludicrous display last night?'

});

{% endcodeblock %}

{% anchor h3 %}

Setting data

{% endanchor %}

<p>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.</p>

{% codeblock lang:javascript %}

var email = new Email({

to: 'denim@sample.com',

from: 'roy@sample.com',

subject: 'Listen',

text: 'Have you tried turning it off and on again'

});

{% endcodeblock %}

<p>The following examples update the 'x-smtpapi' headers:</p>

{% codeblock lang:javascript %}

/* To Addresses */

email.addTo('moo@cow.com'); // to = ['moo@cow.com']

email.addTo(['solid@snake.com',

'liquid@snake.com']); // to = ['moo@cow.com', 'solid@snake.com', 'liquid@snake.com']

/* Custom Email Headers */

email.setHeaders({full: 'hearts'}); // headers = {full: 'hearts'}

email.addHeaders({spin: 'attack'}); // headers = {full: 'hearts', spin: 'attack'}

email.setHeaders({mask: 'salesman'}); // headers = {mask: 'salesman'}

/* Substitution */

email.addSubVal('keep', 'secret'); // sub = {keep: ['secret']}

email.addSubVal('keep', 'safe'); // sub = {keep: ['secret', 'safe']}

/* Section */

email.setSection({'-charge-': 'This ship is useless.'}); // section = {'-charge-': 'This ship is useless.'}

email.addSection({'-bomber-': 'Only for sad vikings.'}); // section = {'-charge-': 'This ship is useless.','-bomber-': 'Only for sad vikings.'}

email.setSection({'-beam-': 'The best is for first'}); // section = {'-beam-': 'The best is for first'}

{% endcodeblock %}

<p>Setting unique arguments allows you to get more mojo out of your statistics:</p>

{% codeblock lang:javascript %}

email.setUniqueArgs({cow: 'chicken'}); // unique_args = {cow: 'chicken'}

email.addUniqueArgs({cat: 'dog'}); // unique_args = {cow: 'chicken', cat: 'dog'}

email.setUniqueArgs({dad: 'proud'}); // unique_args = {dad: 'proud'}

{% endcodeblock %}

<p>You can set categories with the following:</p>

{% codeblock lang:javascript %}

email.setCategory('tactics'); // category = ['tactics']

email.addCategory('advanced'); // category = ['tactics', 'advanced']

email.setCategory('snowball-fight'); // category = ['snowball-fight']

{% endcodeblock %}

<p>You can set a filter using an object literal:</p>

{% codeblock lang:javascript %}

email.setFilterSetting({

'footer': {

'setting': {

'enable': 1,

'text/plain': 'You can haz footers!'

}

}

});

{% endcodeblock %}

<p>Alternatively, you can add filter settings one at a time.

</p>

{% codeblock lang:javascript %}

email.addFilterSetting('footer', 'enable', 1);

email.addFilterSetting('footer', 'text/html', '<strong>boo</strong>');

{% endcodeblock %}

<p>You can add files as attachments directly from content stored in memory, like so:</p>

{% codeblock lang:javascript %}

email.addFile({

filename: 'secret.txt',

content: new Buffer('You will never know....')

});

{% endcodeblock %}

<p>Alternately, you can include files from a remote URL and will attempt to determine the file type based on the filename:</p>

{% codeblock lang:javascript %}

email.addFile({

filename: 'icon.jpg',

url: 'http://i.imgur.com/2fDh8.jpg'

});

{% endcodeblock %}

<p>Finally, you can add file from a path on the server's local filesystem, also attempting to determine the filetype via the filename:</p>

{% codeblock lang:javascript %}

email.addFile({

path: '../files/resume.txt'

});

{% endcodeblock %}