parse-server-mailgun

parse-server-mailgun

Allows your Parse Server app to send template-based password reset and email verification through Mailgun. Just add your template files (plain text and html) to the email adapter's configuration.

Installation

npm install --save parse-server-mailgun

Configuration

As is the case with the default Mailgun adapter that comes with the Parse Server, you need to set a fromAddres, and the domain and apiKey provided by Mailgun. In addition, you also need to configure the templates you wish to use with the password reset and email verification emails:

const resolve = require('path').resolve;
// Note that the paths to the templates are absolute.
var server = ParseServer({
  ...otherOptions,
  // Enable email verification
  verifyUserEmails: true,
  emailAdapter: {
    module: 'parse-server-mailgun',
    options: {
      // The address that your emails come from
      fromAddress: '[e-mail]',
      // Your domain from mailgun.com
      domain: 'example.com',
      // Your API key from mailgun.com
      apiKey: 'key-mykey',
      // The template section
      templates: {
        passwordResetEmail: {
          subject: 'Reset your password',
          pathPlainText: resolve(__dirname, 'path/to/templates/password_reset_email.txt'),
          pathHtml: resolve(__dirname, 'path/to/templates/password_reset_email.html'),
          callback: (user) => { return { firstName: user.get('firstName') }}
          // Now you can use {{firstName}} in your templates
        },
        verificationEmail: {
          subject: 'Confirm your account',
          pathPlainText: resolve(__dirname, 'path/to/templates/verification_email.txt'),
          pathHtml: resolve(__dirname, 'path/to/templates/verification_email.html'),
          callback: (user) => { return { firstName: user.get('firstName') }}
          // Now you can use {{firstName}} in your templates
        },
        customEmailAlert: {
          subject: 'Confirm your account',
          pathPlainText: resolve(__dirname, 'path/to/templates/custom_alert.txt'),
          pathHtml: resolve(__dirname, 'path/to/templates/custom_alert.html'),
        }
      }
    }
  }
});

More templates

With a few lines of code, it's also possible to use the MailgunAdapter directly, so you can send any other template-based email, provided it has been configured as shown in the example configuration above.

// Get access to Parse Server's cache
// With ES2015 syntax:
const { AppCache } = require('parse-server/lib/cache');
// Or with old-school JS:
const AppCache = require('parse-server/lib/cache').AppCache;
// Get a reference to the MailgunAdapter
const MailgunAdapter = AppCache.get('yourAppId')['userController']['adapter'];
// Invoke the send method with an options object
MailgunAdapter.send(
  templateName: 'customEmailAlert'
  subject: 'Optional, an override of your configuration'
  fromAddress: 'Also optional, an override of the adapter's fromAddress'
  recipient: '[e-mail]'
  variables: { alert: 'New posts' } // {{alert}} will be compiled to 'New posts'
)

plain-text and html templates

You must provide at least a plain-text version for both the reset and verification emails. The html versions are optional.

Breaking changes since v2.0.0

The dependency on cheerio is removed. From now on, use Mustache-style variable syntax, e.g. {{variable}}, in your templates. If you're upgrading from 1.0.2, be sure to update your templates with the new syntax style!

Callback feature

As shown in the example configuration above, you can now add a callback in order to introduce some custom variables into the content. The relevant Parse.User object is conveniently passed as an argument. The callback should always return a plain object where the property names exactly match their template counterparts. Note: this only works for password reset and address verification emails.

Additional templates

It's also possible to add other templates to your adapter configuration

Sample templates and default variables

In the test directory, there are a few examples to get you started. By default, you can use the following variables in your template files:

• {{link}} - the reset or verification link provided by the Parse Server
• {{appName}} - as is defined in your Parse Server configuration object
• {{username}} - the Parse.User object's username property
• {{email}} - the Parse.User object's email property

Additional variables can be introduced by adding a callback.