{"id":11524,"library":"parse-server-api-mail-adapter","title":"Parse Server API Mail Adapter","description":"The `parse-server-api-mail-adapter` provides a universal email solution for Parse Server, enabling it to send emails via any third-party REST API. It supports dynamic templates, localization, and includes out-of-the-box integrations for services like AWS SES, Mailgun, and ZeptoMail, along with a custom API option. The current stable version is 5.0.5, with frequent maintenance releases for security updates and occasional minor/major releases for new features or Node.js version support. Its key differentiators include its extensibility to any REST API-based mail service, built-in templating, and full localization support, making it a flexible choice compared to adapters tied to specific providers. It ships with TypeScript definitions, enhancing developer experience for TypeScript users.","status":"active","version":"5.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/parse-community/parse-server-api-mail-adapter","tags":["javascript","parse","parse-server","mail-adapter","email-adapter","mail","email","typescript"],"install":[{"cmd":"npm install parse-server-api-mail-adapter","lang":"bash","label":"npm"},{"cmd":"yarn add parse-server-api-mail-adapter","lang":"bash","label":"yarn"},{"cmd":"pnpm add parse-server-api-mail-adapter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an adapter specifically designed to be integrated into Parse Server's `emailAdapter` configuration.","package":"parse-server","optional":false}],"imports":[{"note":"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.","wrong":"const { ApiPayloadConverter } = require('parse-server-api-mail-adapter');","symbol":"ApiPayloadConverter","correct":"import { ApiPayloadConverter } from 'parse-server-api-mail-adapter';"},{"note":"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.","wrong":"import { ApiMailAdapter } from 'parse-server-api-mail-adapter';","symbol":"ApiMailAdapter","correct":"import ApiMailAdapter from 'parse-server-api-mail-adapter';"},{"note":"This is a TypeScript type import for defining the configuration options passed to the adapter.","wrong":"import { MailAdapterOptions } from 'parse-server-api-mail-adapter';","symbol":"MailAdapterOptions","correct":"import type { MailAdapterOptions } from 'parse-server-api-mail-adapter';"}],"quickstart":{"code":"import ParseServer from 'parse-server';\nimport Mailgun from 'mailgun.js';\nimport formData from 'form-data';\n\nconst mailgun = new Mailgun(formData);\nconst mailgunClient = mailgun.client({ username: 'api', key: process.env.MAILGUN_API_KEY ?? '' });\nconst mailgunDomain = process.env.MAILGUN_DOMAIN ?? 'your-mailgun-domain.com';\n\n// Basic Parse Server setup\nconst server = new ParseServer({\n    databaseURI: process.env.DATABASE_URI ?? 'mongodb://localhost:27017/dev',\n    cloud: __dirname + '/cloud/main.js', // Or wherever your cloud code is\n    appId: process.env.APP_ID ?? 'myAppId',\n    masterKey: process.env.MASTER_KEY ?? 'myMasterKey',\n    serverURL: process.env.SERVER_URL ?? 'http://localhost:1337/parse',\n    publicServerURL: process.env.PUBLIC_SERVER_URL ?? 'http://localhost:1337/parse',\n\n    // Configure the Mail Adapter\n    emailAdapter: {\n        module: 'parse-server-api-mail-adapter',\n        options: {\n            sender: process.env.MAIL_SENDER ?? 'noreply@example.com',\n            templates: {\n                passwordReset: {\n                    subject: 'Reset Your Password',\n                    pathPlainText: 'path/to/templates/password_reset.txt',\n                    pathHtml: 'path/to/templates/password_reset.html'\n                },\n                emailVerification: {\n                    subject: 'Verify Your Email',\n                    pathPlainText: 'path/to/templates/email_verification.txt',\n                    pathHtml: 'path/to/templates/email_verification.html'\n                }\n            },\n            // Example for Mailgun provider\n            api: {\n                mailgun: {\n                    domain: mailgunDomain,\n                    client: mailgunClient,\n                    options: {\n                        // Custom options for Mailgun API calls\n                    }\n                }\n            }\n            // Other API providers like AWS SES, ZeptoMail or custom API would be configured here\n        }\n    }\n});\n\n// To run Parse Server (for example in index.js)\n// const app = express();\n// app.use('/parse', server.app);\n// const port = process.env.PORT || 1337;\n// app.listen(port, () => console.log(`Parse Server running on port ${port}.`));\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 20, 22, or 24. Update your `package.json` engines field accordingly and re-install dependencies.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0 <5.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<=3.x.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<5.0.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 20, 22, or 24. For example, using NVM: `nvm install 20 && nvm use 20`.","cause":"Attempting to run the adapter version 5.x.x on an unsupported Node.js runtime (Node 18).","error":"Error: Node.js version 18.x.x is not supported by parse-server-api-mail-adapter@5.x.x"},{"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`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'client')"},{"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.","cause":"The specified `pathHtml` or `pathPlainText` for an email template (like `emailVerification` or `passwordReset`) does not point to an existing file.","error":"MailAdapter: email verification template not found at path: path/to/templates/email_verification.html"},{"fix":"Double-check your `MAILGUN_API_KEY` and `MAILGUN_DOMAIN` environment variables or hardcoded values in the adapter configuration against your Mailgun account details.","cause":"The API key or domain configured for the Mailgun provider is incorrect or invalid.","error":"Error: Mailgun API call failed: 401 Unauthorized"}],"ecosystem":"npm"}