moziff/sendgrid-mailer

A simple wrapper around the Sendgrid library to make sending emails easy again

sendgrid-mailer

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: '[email protected]',
  from: '[email protected]',
  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: '[email protected]',

  //Email address with name
  to: 'Some One <[email protected]>',

  //Object with name/email
  to: {
    name: 'Some One',
    email: '[email protected]',
  },

  //A Sendgrid Email instance
  to: new Email('[email protected]', 'Some One'),

  //Or an array of emails
  to: ['[email protected]', '[email protected]'],
};

You can provide a reply-to address:

const email = {
  replyTo: '[email protected]',
}

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: ['[email protected]', '[email protected]'],
  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: '[email protected]',
  from: '[email protected]',
  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 <[email protected]>');

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