PostGrid Node.js Client

Common errors

• PostGrid API Error: Missing Mail API Key

  cause Attempting to use a Print-Mail service endpoint (e.g., creating a letter or contact) without providing a valid `mail` API key during client instantiation.
  fix Ensure the `mail` property in the constructor object is set with your Print-Mail API key: `new PostGrid({ mail: 'YOUR_MAIL_API_KEY' })`.

• TypeError: postgrid_node_client_1.PostGrid is not a constructor

  cause This error typically occurs when attempting to import the `PostGrid` class using CommonJS `require()` syntax in an environment where the package is treated as an ES Module, or when using an incorrect named/default import.
  fix Use standard ES Module named import syntax: `import { PostGrid } from 'postgrid-node-client';` and ensure your Node.js project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• PostGrid API Error: Missing Addr API Key

  cause Attempting to use an Address Verification service endpoint (e.g., verifying an address) without providing a valid `addr` API key during client instantiation.
  fix Ensure the `addr` property in the constructor object is set with your Address Verification API key: `new PostGrid({ addr: 'YOUR_ADDR_API_KEY' })`.

Warnings

• gotcha PostGrid requires distinct API keys for its Print-Mail and Address Verification services. Ensure you use the correct key for the corresponding service when instantiating the client or making specific API calls. Using the wrong key for a service will result in an API error.
  Fix: Obtain both 'Mail API Key' from the Print-Mail Dashboard and 'Addr API Key' from the Address Verification Dashboard, and pass them correctly to the PostGrid constructor: `new PostGrid({ mail: mailKey, addr: addrKey })`.
• deprecated The PostGrid client supports a legacy constructor that takes only a single string argument (the Mail API key). This constructor limits functionality to only the Print-Mail service and does not support Address Verification or webhook configuration via the constructor.
  Fix: Use the object-based constructor `new PostGrid({ mail: '[Your Mail API Key]', addr: '[Your Addr API Key]' })` for full functionality and clarity, even if only using one service.
• breaking As the `postgrid-node-client` library is currently in a pre-1.0 version (0.11.0), minor version updates may introduce breaking changes without adhering to strict semantic versioning, which typically reserves breaking changes for major versions (e.g., v1.0.0+).
  Fix: Pin exact versions (e.g., `"postgrid-node-client": "0.11.0"`) or use tilde ranges (e.g., `"~0.11.0"`) rather than caret ranges (`"^0.11.0"`) to prevent unexpected breakage when new minor versions are released. Always review release notes when upgrading.

Install

• npm install postgrid-node-client npm
• yarn add postgrid-node-client yarn
• pnpm add postgrid-node-client pnpm

Imports

• PostGrid
  wrong:

  import PostGrid from 'postgrid-node-client';

  correct:

  import { PostGrid } from 'postgrid-node-client';

  The PostGrid class is a named export, not a default export.
• PostGrid
  wrong:

  const { PostGrid } = require('postgrid-node-client');
  // or
  const PostGrid = require('postgrid-node-client');

  correct:

  import { PostGrid } from 'postgrid-node-client';

  While older Node.js versions (>=10) are supported, the library is primarily designed for ESM usage as indicated by TypeScript types and README examples. CommonJS `require` might work with transpilation or specific build configurations, but native ESM import is recommended.
• PostGrid constructor with webhook options

  import { PostGrid } from 'postgrid-node-client';
  const client = new PostGrid({ mail: 'key1', addr: 'key2' }, { webhookUrl: 'url', webhookSecret: 'secret' });

  The second argument to the constructor is an optional object for webhook configuration.

Quickstart

This quickstart demonstrates how to instantiate the PostGrid client with both Mail and Address Verification API keys (retrieved from environment variables) and then perform basic operations: creating a contact and verifying an address. It also shows optional webhook configuration.

import { PostGrid } from 'postgrid-node-client';

// For demonstration, use environment variables for API keys.
// In a real application, consider a secure configuration manager.
const mailApiKey = process.env.POSTGRID_MAIL_API_KEY ?? 'YOUR_MAIL_API_KEY';
const addrApiKey = process.env.POSTGRID_ADDR_API_KEY ?? 'YOUR_ADDR_API_KEY';

// Instantiate the client with both Mail and Address Verification API keys.
// It's not necessary to supply both if you only use one service.
const client = new PostGrid({
  mail: mailApiKey,
  addr: addrApiKey
}, {
  // Optional: Configure webhook details if your application processes PostGrid webhooks
  webhookUrl: 'https://my.service.com/postgrid/callback',
  webhookSecret: 'abc123456the-tall-brown-bear',
  webhookEvents: ['letter.created', 'letter.updated']
});

async function runExample() {
  try {
    console.log('Attempting to create a contact...');
    const newContact = await client.contacts.create({
      first_name: 'John',
      last_name: 'Doe',
      address: {
        address_line1: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zip: '90210',
        country: 'US'
      },
      email: 'john.doe@example.com',
      phone_number: '+15551234567'
    });
    console.log('Contact created successfully:', newContact.id);

    // Example of Address Verification (requires addr API key)
    console.log('\nAttempting Address Verification...');
    const verifiedAddress = await client.addresses.verify({
      address_line1: '123 Main St',
      city: 'Anytown',
      state: 'CA',
      zip: '90210',
      country: 'US'
    });
    console.log('Address Verification result:', verifiedAddress.success ? 'Verified' : 'Failed');

  } catch (error: any) {
    console.error('Error interacting with PostGrid:', error.message);
    if (error.response?.data) {
      console.error('API Response Data:', error.response.data);
    }
  }
}

runExample();