Sendgrid service for Feathers
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github
example
src Removing JSHint directives Oct 21, 2016
test Removing JSHint directives Oct 21, 2016
.babelrc
.codeclimate.yml
.gitignore Adding coverage to .npmignore, Slack notifications / supported node v… Oct 26, 2016
.istanbul.yml Adding coverage to .npmignore, Slack notifications / supported node v… Oct 26, 2016
.npmignore Adding coverage to .npmignore, Slack notifications / supported node v… Oct 26, 2016
.travis.yml
CHANGELOG.md
LICENSE
README.md Adding coverage to .npmignore, Slack notifications / supported node v… Oct 26, 2016
mocha.opts
package.json

README.md

feathers-sendgrid

A SendGrid Service for FeatherJS.

Build Status Code Climate Test Coverage Dependency Status Download Status Slack Status

So far this only supports sending email. If you'd like additional functionality PRs are welcome! 😄

Installation

npm install feathers-sendgrid --save

Documentation

feathers-sendgrid is used just like any other service. In order to send an email simply call create with a payload that conforms to the Sendgrid V3 REST API. You can see an example payload here.

For usage with some of the bundled hooks see the example below.

Bundled Hooks

This module comes with a couple bundled hooks that make it a bit easier to send email. These are entirely optional.

Rendering Email Templates

This hook renders a specific email template based on your express view engine with your hook object. It is meant to be used as a before hook on the a create method.

const Handlebars = require('hbs');
const hooks = require('feathers-sendgrid').hooks;

app.service('mailer').before({
  create: [
    hooks.renderTemplate({ engine:  Handlebars })
  ]
});

function sendEmail(options = {}) {
  return function(hook) {
    return new Promise((resolve, reject) => {
      hooks.renderTemplate({template: 'welcome', engine: Handlebars })(hook)
        .then(hook => {
          const data = {
            from: 'hello@feathersjs.com',
            to: hook.result.email,
            subject: 'Welcome',
            content: hook.data.content
          };

          hook.app.service('mailer')
            .create(data, {template: 'welcome'})
            .then()
        })
    });
  };
}

app.service('users').after({
  create: [
    sendEmail()
  ]
});

Options

  • engine (required) - the view engine instance.
  • template (required) - the name of your template.
  • path [optional] - path to your email template directory. Defaults to your express view engine path + 'email' (ie. path/to/views/email/).

Validating Email Params

This hook validates that the following fields exist inside hook.data:

  • from
  • to or personalizations
  • subject
  • content

It is really loose validation since Sendgrid does it's own validation. This is more for ensuring that the absolute minimum fields are included in order to send an email.

const hooks = require('feathers-sendgrid').hooks;

app.service('mailer').before({
  create: [
    hooks.validateEmail()
  ]
});

Normalizing Email Params

This hook makes it a bit less tedious to send simple emails. It takes a simple flat format and turns it into the format that Sendgrid expects. It only effects the following fields in hook.data:

  • from
  • to
  • subject
  • content
const hooks = require('feathers-sendgrid').hooks;

app.service('mailer').before({
  create: [
    hooks.normalizeEmail()
  ]
});

Complete Example

Here's an example of a Feathers server with a mailer Sendgrid service.

import rest = from 'feathers-rest';
import hooks from 'feathers-hooks';
import feathers from 'feathers';
import bodyParser from 'body-parser';
import { MailService, hooks as mailerHooks } from 'feathers-sendgrid';

// Create a feathers instance.
var app = feathers()
  // Enable REST services
  .configure(rest())
  // Enable hooks
  .configure(hooks())
  // Turn on JSON parser for REST services
  .use(bodyParser.json())
  // Turn on URL-encoded parser for REST services
  .use(bodyParser.urlencoded({extended: true}));

// Register the Sendgrid service
app.use('/mailer', MailService({ apiKey: "YOUR_SENDGRID_API_KEY" }));

app.service('mailer').before({
  create: [mailerHooks.validateEmail(), mailerHooks.normalizeEmail()]
});

// Use the service
var email = {
   from: 'FROM_EMAIL',
   to: 'TO_EMAIL',
   subject: 'Sendgrid test',
   content: 'This is the email body'
};

app.service('mailer').create(email).then(function (result) {
  console.log('Sent email', result);
}).catch(err => {
  console.log(err);
});

// Start the server.
var port = 3030;
app.listen(port, function() {
  console.log(`Feathers server listening on port ${port}`);
});

You can run this example by using npm start. Make sure you've added your Sendgrid API token.

License

Copyright (c) 2016

Licensed under the MIT license.