npm promulgates marsupials
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    sendgrid-mailerpublic

    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

    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

    install

    npm i sendgrid-mailer

    Downloadslast 7 days

    274

    version

    1.2.2

    license

    MIT

    repository

    github.com

    last publish

    collaborators

    • avatar