Merge pull request #1144 from drew-gross/document-email-adapter

Document email adapter

README.md

@@ -187,6 +187,36 @@ The client keys used with Parse are no longer necessary with Parse Server. If yo
 * `loggerAdapter` - The default behavior/transport (File) can be changed by creating an adapter class (see [`LoggerAdapter.js`](https://github.com/ParsePlatform/parse-server/blob/master/src/Adapters/Logger/LoggerAdapter.js)).
 * `databaseAdapter` - The backing store can be changed by creating an adapter class (see `DatabaseAdapter.js`). Defaults to `MongoStorageAdapter`.
 
+##### Email verification and password reset
+
+Verifying user email addresses and enabling password reset via email requries an email adapter. As part of the `parse-server` package we provide an adapter for sending email through Mailgun. To use it, sign up for Mailgun, and add this to your initialization code:
+
+```js
+var server = ParseServer({
+  ...otherOptions,
+  // Enable email verification
+  verifyUserEmails: true,
+  // The public URL of your app.
+  // This will appear in the link that is used to verify email addresses and reset passwords.
+  publicServerURL: 'https://example.com',
+  // Your apps name. This will appear in the subject and body of the emails that are sent.
+  appName: 'Parse App',
+  // The email adapter
+  emailAdapter: {
+    module: 'parse-server-simple-mailgun-adapter',
+    options: {
+      // The address that your emails come from
+      fromAddress: 'parse@example.com',
+      // Your domain from mailgun.com
+      domain: 'example.com',
+      // Your API key from mailgun.com
+      apiKey: 'key-mykey',
+    }
+  }
+});
+
+You can also use other email adapters contributed by the community such as [parse-server-sendgrid-adapter](https://www.npmjs.com/package/parse-server-sendgrid-adapter).
+
 ### Using environment variables to configure Parse Server
 
 You may configure the Parse Server using environment variables:

package.json

@@ -37,6 +37,7 @@
     "parse-server-fs-adapter": "^1.0.0",
     "parse-server-gcs-adapter": "^1.0.0",
     "parse-server-s3-adapter": "^1.0.0",
+    "parse-server-simple-mailgun-adapter": "^1.0.0",
     "redis": "^2.5.0-1",
     "request": "^2.65.0",
     "tv4": "^1.2.7",

spec/index.spec.js

@@ -56,6 +56,7 @@ describe('server', () => {
       fileKey: 'test',
       verifyUserEmails: true,
       emailAdapter: MockEmailAdapterWithOptions({
+        fromAddress: 'parse@example.com',
         apiKey: 'k',
         domain: 'd',
       }),
@@ -80,6 +81,7 @@ describe('server', () => {
       emailAdapter: {
         class: MockEmailAdapterWithOptions,
         options: {
+          fromAddress: 'parse@example.com',
           apiKey: 'k',
           domain: 'd',
         }
@@ -103,8 +105,9 @@ describe('server', () => {
       fileKey: 'test',
       verifyUserEmails: true,
       emailAdapter: {
-        module: './Email/SimpleMailgunAdapter',
+        module: 'parse-server-simple-mailgun-adapter',
         options: {
+          fromAddress: 'parse@example.com',
           apiKey: 'k',
           domain: 'd',
         }
@@ -127,9 +130,9 @@ describe('server', () => {
       collectionPrefix: 'test_',
       fileKey: 'test',
       verifyUserEmails: true,
-      emailAdapter: './Email/SimpleMailgunAdapter',
+      emailAdapter: 'parse-server-simple-mailgun-adapter',
       publicServerURL: 'http://localhost:8378/1'
-    })).toThrow('SimpleMailgunAdapter requires an API Key and domain.');
+    })).toThrow('SimpleMailgunAdapter requires an API Key, domain, and fromAddress.');
     done();
   });
 
@@ -147,13 +150,13 @@ describe('server', () => {
       fileKey: 'test',
       verifyUserEmails: true,
       emailAdapter: {
-        module: './Email/SimpleMailgunAdapter',
+        module: 'parse-server-simple-mailgun-adapter',
         options: {
           domain: 'd',
         }
       },
       publicServerURL: 'http://localhost:8378/1'
-    })).toThrow('SimpleMailgunAdapter requires an API Key and domain.');
+    })).toThrow('SimpleMailgunAdapter requires an API Key, domain, and fromAddress.');
     done();
   });
 

src/Adapters/AdapterLoader.js

@@ -10,8 +10,12 @@ export function loadAdapter(adapter, defaultAdapter, options) {
     try {
       return adapter(options);
     } catch(e) {
+      if (e.name === 'TypeError') {
         var Adapter = adapter;
         return new Adapter(options);
+      } else {
+        throw e;
+      }
     }
   } else if (typeof adapter === "string") {
     adapter = require(adapter);
@@ -19,7 +23,6 @@ export function loadAdapter(adapter, defaultAdapter, options) {
     if (adapter.default) {
       adapter = adapter.default;
     }
-
     return loadAdapter(adapter, undefined, options);
   } else if (adapter.module) {
     return loadAdapter(adapter.module, undefined, adapter.options);

src/Adapters/Email/SimpleMailgunAdapter.js

@@ -1,32 +0,0 @@
-import Mailgun from 'mailgun-js';
-
-let SimpleMailgunAdapter = mailgunOptions => {
-	if (!mailgunOptions || !mailgunOptions.apiKey || !mailgunOptions.domain) {
-		throw 'SimpleMailgunAdapter requires an API Key and domain.';
-	}
-	let mailgun = Mailgun(mailgunOptions);
-
-	let sendMail = ({to, subject, text}) => {
-		let data = {
-			from: mailgunOptions.fromAddress,
-			to: to,
-			subject: subject,
-			text: text,
-		}
-
-		return new Promise((resolve, reject) => {
-			mailgun.messages().send(data, (err, body) => {
-				if (typeof err !== 'undefined') {
-					reject(err);
-				}
-				resolve(body);
-			});
-		});
-	}
-
-	return Object.freeze({
-    sendMail: sendMail
-	});
-}
-
-module.exports = SimpleMailgunAdapter

src/Controllers/UserController.js

@@ -181,7 +181,7 @@ export class UserController extends AdaptableController {
 
   defaultVerificationEmail({link, user, appName, }) {
     let text = "Hi,\n\n" +
-	      "You are being asked to confirm the e-mail address " + user.email + " with " + appName + "\n\n" +
+	      "You are being asked to confirm the e-mail address " + user.get("email") + " with " + appName + "\n\n" +
 	      "" +
 	      "Click here to confirm it:\n" + link;
     let to = user.get("email");

src/ParseServer.js

@@ -11,7 +11,6 @@ var batch = require('./batch'),
     Parse = require('parse/node').Parse,
     authDataManager = require('./authDataManager');
 
-//import passwordReset             from './passwordReset';
 import cache                    from './cache';
 import Config                   from './Config';
 import parseServerPackage       from '../package.json';

src/index.js

@@ -1,4 +1,4 @@
-import ParseServer            from './ParseServer'
+import ParseServer           from './ParseServer';
 import { GCSAdapter }        from 'parse-server-gcs-adapter';
 import { S3Adapter }         from 'parse-server-s3-adapter';
 import { FileSystemAdapter } from 'parse-server-fs-adapter';