@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 package is part of a monorepo, please see this README for details.
This is a dedicated service for interaction with the mail endpoint of the SendGrid v3 API.
To be notified when this package is updated, please subscribe to email notifications for releases and breaking changes.
Grab your API Key from the Twilio SendGrid UI.
Do not hardcode your Twilio SendGrid API Key into your code. Instead, use an environment variable or some other secure means of protecting your Twilio SendGrid API Key. Following is an example of using an environment variable.
Update the development environment with your SENDGRID_API_KEY, for example:
echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
echo "sendgrid.env" >> .gitignore
source ./sendgrid.env
The following recommended installation requires npm. If you are unfamiliar with npm, see the npm docs. Npm comes installed with Node.js since node version 0.8.x, therefore, you likely already have it.
npm install --save @sendgrid/mail
You may also use yarn to install.
yarn add @sendgrid/mail
Verify an email address or domain in the Sender Authentication tab. Without this you will receive a 403 Forbidden response when trying to send mail.
The following is the minimum needed code to send a simple email. Use this example, and modify the to and from variables:
For more complex use cases, please see USE_CASES.md.
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const msg = {
to: 'test@example.com',
from: 'test@example.com', // Use the email address or domain you verified above
subject: 'Sending with Twilio 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>',
};
//ES6
sgMail
.send(msg)
.then(() => {}, error => {
console.error(error);
if (error.response) {
console.error(error.response.body)
}
});
//ES8
(async () => {
try {
await sgMail.send(msg);
} catch (error) {
console.error(error);
if (error.response) {
console.error(error.response.body)
}
}
})();
After executing the above code, you should have an email in the inbox of the recipient. You can check the status of your email in the UI. Alternatively, we can post events to a URL of your choice using our Event Webhook. This gives you data about the events that occur as Twilio SendGrid processes your email.
Please see our troubleshooting guide for common library issues.
All updates to this library are documented in our CHANGELOG and releases. You may also subscribe to email release notifications for releases and breaking changes.
We encourage contribution to our libraries (you might even score some nifty swag), please see our CONTRIBUTING guide for details.
@sendgrid/mail is maintained and funded by Twilio SendGrid, Inc. The names and logos for @sendgrid/mail are trademarks of Twilio SendGrid, Inc.
If you need help installing or using the library, please check the Twilio SendGrid Support Help Center.
If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!
FAQs
Twilio SendGrid NodeJS mail service
The npm package @sendgrid/mail receives a total of 1,049,059 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.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.