PostGrid plugin

• An order spends money. letters.create, postcards.create and selfMailers.create print and post a physical item. There is no sandbox flag on the request: test mode is a property of the key.
• Idempotency. Order creation accepts an Idempotency-Key header, and PostGrid honours it for 24 hours. The plugin generates one per call; pass idempotencyKey in the input to reuse it so a retried request returns the original order instead of printing a second one.
• Cancelling. An order can be cancelled only while its status is ready. After that it is with the printer. For a send-as-soon-as-possible order that is roughly midnight Eastern on the following day.
• Tracking. Every order carries status, from ready through printing and processed_for_delivery to completed or cancelled. Live mail bound for the US also gains imbStatus, the USPS stage, plus imbDate and imbZIPCode.
• Paging is by offset. List routes take skip and limit and return totalCount; page while skip is below it by adding limit each time.
• Addresses are corrected. A created contact may come back with a different address than it was sent, and addressStatus says whether it was verified, corrected or failed. On an order, a to or from contact given with an id is sent as that id alone, so skipVerification and forceVerifiedStatus take effect only on an inline contact (address fields, no id).
• Webhooks. PostGrid can post delivery notifications to a URL you register in its dashboard, but this plugin does not handle inbound deliveries.

• 21 typed API operations

Setup

npm install corsair @corsair-dev/postgrid better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/postgrid better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/postgrid better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/postgrid better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { postgrid } from '@corsair-dev/postgrid';

export const corsair = createCorsair({
	plugins: [
		postgrid(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

postgrid()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'postgrid',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.postgrid.api.letters.list({ limit: 10 });

const tenant = corsair.withTenant('acme');
await tenant.postgrid.api.templates.create({ description: 'Welcome postcard', html: '<b>Hello</b> {{to.firstName}}!' });

What’s next