Postmark Node.js Library

Common errors

• TypeError: postmark.Client is not a constructor

  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`.
  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.

• Error: "From" and "To" fields are required.

  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.
  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.

• Error: Not Found - The server token you provided was not found.

  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.
  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.

• SyntaxError: Named export 'ServerClient' not found. The requested module 'postmark' is a CommonJS module, which may not support all module.exports as named exports.

  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.
  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.

Warnings

• breaking 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.
  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`).
• gotcha 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.
  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.
• gotcha 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.
  Fix: Always use the exact casing specified in the Postmark API documentation for email parameters (e.g., `From`, not `from`).
• breaking 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.
  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.

Install

• npm install postmark npm
• yarn add postmark yarn
• pnpm add postmark pnpm

Imports

• ServerClient
  wrong:

  const postmark = require('postmark'); const client = new postmark.Client('YOUR_API_TOKEN');

  correct:

  import { ServerClient } from 'postmark';

  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
  wrong:

  const client = new postmark.AccountClient('YOUR_API_TOKEN');

  correct:

  import { AccountClient } from 'postmark';

  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`.

Quickstart

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();