@sendgrid/mail
Advanced tools
The @sendgrid/mail package is a Node.js client library for sending emails using the SendGrid email service. It provides an easy-to-use interface for composing and sending emails, including support for attachments, templates, and various email options.
Sending a Simple Email
This feature allows you to send a simple email with a subject, a plain text part, and an HTML part.
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const msg = {
to: 'recipient@example.com',
from: 'sender@example.com',
subject: 'Sending with SendGrid is Fun',
text: 'and easy to do anywhere, even with Node.js',
html: '<strong>and easy to do anywhere, even with Node.js</strong>',
};
sgMail.send(msg);Using Email Templates
This feature allows you to send emails using dynamic templates created on the SendGrid platform. You can pass dynamic data to populate the template.
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const msg = {
to: 'recipient@example.com',
from: 'sender@example.com',
templateId: 'd-12345678901234567890123456789012',
dynamicTemplateData: {
name: 'John',
city: 'Denver'
}
};
sgMail.send(msg);Sending Multiple Emails
This feature allows you to send the same email to multiple recipients with a single API call.
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const messages = [
{
to: 'recipient1@example.com',
from: 'sender@example.com',
subject: 'Hello recipient 1',
text: 'Sending to multiple recipients is easy!'
},
{
to: 'recipient2@example.com',
from: 'sender@example.com',
subject: 'Hello recipient 2',
text: 'Sending to multiple recipients is easy!'
}
];
sgMail.send(messages);Adding Attachments
This feature allows you to send emails with attachments. The attachment content should be base64 encoded.
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const msg = {
to: 'recipient@example.com',
from: 'sender@example.com',
subject: 'Attachment Example',
text: 'Please find the attached file.',
attachments: [
{
content: 'Some base64 encoded content',
filename: 'somefile.txt',
type: 'plain/text',
disposition: 'attachment',
contentId: 'mytext'
}
]
};
sgMail.send(msg);Nodemailer is a module for Node.js applications to allow easy email sending. It supports various transport methods besides SMTP, like Sendmail or Amazon SES. It is a more general-purpose email sending library compared to @sendgrid/mail, which is focused on integrating with SendGrid's service.
mailgun-js is a simple Node.js module for interacting with the Mailgun API. Similar to @sendgrid/mail, it is designed for a specific email service (Mailgun) and provides functionalities to send emails, manage lists, etc. It is a direct competitor to SendGrid's offering.
The postmark module is a Node.js client for the Postmark API. Like @sendgrid/mail, it is service-specific and allows users to send emails through Postmark's transactional email service. It offers features like sending emails, tracking deliveries, and managing bounces.
This is a dedicated service for interaction with the mail endpoint of the Sendgrid API.
Install with npm or yarn:
npm install @sendgrid/mail
yarn add @sendgrid/mail
Load the library and set the API key if you haven’t set it before:
//Load library
const sgMail = require('@sendgrid/mail');
//Set API key
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
Load the library, prepare your email data and use the send method:
//Load library
const sgMail = require('@sendgrid/mail');
//Create email data
const data = {
to: 'recipient@example.org',
from: 'sender@example.org',
subject: 'Hello world',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
};
//Send email
sgMail.send(data);
The to field can contain an array of recipients, which will send a single email with all of the recipients in the to field. The recipients will be able to see each other:
//Load library
const sgMail = require('@sendgrid/mail');
//Create email data
const data = {
to: ['recipient1@example.org', 'recipient2@example.org'],
from: 'sender@example.org',
subject: 'Hello world',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
};
//Send email
sgMail.send(data);
If you want to send multiple individual emails to multiple recipient where they don't see each others email addresses, use sendMultiple instead:
//Load library
const sgMail = require('@sendgrid/mail');
//Create email data
const data = {
to: ['recipient1@example.org', 'recipient2@example.org'],
from: 'sender@example.org',
subject: 'Hello world',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
};
//Send emails
sgMail.sendMultiple(data);
Note that sendMultiple(data) is a convenience shortcut for send(data, true), and alternatively you can also set the isMultiple flag to true on your data object.
The send method also accepts an array of email data if you want to send multiple different single emails with for example different content and sender values. This will send multiple requests (in parallel), so be aware of any API rate restrictions:
//Load library
const sgMail = require('@sendgrid/mail');
//Create emails data
const emails = [
{
to: 'recipient1@example.org',
from: 'sender@example.org',
subject: 'Hello recipient 1',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
},
{
to: 'recipient2@example.org',
from: 'other-sender@example.org',
subject: 'Hello recipient 2',
text: 'Hello other plain world!',
html: '<p>Hello other HTML world!</p>',
},
];
//Send emails
sgMail.send(emails);
You can specify the cc, bcc and replyTo fields for more control over who you send the email to and where people will reply to:
const data = {
to: 'recipient@example.org',
cc: 'someone@example.org',
bcc: ['me@example.org', 'you@example.org'],
from: 'sender@example.org',
replyTo: 'othersender@example.org',
subject: 'Hello world',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
};
The email address fields (to, from, cc, bcc, replyTo) are flexible and can be any of the following:
const data = {
//Simple email address string
to: 'someone@example.org',
//Email address with name
to: 'Some One <someone@example.org>',
//Object with name/email
to: {
name: 'Some One',
email: 'someone@example.org',
},
//Arrays are supported for to, cc and bcc
to: [
'someone@example.org',
'Some One <someone@example.org>',
{
name: 'Some One',
email: 'someone@example.org',
},
],
};
The send and sendMultiple methods return a Promise, so you can handle success and capture errors:
sgMail
.send(data)
.then(() => {
//Celebrate
})
.catch(error => {
//Log friendly error
console.error(error.toString());
//Extract error data
const {message, code, response} = error;
//Extract response data
const {headers, body} = response;
});
Alternatively, pass a callback function as the last parameter:
sgMail
.send(data, (error, result) => {
if (error) {
//Do something with the error
}
else {
//Celebrate
}
});
All other advanced settings are supported and can be passed in through the data object according to the expected format as per the API v3 documentation. Note that you can use either camelCase or snake_case for property names.
Configure the substitution tag wrappers globally:
sgMail.setSubstitutionWrappers('{{', '}}');
Then provide a template ID and substitutions:
const data = {
templateId: 'sendgrid-template-id',
substitutions: {
name: 'Some One',
id: '123',
},
};
Alternatively, you may specify the substitution wrappers via the data object as well. This will override any wrappers you may have configured globally.
const data = {
templateId: 'sendgrid-template-id',
substitutionWrappers: ['{{', '}}'],
substitutions: {
name: 'Some One',
id: '123',
},
};
To send multiple individual emails to multiple recipients with additional customization (like a different subject), use the personalizations field as per the API definition instead of to, leveraging all customization options:
const data = {
personalizations: [
{
to: 'recipient1@example.org',
subject: 'Hello recipient 1',
substitutions: {
name: 'Recipient 1',
id: '123',
},
headers: {
'X-Custom-Header': 'Recipient 1',
},
customArgs: {
myArg: 'Recipient 1',
},
},
{
to: 'recipient2@example.org',
subject: 'Hello recipient 2',
substitutions: {
name: 'Recipient 2',
id: '456',
},
headers: {
'X-Custom-Header': 'Recipient 2',
},
customArgs: {
myArg: 'Recipient 1',
},
sendAt: 1500077141,
}
],
from: 'sender@example.org',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
};
If the substitutions field is provided globally as well, these substitutions will be merged with any custom substitutions you provide in the personalizations.
Attachments can be sent by providing an array of attachments as per the API specifications:
const data = {
to: 'recipient@example.org',
from: 'sender@example.org',
subject: 'Hello attachment',
html: '<p>Here’s an attachment for you!</p>',
attachments: [
{
content: 'Some attachment content',
filename: 'some-attachment.txt',
},
],
};
Instead of using the text and html shorthand properties, you can manually use the content property:
const data = {
to: 'recipient@example.org',
from: 'sender@example.org',
subject: 'Hello manual content',
content: [
{
type: 'text/html',
value: '<p>Hello HTML world!</p>',
},
{
type: 'text/plain',
value: 'Hello plain world!',
},
],
};
Use the sendAt property to specify when to send the emails (in seconds, not milliseconds):
const data = {
to: 'recipient@example.org',
from: 'sender@example.org',
subject: 'Hello delayed email',
html: '<p>Some email content</p>',
sendAt: 1500077141,
};
Use the headers property to specify any custom headers:
const data = {
to: 'recipient@example.org',
from: 'sender@example.org',
subject: 'Hello custom header',
html: '<p>Some email content</p>',
headers: {
'X-CustomHeader': 'Custom header value',
},
};
Use the categories property to provide an array of categories for your email:
const data = {
to: 'recipient@example.org',
from: 'sender@example.org',
subject: 'Hello email with categories',
html: '<p>Some email content</p>',
categories: [
'transactional', 'customer', 'weekly',
],
};
Specifying a single category is also supported:
const data = {
to: 'recipient@example.org',
from: 'sender@example.org',
subject: 'Hello email with categories',
html: '<p>Some email content</p>',
category: 'transactional',
};
All other options from the API definition are supported:
const data = {
//Sections
sections: {},
//Custom arguments
customArgs: {},
//Batch ID
batchId: String,
//ASM
asm: {},
//IP pool name
ipPoolName: String,
//Mail settings
mailSettings: {},
//Tracking settings
trackingSettings: {},
};
An example with most settings used (note that some settings can be used in multiple ways, see above for full details for each setting):
//Load library
const sgMail = require('@sendgrid/mail');
//Set API key
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
//Create mail data
const data = {
to: 'recipient@example.org',
cc: 'someone@example.org',
bcc: ['me@example.org', 'you@example.org'],
from: 'sender@example.org',
replyTo: 'othersender@example.org',
subject: 'Hello world',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
templateId: 'sendgrid-template-id',
substitutionWrappers: ['{{', '}}'],
substitutions: {
name: 'Some One',
id: '123',
},
attachments: [
{
content: 'Some attachment content',
filename: 'some-attachment.txt',
},
],
categories: ['Transactional', 'My category'],
sendAt: 1500077141,
headers: {
'X-CustomHeader': 'Custom header value',
},
sections: {},
customArgs: {
myCustomArg: 123,
},
batchId: 'sendgrid-batch-id',
asm: {},
ipPoolName: 'sendgrid-ip-pool-name',
mailSettings: {},
trackingSettings: {},
};
//Send email and handle result
sgMail
.send(data)
.then(() => console.log('Mail sent successfully'))
.catch(error => console.error(error.toString()));
FAQs
Twilio SendGrid NodeJS mail service
The npm package @sendgrid/mail receives a total of 1,212,951 weekly downloads. As such, @sendgrid/mail popularity was classified as popular.
We found that @sendgrid/mail demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious Go packages are impersonating popular libraries to install hidden loader malware on Linux and macOS, targeting developers with obfuscated payloads.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.