How to Send Email Using SendGrid from Node.js

This guide demonstrates how to perform common programming tasks with the SendGrid email service on Windows Azure. The samples are written using the Node.js API. The scenarios covered include constructing email, sending email, adding attachments, using filters, and updating properties. For more information on SendGrid and sending email, see the Next Steps section.

Table of Contents

• What is the SendGrid Email Service?
• Create a SendGrid Account
• Reference the SendGrid Node.js Module
• How to: Create an Email
• How to: Send an Email
• How to: Add an Attachment
• How to: Use Filters to Enable Footers, Tracking, and Analytics
• How to: Update Email Properties
• How to: Use Additional SendGrid Services
• Next Steps

What is the SendGrid Email Service?

SendGrid is a cloud-based email service that provides reliable email delivery, scalability, and real-time analytics, along with flexible APIs that make custom integration easy. Common SendGrid usage scenarios include:

• Automatically sending receipts to customers
• Administering distribution lists for sending customers monthly e-fliers and special offers
• Collecting real-time metrics for things like blocked e-mail, and customer responsiveness
• Generating reports to help identify trends
• Forwarding customer inquiries
• Email notifications from your application

For more information, see http://sendgrid.com.

Create a SendGrid Account

Reference the SendGrid Node.js Module

The SendGrid module for Node.js can be installed through the node package manager (npm) by using the following command:

npm install sendgrid-nodejs

After installation, you can require the module in your application by using the following code:

var SendGrid = require('sendgrid-nodejs')

The SendGrid module exports the SendGrid and Email functions. SendGrid is responsible for sending email through either SMTP or Web API, while Email encapsulates an email message.

How to: Create an Email

Creating an email message using the SendGrid module involves first creating an email message using the Email function, and then sending it using the SendGrid function. The following is an example of creating a new message using the Email function:

var mail = new SendGrid.Email({
    to: 'john@contoso.com',
    from: 'anna@contoso.com',
    subject: 'test mail',
    text: 'This is a sample email message.'
});

You can also specify an HTML message for clients that support it by setting the html property. For example:

html: This is a sample <b>HTML<b> email message.

Setting both the text and html properties provides graceful fallback to text content for clients that cannot support HTML messages.

For more information on all properties supported by the Email function, see sendgrid-nodejs.

How to: Send an Email

After creating an email message using the Email function, you can send it using either SMTP or the Web API provided by SendGrid. For details about the benefits and differences of each API, see SMTP vs. Web API in the SendGrid documentation.

Using either the SMTP API or Web API requires that you first initialize the SendGrid function using the user and key of your SendGrid account as follows:

var sender = new SendGrid.SendGrid('user','key');

The message can now be sent using either SMTP or the Web API. The calls are virtually identical, passing the email message and an optional callback function; The callback is used to determine the success or failure of the operation. The following examples show how to send a message using both SMTP and the Web API.

SMTP

sender.smtp(mail, function(success, err){
    if(success) console.log('Email sent');
    else console.log(err);
)});

Web API

sender.send(mail, function(success, err){
    if(success) console.log('Email sent');
    else console.log(err);
)});

sender.send({
    to: 'john@contoso.com',
    from: 'anna@contoso.com',
    subject: 'test mail',
    text: 'This is a sample email message.'
});

How to: Add an Attachment

Attachments can be added to a message by specifying the file name(s) and path(s) in the files property. The following example demonstrates sending an attachment:

sender.send({
    to: 'john@contoso.com',
    from: 'anna@contoso.com',
    subject: 'test mail',
    text: 'This is a sample email message.',
    files: {
        'file1.txt': __dirname + '/file1.txt',
        'image.jpg': __dirname + '/image.jpg'
    }
});

How to: Use Filters to Enable Footers, Tracking, and Twitter

SendGrid provides additional email functionality through the use of filters. These are settings that can be added to an email message to enable specific functionality such as enabling click tracking, Google analytics, subscription tracking, and so on. For a full list of filters, see Filter Settings.

Filters can be applied to a message by using the filters property. Each filter is specified by a hash containing filter-specific settings. The following examples demonstrate the footer, click tracking, and Twitter filters:

Footer

sender.send({
    to: 'john@contoso.com',
    from: 'anna@contoso.com',
    subject: 'test mail',
    text: 'This is a sample email message.',
    filters: {
        'footer': {
            'settings': {
                'enable': 1,
                'text/plain': 'This is a text footer.'
            }
        }
    }
});

Click Tracking

sender.send({
    to: 'john@contoso.com',
    from: 'anna@contoso.com',
    subject: 'test mail',
    text: 'This is a sample email message.',
    filters: {
        'clicktrack': {
            'settings': {
                'enable': 1
            }
        }
    }
});

Twitter

sender.send({
    to: 'john@contoso.com',
    from: 'anna@contoso.com',
    subject: 'test mail',
    text: 'This is a sample email message.',
    filters: {
        'twitter': {
            'settings': {
                'enable': 1,
                'username': 'twitter_username',
                'password': 'twitter_password'
            }
        }
    }
});

How to: Update Email Properties

Some email properties can be overwritten using setProperty or appended using addProperty. For example, you can add additional recipients by using

email.addTo('jeff@contoso.com');

or set a filter by using

email.setFilterSetting({
  'footer': {
    'setting': {
      'enable': 1,
      'text/plain': 'This is a footer.'
    }
  }
});

For more information, see sendgrid-nodejs.

How to: Use Additional SendGrid Services

SendGrid offers web-based APIs that you can use to leverage additional SendGrid functionality from your Windows Azure application. For full details, see the SendGrid API documentation.

Next Steps

Now that you’ve learned the basics of the SendGrid Email service, follow these links to learn more.

• SendGrid Node.js module repository: sendgrid-nodejs
• SendGrid API documentation: http://docs.sendgrid.com/documentation/api/
• SendGrid special offer for Windows Azure customers: http://sendgrid.com/azure.html