Postmark Node.js Client Library

The library requires a minimum Node.js version of v18.0.0 because it relies on the native Fetch API and has no runtime dependencies.

Version Compatibility:

• Node 18–20: The Fetch API is available but may emit an ExperimentalWarning: The Fetch API is an experimental feature from the Node runtime.
• Node 21+: The global Fetch API is stable.
• Node < 18: You must use older versions of the library:
  • Use 4.x.x for Node versions between 14 and 18.
  • Use 3.x.x for Node versions < 14.

Install the postmark library using npm:

npm install postmark

The library uses Node's built-in fetch (undici), which does not automatically respect HTTP_PROXY, HTTPS_PROXY, or NO_PROXY environment variables. To run behind a corporate egress proxy, you must provide a custom fetch implementation via the fetch option in the ServerClient constructor. You can use an undici ProxyAgent for this purpose. This option can also be used to inject mock fetch implementations for testing.

import { ServerClient } from "postmark";
import { ProxyAgent } from "undici";

const dispatcher = new ProxyAgent("http://proxy.internal:8080");

const client = new ServerClient("server-token", {
    fetch: (input, init) => fetch(input, { ...init, dispatcher }),
});

Node's built-in fetch (undici) does not automatically respect HTTP_PROXY, HTTPS_PROXY, or NO_PROXY environment variables. To route Postmark requests through a corporate egress proxy or to customize the transport layer, you must provide a custom FetchImplementation via the Configuration object.

A FetchImplementation follows the standard fetch signature: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>

import { ClientOptions } from 'postmark';

// Example: Using a custom fetch implementation (e.g., one configured with a ProxyAgent)
const customFetch: ClientOptions.FetchImplementation = async (input, init) => {
  // Your custom proxy/transport logic here
  return fetch(input, init);
};

const config = new ClientOptions.Configuration(
  true, 
  undefined, 
  undefined, 
  customFetch
);

The ClientOptions.Configuration class allows you to customize the transport and connection settings for the Postmark client. This is particularly useful for setting custom timeouts, changing the request host, or routing traffic through a proxy.

Available configuration properties:

• useHttps: Boolean indicating whether to use HTTPS.
• requestHost: A custom string for the request host.
• timeout: A number representing the request timeout.
• fetch: A custom FetchImplementation to override the default fetch behavior (e.g., to support corporate proxies).

import { ClientOptions } from 'postmark';

const config = new ClientOptions.Configuration(
  true,           // useHttps
  'api.custom.com', // requestHost
  5000,           // timeout in ms
  customFetchFn   // fetch implementation
);

Use OutboundMessageTrackingFilteringParameters, OutboundMessageOpensFilteringParameters, or OutboundMessageClicksFilteringParameters to query tracking data. These classes allow deep filtering based on client information (name, company, family), operating system details (name, family, company), platform, and geographic location (country, region, city).

import { OutboundMessageOpensFilteringParameters } from 'postmark';

const params = new OutboundMessageOpensFilteringParameters(
  100, // count
  0,   // offset
  'user@example.com', // recipient
  'open-tag', // tag
  'Chrome', // client_name
  undefined, // client_company
  undefined, // client_family
  'Windows', // os_name
  'Windows', // os_family
  'Microsoft', // os_company
  'desktop', // platform
  'US', // country
  'California', // region
  'San Francisco', // city
  'outbound-stream' // messageStream
);

All error types thrown by the client are available via the Errors export. Use these to perform type-guarded error handling when catching exceptions from client methods.

import { Errors } from 'postmark';

try {
  await client.sendEmail(...);
} catch (error) {
  if (error instanceof Errors.SomeSpecificError) {
    // Handle specific error
  }
}

If you catch an InactiveRecipientsError, you can access the recipients property to get a list of the specific email addresses that were flagged as inactive by the Postmark API. The error automatically parses these addresses from the error message using internal regex patterns.

try {
  await postmarkClient.sendEmail(...);
} catch (error) {
  if (error instanceof InactiveRecipientsError) {
    console.log('The following recipients are inactive:', error.recipients);
    // error.recipients is a string[]
  }
}

Use InboundMessagesFilteringParameters to query inbound messages. Supports pagination via count and offset (defaulting to 100 and 0 respectively). Filtering options include mailboxHash, recipient, fromEmail, tag, status, fromDate, toDate, and subject.

import { InboundMessagesFilteringParameters, InboundMessageStatus } from 'postmark';

const params = new InboundMessagesFilteringParameters(
  10, // count
  0,  // offset
  'hash_abc123', // mailboxHash
  'recipient@example.com', // recipient
  undefined, // fromEmail
  'inbound-tag', // tag
  InboundMessageStatus.Processed, // status
  '2023-01-01', // fromDate
  undefined, // toDate
  undefined  // subject
);

Use OutboundMessagesFilteringParameters to query outbound messages. This class supports pagination via count and offset (defaulting to 100 and 0 respectively) and allows filtering by recipient, sender, tags, status, date ranges, subject, and message stream. It also supports arbitrary metadata filtering using keys prefixed with metadata_ via index signature access.

import { OutboundMessagesFilteringParameters, OutboundMessageStatus } from 'postmark';

const params = new OutboundMessagesFilteringParameters(
  50, // count
  0,  // offset
  'user@example.com', // recipient
  undefined, // fromEmail
  'welcome-tag', // tag
  OutboundMessageStatus.Sent, // status
  '2023-01-01', // fromDate
  '2023-12-31', // toDate
  'Hello World', // subject
  'outbound-stream' // messageStream
);

// You can also add custom metadata filters
params['metadata_custom_id'] = '12345';