This package has been deprecated

Author message:

This package has been deprecated in favour of the new official library @sendgrid/mail. See the npm or github page for more details.

sendgrid-mailer

1.2.2 • Public • Published

sendgrid-mailer

npm version node dependencies github issues

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

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Published

Version History

  • Version
    Downloads (Last 7 Days)
    • Published

Package Sidebar

Install

npm i sendgrid-mailer

Weekly Downloads

5

Version

1.2.2

License

MIT

Last publish

Collaborators

  • adamreisnz