Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ServerClient
✓ import { ServerClient } from 'postmark';
✗ const postmark = require('postmark'); const client = new postmark.Client('YOUR_API_TOKEN');
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.
AccountClient
✓ import { AccountClient } from 'postmark';
✗ const client = new postmark.AccountClient('YOUR_API_TOKEN');
Used for managing account-level Postmark resources. Requires an account API token, not a server token. Available since v2.
Models
✓ import type * as Models from 'postmark/dist/client/models';
Directly importing types for API request/response bodies from 'postmark/dist/client/models' provides robust type-checking for operations like `sendEmail` or `sendEmailWithTemplate`.
Demonstrates how to initialize the Postmark `ServerClient` and send a basic transactional email using environment variables for the API token.
import { ServerClient } from 'postmark';
const POSTMARK_SERVER_TOKEN = process.env.POSTMARK_SERVER_TOKEN ?? '';
if (!POSTMARK_SERVER_TOKEN) {
console.error('POSTMARK_SERVER_TOKEN environment variable is not set.');
process.exit(1);
}
const client = new ServerClient(POSTMARK_SERVER_TOKEN);
async function sendExampleEmail() {
try {
const response = await client.sendEmail({
From: 'sender@example.com',
To: 'recipient@example.com',
Subject: 'Hello from Postmark.js!',
TextBody: 'Hello, this is a test email sent using the official Postmark Node.js library!',
HtmlBody: '<html><body><strong>Hello</strong>, this is a test email sent using the official Postmark Node.js library!</body></html>',
MessageStream: 'outbound'
});
console.log('Email sent successfully:', response);
} catch (error) {
console.error('Failed to send email:', error);
if (error instanceof Error) {
console.error('Error message:', error.message);
}
}
}
sendExampleEmail();
Debug
Known issues
breakingVersion 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.fixUpgrade 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`).
affects: >=4.0.0
gotchaUsing 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.fixEnsure 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.
affects: >=2.0.0
gotchaWhen 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.fixAlways use the exact casing specified in the Postmark API documentation for email parameters (e.g., `From`, not `from`).
affects: >=1.0.0
breakingA 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.fixAlways 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.
affects: N/A (affected specific malicious package)
Errors
Common errors & fixes
TypeError: postmark.Client is not a constructor
Attempting to use `new postmark.Client()` with newer versions (v2+) of the library which have renamed the primary client class to `ServerClient` or `AccountClient`.
fixReplace `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. Error: "From" and "To" fields are required.
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.
fixEnsure 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.
Error: Not Found - The server token you provided was not found.
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.
fixVerify 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.
SyntaxError: Named export 'ServerClient' not found. The requested module 'postmark' is a CommonJS module, which may not support all module.exports as named exports.
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.
fixIf 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. Audit
Dependencies
axiosrequiredUsed as the underlying HTTP client for making API requests.