| title | description | services | documentationcenter | author | manager | editor | ms.assetid | ms.service | ms.workload | ms.tgt_pltfrm | ms.devlang | ms.topic | ms.date | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
How to use the SendGrid email service (Node.js) | Microsoft Docs |
Learn how send email with the SendGrid email service on Azure. Code samples written using the Node.js API. |
nodejs |
erikre |
wpickett |
cac444b4-26b0-45ea-9c3d-eca28d57dacb |
multiple |
na |
na |
nodejs |
article |
01/05/2016 |
erikre |
This guide demonstrates how to perform common programming tasks with the SendGrid email service on 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.
SendGrid is a cloud-based email service that provides reliable transactional 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 https://sendgrid.com.
[!INCLUDE sendgrid-sign-up]
The SendGrid module for Node.js can be installed through the node package manager (npm) by using the following command:
npm install sendgrid
After installation, you can require the module in your application by using the following code:
var sendgrid = require('sendgrid')(sendgrid_username, sendgrid_password);
The SendGrid module exports the SendGrid and Email functions. SendGrid is responsible for sending email through Web API, while Email encapsulates an email message.
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 email = new sendgrid.Email({
to: '[email protected]',
from: '[email protected]',
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.
After creating an email message using the Email function, you can send it using the Web API provided by SendGrid.
sendgrid.send(email, function(err, json){
if(err) { return console.error(err); }
console.log(json);
});
Note
While the above examples show passing in an email object and callback function, you can also directly invoke the send function by directly specifying email properties. For example:
sendgrid.send({
to: '[email protected]',
from: '[email protected]',
subject: 'test mail',
text: 'This is a sample email message.'
});
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:
sendgrid.send({
to: '[email protected]',
from: '[email protected]',
subject: 'test mail',
text: 'This is a sample email message.',
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) //
}
],
});
Note
When using the files property, the file must be accessible through fs.readFile. If the file you wish to attach is hosted in Azure Storage, such as in a Blob container, you must first copy the file to local storage or to an Azure drive before it can be sent as an attachment using the files property.
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 and click tracking filters:
var email = new sendgrid.Email({
to: '[email protected]',
from: '[email protected]',
subject: 'test mail',
text: 'This is a sample email message.'
});
email.setFilters({
'footer': {
'settings': {
'enable': 1,
'text/plain': 'This is a text footer.'
}
}
});
sendgrid.send(email);
var email = new sendgrid.Email({
to: '[email protected]',
from: '[email protected]',
subject: 'test mail',
text: 'This is a sample email message.'
});
email.setFilters({
'clicktrack': {
'settings': {
'enable': 1
}
}
});
sendgrid.send(email);
Some email properties can be overwritten using setProperty or appended using addProperty. For example, you can add additional recipients by using
email.addTo('[email protected]');
or set a filter by using
email.addFilter('footer', 'enable', 1);
email.addFilter('footer', 'text/html', '<strong>boo</strong>');
For more information, see sendgrid-nodejs.
SendGrid offers web-based APIs that you can use to leverage additional SendGrid functionality from your Azure application. For full details, see the SendGrid API documentation.
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: https://sendgrid.com/docs
- SendGrid special offer for Azure customers: http://sendgrid.com/azure.html