{"id":16495,"library":"postmark","title":"Postmark Node.js Library","description":"The `postmark` package is the official Node.js client library for interacting with the Postmark HTTP API, facilitating robust email sending and parsing capabilities within Node.js applications. It provides high delivery rates, comprehensive bounce and spam processing, and detailed email statistics. The current stable version is 4.0.7, which has recently updated its underlying HTTP client (`axios`). The library sees frequent patch releases to keep dependencies current and make minor model adjustments, with major version increments typically aligned with Node.js End-of-Life (EOL) cycles. Its key differentiators include being an official, actively maintained client with full support for Postmark's REST API, including features for both sending transactional emails and parsing incoming emails.","status":"active","version":"4.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/ActiveCampaign/postmark.js","tags":["javascript","typescript"],"install":[{"cmd":"npm install postmark","lang":"bash","label":"npm"},{"cmd":"yarn add postmark","lang":"bash","label":"yarn"},{"cmd":"pnpm add postmark","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used as the underlying HTTP client for making API requests.","package":"axios","optional":false}],"imports":[{"note":"The primary class for interacting with the Postmark API for sending emails. `Client` was used in older versions, `ServerClient` is the current recommended class for server-level tokens. The library ships with TypeScript types.","wrong":"const postmark = require('postmark'); const client = new postmark.Client('YOUR_API_TOKEN');","symbol":"ServerClient","correct":"import { ServerClient } from 'postmark';"},{"note":"Used for managing account-level Postmark resources. Requires an account API token, not a server token. Available since v2.","wrong":"const client = new postmark.AccountClient('YOUR_API_TOKEN');","symbol":"AccountClient","correct":"import { AccountClient } from 'postmark';"},{"note":"Directly importing types for API request/response bodies from 'postmark/dist/client/models' provides robust type-checking for operations like `sendEmail` or `sendEmailWithTemplate`.","symbol":"Models","correct":"import type * as Models from 'postmark/dist/client/models';"}],"quickstart":{"code":"import { ServerClient } from 'postmark';\n\nconst POSTMARK_SERVER_TOKEN = process.env.POSTMARK_SERVER_TOKEN ?? '';\n\nif (!POSTMARK_SERVER_TOKEN) {\n console.error('POSTMARK_SERVER_TOKEN environment variable is not set.');\n process.exit(1);\n}\n\nconst client = new ServerClient(POSTMARK_SERVER_TOKEN);\n\nasync function sendExampleEmail() {\n try {\n const response = await client.sendEmail({\n From: 'sender@example.com',\n To: 'recipient@example.com',\n Subject: 'Hello from Postmark.js!',\n TextBody: 'Hello, this is a test email sent using the official Postmark Node.js library!',\n HtmlBody: 'Hello, this is a test email sent using the official Postmark Node.js library!',\n MessageStream: 'outbound'\n });\n console.log('Email sent successfully:', response);\n } catch (error) {\n console.error('Failed to send email:', error);\n if (error instanceof Error) {\n console.error('Error message:', error.message);\n }\n }\n}\n\nsendExampleEmail();","lang":"typescript","description":"Demonstrates how to initialize the Postmark `ServerClient` and send a basic transactional email using environment variables for the API token."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14.0.0 or higher. If upgrading Node.js is not possible, downgrade the `postmark` package to a 3.x.x version (e.g., `npm install postmark@^3`).","message":"Version 4.0.0 and above dropped support for Node.js versions older than 14.0.0. Applications running on Node.js < v14.0.0 must use `postmark` library version 3.x.x.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure you are instantiating the correct client class for your intended operation and providing the corresponding API token. Server tokens start with a dash-separated UUID, while Account tokens are typically longer, alphanumeric strings without dashes.","message":"Using the correct client (`ServerClient` vs `AccountClient`) and API token type is crucial. `ServerClient` is for sending emails and managing server-level resources, requiring a server API token. `AccountClient` is for managing Postmark account-level resources and requires an account API token.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always use the exact casing specified in the Postmark API documentation for email parameters (e.g., `From`, not `from`).","message":"When sending emails, properties such as `From`, `To`, `Subject`, `TextBody`, and `HtmlBody` are case-sensitive according to the Postmark API specification. Mismatched casing will result in API errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always verify the package name (`postmark`) when installing. If you suspect having installed a malicious package like `postmark-mcp`, immediately remove it, check email logs for suspicious activity, and rotate any credentials that might have been sent via email.","message":"A malicious `postmark-mcp` package was identified on npm, which was *not* the official Postmark library, but a typosquatting attempt. This package stole emails by secretly BCC'ing messages to an external server.","severity":"breaking","affected_versions":"N/A (affected specific malicious package)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Replace `new postmark.Client('YOUR_API_TOKEN')` with `new postmark.ServerClient('YOUR_API_TOKEN')` for server-level operations or `new postmark.AccountClient('YOUR_API_TOKEN')` for account-level operations.","cause":"Attempting to use `new postmark.Client()` with newer versions (v2+) of the library which have renamed the primary client class to `ServerClient` or `AccountClient`.","error":"TypeError: postmark.Client is not a constructor"},{"fix":"Ensure the email object passed to `sendEmail` or `sendEmailWithTemplate` includes `From: 'sender@example.com'` and `To: 'recipient@example.com'` with correct, valid email addresses and exact casing.","cause":"The `sendEmail` or `sendEmailWithTemplate` method was called without providing valid `From` and `To` email addresses in the message payload, or they were provided with incorrect casing.","error":"Error: \"From\" and \"To\" fields are required."},{"fix":"Verify that the API token used is a valid Postmark Server API Token, not an Account API Token, and that it is active in your Postmark account. Double-check for typos or leading/trailing spaces.","cause":"An invalid or expired Postmark API Server Token was provided during client initialization, or an Account API Token was used where a Server Token is expected.","error":"Error: Not Found - The server token you provided was not found."},{"fix":"If running in a CJS environment, use `const { ServerClient } = require('postmark');`. Ensure your project's `package.json` has `\"type\": \"module\"` for ESM, or use a bundler that handles module interoperability correctly.","cause":"Trying to use ESM `import { ServerClient } from 'postmark'` in a CommonJS (CJS) environment, or an older Node.js version that doesn't fully support ESM, when the package's `package.json` might be configured for ESM or dual-packaging.","error":"SyntaxError: Named export 'ServerClient' not found. The requested module 'postmark' is a CommonJS module, which may not support all module.exports as named exports."}],"ecosystem":"npm"}