Parse Server API Mail Adapter

Common errors

• Error: Node.js version 18.x.x is not supported by parse-server-api-mail-adapter@5.x.x

  cause Attempting to run the adapter version 5.x.x on an unsupported Node.js runtime (Node 18).
  fix Upgrade your Node.js environment to version 20, 22, or 24. For example, using NVM: `nvm install 20 && nvm use 20`.

• TypeError: Cannot read properties of undefined (reading 'client')

  cause The mail client (e.g., Mailgun client) or its configuration object (`api.mailgun.client`) is not correctly initialized or passed to the adapter options.
  fix Ensure `mailgun.js` or your chosen mail client is correctly imported, initialized with necessary API keys, and the resulting client instance is passed to the adapter configuration under `options.api.[providerName].client`.

• MailAdapter: email verification template not found at path: path/to/templates/email_verification.html

  cause The specified `pathHtml` or `pathPlainText` for an email template (like `emailVerification` or `passwordReset`) does not point to an existing file.
  fix Verify that the template files exist at the exact paths specified in the `templates` object within the `emailAdapter` configuration. Ensure file permissions allow the Parse Server process to read them.

• Error: Mailgun API call failed: 401 Unauthorized

  cause The API key or domain configured for the Mailgun provider is incorrect or invalid.
  fix Double-check your `MAILGUN_API_KEY` and `MAILGUN_DOMAIN` environment variables or hardcoded values in the adapter configuration against your Mailgun account details.

Warnings

• breaking Version 5.0.0 removed support for Node.js 18. Your Parse Server environment must be running Node.js 20, 22, or 24. Subsequent minor releases fix `package-lock.json` sync and correct engine specification, but the core Node.js requirement remains.
  Fix: Upgrade your Node.js runtime to version 20, 22, or 24. Update your `package.json` engines field accordingly and re-install dependencies.
• breaking Version 4.0.0 removed support for Node.js 14 and 16. Deployments on these older Node.js versions will fail or encounter unexpected behavior.
  Fix: Upgrade your Node.js runtime to version 18, 20, or 22 (for v4.x.x). For v5.x.x, Node.js 20, 22, or 24 is required.
• gotcha The repository was transferred to the Parse Platform Organization on May 15, 2022. Direct GitHub references or cloned repositories with outdated remotes will need to be updated.
  Fix: Update any direct GitHub links, git remotes, or package manager references (if directly pointing to the old repo) to `parse-community/parse-server-api-mail-adapter`.
• gotcha Security vulnerability fixes have been released in recent versions for underlying dependencies like `undici`, `tar`, `npm`, `lodash`, and `@babel/traverse`. Running older versions may expose your application to known vulnerabilities.
  Fix: Regularly update to the latest patch version (e.g., `npm install parse-server-api-mail-adapter@latest`) to ensure all known security patches for dependencies are applied.
• gotcha When configuring a custom API, ensure the `send` function correctly handles the expected payload and returns a Promise, as Parse Server relies on this contract for email delivery.
  Fix: Review the 'Custom API' section in the documentation. Implement the `send` function to accept `mail` and `options` objects and return a Promise that resolves upon successful sending.

Install

• npm install parse-server-api-mail-adapter npm
• yarn add parse-server-api-mail-adapter yarn
• pnpm add parse-server-api-mail-adapter pnpm

Imports

• ApiPayloadConverter
  wrong:

  const { ApiPayloadConverter } = require('parse-server-api-mail-adapter');

  correct:

  import { ApiPayloadConverter } from 'parse-server-api-mail-adapter';

  CommonJS `require` is shown in older documentation or examples, but ESM `import` is the recommended standard. Ensure Parse Server itself is configured for ESM if using top-level imports.
• ApiMailAdapter
  wrong:

  import { ApiMailAdapter } from 'parse-server-api-mail-adapter';

  correct:

  import ApiMailAdapter from 'parse-server-api-mail-adapter';

  While often used as a string module name in Parse Server config, if instantiating directly in Cloud Code or custom scripts, it's typically imported as a default export.
• MailAdapterOptions
  wrong:

  import { MailAdapterOptions } from 'parse-server-api-mail-adapter';

  correct:

  import type { MailAdapterOptions } from 'parse-server-api-mail-adapter';

  This is a TypeScript type import for defining the configuration options passed to the adapter.

Quickstart

Demonstrates how to configure `parse-server-api-mail-adapter` with Parse Server using environment variables for sensitive data and Mailgun as an example provider, including template paths.

import ParseServer from 'parse-server';
import Mailgun from 'mailgun.js';
import formData from 'form-data';

const mailgun = new Mailgun(formData);
const mailgunClient = mailgun.client({ username: 'api', key: process.env.MAILGUN_API_KEY ?? '' });
const mailgunDomain = process.env.MAILGUN_DOMAIN ?? 'your-mailgun-domain.com';

// Basic Parse Server setup
const server = new ParseServer({
    databaseURI: process.env.DATABASE_URI ?? 'mongodb://localhost:27017/dev',
    cloud: __dirname + '/cloud/main.js', // Or wherever your cloud code is
    appId: process.env.APP_ID ?? 'myAppId',
    masterKey: process.env.MASTER_KEY ?? 'myMasterKey',
    serverURL: process.env.SERVER_URL ?? 'http://localhost:1337/parse',
    publicServerURL: process.env.PUBLIC_SERVER_URL ?? 'http://localhost:1337/parse',

    // Configure the Mail Adapter
    emailAdapter: {
        module: 'parse-server-api-mail-adapter',
        options: {
            sender: process.env.MAIL_SENDER ?? 'noreply@example.com',
            templates: {
                passwordReset: {
                    subject: 'Reset Your Password',
                    pathPlainText: 'path/to/templates/password_reset.txt',
                    pathHtml: 'path/to/templates/password_reset.html'
                },
                emailVerification: {
                    subject: 'Verify Your Email',
                    pathPlainText: 'path/to/templates/email_verification.txt',
                    pathHtml: 'path/to/templates/email_verification.html'
                }
            },
            // Example for Mailgun provider
            api: {
                mailgun: {
                    domain: mailgunDomain,
                    client: mailgunClient,
                    options: {
                        // Custom options for Mailgun API calls
                    }
                }
            }
            // Other API providers like AWS SES, ZeptoMail or custom API would be configured here
        }
    }
});

// To run Parse Server (for example in index.js)
// const app = express();
// app.use('/parse', server.app);
// const port = process.env.PORT || 1337;
// app.listen(port, () => console.log(`Parse Server running on port ${port}.`));