Registry / communication / postgrid-node-client

postgrid-node-client

JSON →
library0.11.0jsnpmunverified

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.

npm install postgrid-node-client
INSTALL
IMPORT
SIG · POSTGRID-NODE-CLIE
P
postgrid-node-client
communicationjavascriptv0.11.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PostGrid
import { PostGrid } from 'postgrid-node-client';
import PostGrid from 'postgrid-node-client';
The PostGrid class is a named export, not a default export.
PostGrid
import { PostGrid } from 'postgrid-node-client';
const { PostGrid } = require('postgrid-node-client'); // or const PostGrid = require('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.

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();
Debug
Known issues
gotchaPostGrid 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 })`.
affects: >=0.1.0
deprecatedThe 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.
affects: >=0.1.0
breakingAs 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.
affects: >=0.1.0
Errors
Common errors & fixes
PostGrid API Error: Missing Mail API Key
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
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
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' })`.
Upgrade
Version history
0.11.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
postgrid-node-client — npm install postgrid-node-client · libregistry