sendgrid-mailer v1.2.2
sendgrid-mailer
DEPRECATED
This package is now deprecated in favour of the new official Sendgrid library @sendgrid/mail. This new library, which I've worked on in collaboration with Sendgrid, follows almost the exact same API as this package. As such, it will work as a drop-in replacement with only a few minor changes needed:
//Instead of:
const sendgrid = require('sendgrid-mailer');
//Use:
const sgMail = require('@sendgrid/mail');
//Instead of:
sendgrid.config(SENDGRID_API_KEY);
//Use:
sgMail.setApiKey(SENDGRID_API_KEY);
//Instead of:
sendgrid.send(emails);
//Use:
sgMail.send(emails);
//Or:
sgMail.sendMultiple(emails);
That's it! The structure of your emails data can remain unchanged. In addition, the new library supports all advanced API options as documented in the API v3 documentation as well.
Please use the new Sendgrid library going forward, as this package will no longer be maintained or supported.
Introduction
A simple wrapper around the official Sendgrid library to make sending emails easy again.
This wrapper is not meant as a full blown replacement of the official Sendgrid library. Instead, it is meant for those use cases where you just want to send one or more emails quickly with a few lines of code, without needing to use elaborate helper classes or remember the Sendgrid Request JSON structure by heart.
Installation
Use npm
or yarn
to install:
npm install sendgrid-mailer --save
yarn add sendgrid-mailer
Requirements
Written in ES6 for Node 6+, requires sendgrid as a peer dependency.
Usage
Configure mailer
Configure the API key somewhere once:
require('sendgrid-mailer').config(API_KEY);
Simplest example
//Load mailer and set API key (only needed once)
const mailer = require('sendgrid-mailer').config(API_KEY);
//Create email data
const email = {
to: 'a@example.org',
from: 'b@example.org',
subject: 'Hello world',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
};
//Send away
mailer.send(email); //Returns promise
Further details
The send
method returns a Promise
, so you can handle success and capture errors:
mailer.send(email)
.then(() => {
//Celebrate
})
.catch(error => {
//Do something with the error
});
It accepts both a single email or an array of emails (sent individually):
//Construct an array of emails
const emails = [email1, email2, email3];
//Send them all
mailer.send(emails);
It also accepts Sendgrid helper Mail
instances:
//Load helper class
const Mail = require('sendgrid').mail.Mail;
//Instantiate
const sgMail = new Mail();
//...compose email...
//Send using mailer
mailer.send(sgMail);
The to
and from
fields are flexible:
const email = {
//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',
},
//A Sendgrid Email instance
to: new Email('someone@example.org', 'Some One'),
//Or an array of emails
to: ['someone@example.org', 'else@example.org'],
};
You can provide a reply-to address:
const email = {
replyTo: 'no-reply@example.org',
}
You can provide a template ID and substitutions:
const email = {
templateId: 'sendgrid-template-id',
substitutions: {
'{{name}}': 'Some One',
'{{id}}': '123',
},
}
Or an array of substitutions if you have multiple recipients:
const email = {
templateId: 'sendgrid-template-id',
to: ['someone@example.org', 'else@example.org'],
substitutions: [
{
'{{name}}': 'Some One',
'{{id}}': '123',
},
{
'{{name}}': 'Else',
'{{id}}': '456',
},
],
}
If needed, you can get direct access to the underlying Sendgrid instance:
//Do stuff with the Sendgrid instance
const emptyRequest = mailer.sg.emptyRequest();
You can use the mailer to quickly create Sendgrid Mail
instances:
//Create email data
const email = {
to: 'someone@example.org',
from: 'else@example.org',
subject: 'Hello world',
text: 'Hello plain world!',
html: '<p>Hello HTML world!</p>',
};
//Create a Sendgrid `Mail` instance
const sgMail = mailer.createMail(email);
Or Email
identity instances:
//Create a Sendgrid `Email` instance
const sgEmail = mailer.createEmail('Some One <someone@example.org>');
Or even to create Sendgrid Request
instances so you can send them yourself for more control:
//Create a Sendgrid `Request` instance
const sgRequest = mailer.createRequest(email);
//Send it using the underlying API
mailer.sg.API(request);
Lastly, you can overwrite the promise implementation you want the mailer to use. Defaults to ES6 Promise
:
mailer.Promise = require('bluebird');
Contributing
Pull requests or suggestions for improvement welcome!
License
(MIT License)
Copyright 2016-2017, Adam Reis