{"id":15767,"library":"postgrid-node-client","title":"PostGrid Node.js Client","description":"The `postgrid-node-client` library provides a Node.js and TypeScript client for interacting with the PostGrid Business API, facilitating postal delivery services (Print-Mail) and address verification/autocomplete. Currently at version 0.11.0, this package offers a convenient, typed interface over PostGrid's dual REST API structure. A key differentiator is its robust handling of two distinct API keys required by PostGrid: one for Print-Mail and another for Address Verification, allowing developers to instantiate a single client that intelligently routes requests. While a specific release cadence isn't published, its pre-1.0 versioning implies active development. The client simplifies common tasks such as creating contacts, sending documents, and verifying addresses, abstracting away direct HTTP requests and JSON parsing, and supports webhook configuration for event notifications.","status":"active","version":"0.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/flexbase-eng/postgrid-node-client","tags":["javascript","postgrid.com","postal delivery","api","typescript"],"install":[{"cmd":"npm install postgrid-node-client","lang":"bash","label":"npm"},{"cmd":"yarn add postgrid-node-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add postgrid-node-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The PostGrid class is a named export, not a default export.","wrong":"import PostGrid from 'postgrid-node-client';","symbol":"PostGrid","correct":"import { PostGrid } from 'postgrid-node-client';"},{"note":"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.","wrong":"const { PostGrid } = require('postgrid-node-client');\n// or\nconst PostGrid = require('postgrid-node-client');","symbol":"PostGrid","correct":"import { PostGrid } from 'postgrid-node-client';"},{"note":"The second argument to the constructor is an optional object for webhook configuration.","symbol":"PostGrid constructor with webhook options","correct":"import { PostGrid } from 'postgrid-node-client';\nconst client = new PostGrid({ mail: 'key1', addr: 'key2' }, { webhookUrl: 'url', webhookSecret: 'secret' });"}],"quickstart":{"code":"import { PostGrid } from 'postgrid-node-client';\n\n// For demonstration, use environment variables for API keys.\n// In a real application, consider a secure configuration manager.\nconst mailApiKey = process.env.POSTGRID_MAIL_API_KEY ?? 'YOUR_MAIL_API_KEY';\nconst addrApiKey = process.env.POSTGRID_ADDR_API_KEY ?? 'YOUR_ADDR_API_KEY';\n\n// Instantiate the client with both Mail and Address Verification API keys.\n// It's not necessary to supply both if you only use one service.\nconst client = new PostGrid({\n  mail: mailApiKey,\n  addr: addrApiKey\n}, {\n  // Optional: Configure webhook details if your application processes PostGrid webhooks\n  webhookUrl: 'https://my.service.com/postgrid/callback',\n  webhookSecret: 'abc123456the-tall-brown-bear',\n  webhookEvents: ['letter.created', 'letter.updated']\n});\n\nasync function runExample() {\n  try {\n    console.log('Attempting to create a contact...');\n    const newContact = await client.contacts.create({\n      first_name: 'John',\n      last_name: 'Doe',\n      address: {\n        address_line1: '123 Main St',\n        city: 'Anytown',\n        state: 'CA',\n        zip: '90210',\n        country: 'US'\n      },\n      email: 'john.doe@example.com',\n      phone_number: '+15551234567'\n    });\n    console.log('Contact created successfully:', newContact.id);\n\n    // Example of Address Verification (requires addr API key)\n    console.log('\\nAttempting Address Verification...');\n    const verifiedAddress = await client.addresses.verify({\n      address_line1: '123 Main St',\n      city: 'Anytown',\n      state: 'CA',\n      zip: '90210',\n      country: 'US'\n    });\n    console.log('Address Verification result:', verifiedAddress.success ? 'Verified' : 'Failed');\n\n  } catch (error: any) {\n    console.error('Error interacting with PostGrid:', error.message);\n    if (error.response?.data) {\n      console.error('API Response Data:', error.response.data);\n    }\n  }\n}\n\nrunExample();","lang":"typescript","description":"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."},"warnings":[{"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 })`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=0.1.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.","message":"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+).","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the `mail` property in the constructor object is set with your Print-Mail API key: `new PostGrid({ mail: 'YOUR_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.","error":"PostGrid API Error: Missing Mail API Key"},{"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`).","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.","error":"TypeError: postgrid_node_client_1.PostGrid is not a constructor"},{"fix":"Ensure the `addr` property in the constructor object is set with your Address Verification API key: `new PostGrid({ addr: 'YOUR_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.","error":"PostGrid API Error: Missing Addr API Key"}],"ecosystem":"npm"}