PostGrid

https://postgrid.readme.io/docs
Admin
PostGrid provides services for real-time address verification, autocompletion, and standardization,...
Tokens:85,623
Snippets:1,148
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install PostGrid Python SDK

Source: https://postgrid.readme.io/docs/using-our-python-sdk-1

Run this command in your terminal to install or upgrade the PostGrid Python library.

```bash
pip install --upgrade postgrid-python
```

--------------------------------

### Install Stripe.js via NPM

Source: https://postgrid.readme.io/docs/collecting-payment-details-from-sub-orgs-using-the-api

Install the Stripe.js library as a dependency in your project.

```shell
npm install @stripe/stripe-js
```

--------------------------------

### Complex Parameterized Query Example

Source: https://postgrid.readme.io/docs/enhanced-reports-1

A comprehensive example demonstrating filtering, type casting, and optional parameters in a single query.

```sql
SELECT
    status,
    COUNT(*) as count,
    COUNT(*) FILTER (WHERE express = true) as express_count
FROM letters
WHERE sendDate >= $start_date::DATE
  AND sendDate <= $end_date::DATE
  AND ($campaign IS NULL OR campaign = $campaign)
GROUP BY status
ORDER BY count DESC
```

--------------------------------

### Template search response example

Source: https://postgrid.readme.io/docs/creating-templates-using-the-api

Example JSON response structure returned when searching for templates.

```json
{
    "object": "list",
    "limit": 10,
    "skip": 0,
    "totalCount": 1,
    "data": [
        {
            "id": "template_suknWmGvcjFeQyW6iUsBou",
            "object": "template",
            "live": false,
            "description": "This is a test Template",
            "html": "\n<html>\n\t<body>\n\t\t<h1> Dear {{to.firstName}} </h1>\n\n\t\t<p> I hope that this letter finds you well. Here is the new policy ... </p>\n\n\t\t<p> Sincerely, </p>\n\t\t<p> {{from.firstName}} </p>\n\t\t<p> {{from.jobTitle}} </p>\n\t\t<p> {{from.companyName}} </p>\n\t</body>\n</html>\n",
            "createdAt": "2021-09-01T20:13:01.877Z",
            "updatedAt": "2021-09-01T20:13:01.877Z"
        }
    ]
}
```

--------------------------------

### Install node-fetch dependency

Source: https://postgrid.readme.io/docs/sending-letters-using-the-api

Install the required node-fetch module to enable API calls in a Node.js environment.

```bash
npm install node-fetch
```

--------------------------------

### Verify Structured Address Example

Source: https://postgrid.readme.io/docs/address-verification

Example usage of the verifyAddress function with a structured object. Providing a country code is recommended for optimal results.

```javascript
const testAddress = {
    line1: '145 Mulberry St',
    city: 'New York',
    provinceOrState: 'NY',
    country: 'US',
};

logAwait(verifyAddress(testAddress));
```

--------------------------------

### Sample order list response

Source: https://postgrid.readme.io/docs/tracking-orders-using-the-api

Example JSON response returned when fetching a list of orders.

```json
{
  "object": "list",
  "limit": 5,
  "skip": 10,
  "totalCount": 100,
  "data:" [
    {
      "id": "postcard_asdb8123hasd1l1As",
      "object": "postcard",
      "live": false,
      "backTemplate": "template_abc812839012381391",
      "description": "This is a test order for verifying statuses",
      "from": "contact_asd89123asdad9981",
      "frontTemplate": "template_asda1h23981njh123",
      "pageCount": 2,
      "sendDate": "2022-05-11T16:03:20.974Z",
      "size": "9x6",
      "status": "ready",
      "to": "contact_asdhksdldak91823lad",
      "url": "https://postgridpdf.url/adlakj1j298jljasdla",
      "createdAt": "2020-11-18T05:10:52.994Z",
      "updatedAt": "2020-11-18T05:10:52.994Z"
    }
  ],

}
```

--------------------------------

### GET /completions/preview

Source: https://postgrid.readme.io/docs/standard-address-verification-and-autocomplete

Retrieves a preview of autocompleted address suggestions.

```APIDOC
## GET /completions/preview

### Description
Returns an array of address previews for autocomplete suggestions.

### Method
GET

### Response
#### Success Response (200)
- **address** (string) - The first line of the autocompleted address
- **city** (string) - The city of the autocompleted address
- **pc** (string) - The first 3 digits of the postal/ZIP code of the autocompleted address
```

--------------------------------

### Webhook Creation Response

Source: https://postgrid.readme.io/docs/tracking-orders-using-the-api

Example JSON response returned after successfully creating a new webhook.

```json
{
  "id": "webhook_5z5e7KLCKiXn84okdzCiBg",
  "object": "webhook",
  "live": false,
  "enabled": true,
  "enabledEvents": [
      "letter.created"
  ],
  "payloadFormat": "jwt",
  "secret": "webhook_secret_a9ryNLNqv5FA2vTKTxJby7",
  "url": "https://myfancyurlformypostgridwebhook.com/listen-for-events",
  "createdAt": "2022-11-01T17:54:54.869Z",
  "updatedAt": "2022-11-01T17:54:54.869Z"
}
```

--------------------------------

### Retrieve Order List Response

Source: https://postgrid.readme.io/docs/tracking-orders-using-the-api

Example JSON response containing a list of orders.

```json
{
  "object": "list",
  "limit": 5,
  "skip": 10,
  "totalCount": 100,
  "data:" [
    {
      "id": "postcard_asdb8123hasd1l1As",
      "object": "postcard",
      "live": false,
      "backTemplate": "template_abc812839012381391",
      "description": "This is a test order for verifying statuses",
      "from": "contact_asd89123asdad9981",
      "frontTemplate": "template_asda1h23981njh123",
      "imbStatus": "entered_mail_stream",
      "pageCount": 2,
      "sendDate": "2022-05-11T16:03:20.974Z",
      "size": "9x6",
      "status": "processed_for_delivery",
      "to": "contact_asdhksdldak91823lad",
      "url": "https://postgridpdf.url/adlakj1j298jljasdla",
      "createdAt": "2020-11-18T05:10:52.994Z",
      "updatedAt": "2020-11-18T05:10:52.994Z"
    }
  ],

}
```

--------------------------------

### Example PostGrid-Signature Header

Source: https://postgrid.readme.io/docs/manually-verifying-webhook-signatures

The header contains a timestamp and a v1 signature hash used for manual verification.

```text
PostGrid-Signature: t=1718932335515,v1=e888f596cf2db26b2f58631cb28d620882022c5727a8f5a558f328f8d886e11d
```

--------------------------------

### Template Creation Response Example

Source: https://postgrid.readme.io/docs/creating-templates-using-the-api

The JSON structure returned by the API upon successful template creation.

```json
{
    "id": "template_suknWmGvcjFeQyW6iUsBou",
    "object": "template",
    "live": false,
    "description": "Test",
    "html": "<html>\n\t\t<body>\n\t\t\t<h1> Dear {{to.firstName}} </h1>\n\n\t\t\t<p> I hope that this letter finds you well. Here is the new policy ... </p>\n\n\t\t\t<p> Sincerely, </p>\n\t\t\t<p> {{from.firstName}} </p>\n\t\t\t<p> {{from.jobTitle}} </p>\n\t\t\t<p> {{from.companyName}} </p>\n\t\t</body>\n\t</html>",
    "createdAt": "2021-09-01T20:13:01.877Z",
    "updatedAt": "2021-09-01T20:13:01.877Z"
}
```

--------------------------------

### Address Verification Response Example

Source: https://postgrid.readme.io/docs/address-verification

Sample JSON response returned by the verification endpoint.

```json
{
    "status": "success",
    "message": "Address verification processed.",
    "data": {
        "city": "NEW YORK",
        "country": "us",
        "countryName": "UNITED STATES",
        "errors": {
            "line1": [
                "Missing Value: Suite identifier"
            ]
        },
        "line1": "145 MULBERRY ST",
        "postalOrZip": "10013",
        "provinceOrState": "NY",
        "status": "failed",
        "zipPlus4": "4766"
    }
}
```

--------------------------------

### Bank Account Response Object

Source: https://postgrid.readme.io/docs/sending-cheques-using-the-api-1

Example JSON response received after successfully creating a bank account.

```json
{
    "id": "bank_pRfyyrHpgQKW2Ptx2pZvsd",
    "object": "bank_account",
    "live": false,
    "accountNumberLast4": 4567,
    "bankCountryCode": "CA",
    "bankName": "CIBC",
    "bankPrimaryLine": "77 Bloor St W",
    "bankSecondaryLine": "",
    "description": "This bank account will be used to send cheques",
    "routeNumber": "010",
    "signatureText": "David",
    "transitNumber": 12345,
    "createdAt": "	2022-05-18T12:50:59.257Z",
    "updatedAt": "2022-05-18T12:50:59.257Z"
}
```

--------------------------------

### Template Update Response

Source: https://postgrid.readme.io/docs/creating-templates-using-the-api

Example JSON response returned after successfully updating a template.

```json
{
    "id": "template_suknWmGvcjFeQyW6iUsBou",
    "object": "template",
    "live": false,
    "description": "This is a test template",
    "html": "\n<html>\n\t<body>\n\t\t<h1> Dear {{to.firstName}} </h1>\n\n\t\t<p> I hope that this letter finds you well. Here is the new policy ... </p>\n\n\t\t<p> Sincerely, </p>\n\t\t<p> {{from.firstName}} </p>\n\t\t<p> {{from.jobTitle}} </p>\n\t\t<p> {{from.companyName}} </p>\n\t</body>\n</html>\n",
    "createdAt": "2021-09-03T16:24:20.275Z",
    "updatedAt": "2021-09-03T21:22:34.689Z"
}
```

--------------------------------

### Sample specific order response

Source: https://postgrid.readme.io/docs/tracking-orders-using-the-api

Example JSON response returned when fetching details for a single order.

```json
{
  "id": "postcard_asdb8123hasd1l1As",
  "object": "postcard",
  "live": false,
  "backTemplate": "template_abc812839012381391",
  "description": "This is a test order for verifying statuses",
  "from": "contact_asd89123asdad9981",
  "frontTemplate": "template_asda1h23981njh123",
  "pageCount": 2,
  "sendDate": "2022-05-11T16:03:20.974Z",
  "size": "9x6",
  "status": "ready",
  "to": "contact_asdhksdldak91823lad",
  "url": "https://postgridpdf.url/adlakj1j298jljasdla",
  "createdAt": "2020-11-18T05:10:52.994Z",
  "updatedAt": "2020-11-18T05:10:52.994Z"
}
```

--------------------------------

### Example API Response

Source: https://postgrid.readme.io/docs/sending-letters-using-the-api

Represents the structure of a successful list request response from the PostGrid API.

```json
{
    "object": "list",
    "limit": 10,
    "skip": 0,
    "totalCount": 0,
    "data": []
}
```

--------------------------------

### Retrieve Specific Order Response

Source: https://postgrid.readme.io/docs/tracking-orders-using-the-api

Example JSON response for a single order lookup.

```json
{
  "id": "postcard_asdb8123hasd1l1As",
  "object": "postcard",
  "live": false,
  "backTemplate": "template_abc812839012381391",
  "description": "This is a test order for verifying statuses",
  "from": "contact_asd89123asdad9981",
  "frontTemplate": "template_asda1h23981njh123",
  "imbStatus": "entered_mail_stream",
  "pageCount": 2,
  "sendDate": "2022-05-11T16:03:20.974Z",
  "size": "9x6",
  "status": "entered_mail_stream",
  "to": "contact_asdhksdldak91823lad",
  "url": "https://postgridpdf.url/adlakj1j298jljasdla",
  "createdAt": "2020-11-18T05:10:52.994Z",
  "updatedAt": "2020-11-18T05:10:52.994Z"
}
```

--------------------------------

### Postcard API Response Example

Source: https://postgrid.readme.io/docs/sending-postcards-using-the-api

JSON response returned after successfully creating a postcard from scratch.

```json
{
    "id":"postcard_kkifTGq3haagbBnfy4yPKg",
    "object":"postcard",
    "live":false,
    "size":"6x4",
    "express":false,
    "mailingClass":"first_class",
    "from":{
        "id":"contact_aPLaHaphgkPdUqVQyFWAHg",
        "object":"contact",
        "addressLine1":"47 DIETZ AVE S",
        "addressLine2":null,
        "addressStatus":"verified",
        "city":"WATERLOO",
        "companyName":"Solutions Technology Inc.",
        "country":"CANADA",
        "countryCode":"CA",
        "firstName":"John",
        "jobTitle":"Software Engineer",
        "lastName":"Adams",
        "postalOrZip":null,
        "provinceOrState":"ONTARIO"
    },
    "frontHTML":"Hello friend!",
    "backHTML":"Bye friend!",
    "sendDate":"2021-09-07T20:56:12.226Z",
    "status":"ready",
    "to":{
        "id":"contact_aPLaHaphgkPdUqVQyFWAHg",
        "object":"contact",
        "addressLine1":"47 DIETZ AVE S",
        "addressLine2":null,
        "addressStatus":"verified",
        "city":"WATERLOO",
        "companyName":"Solutions Technology Inc.",
        "country":"CANADA",
        "countryCode":"CA",
        "firstName":"John",
        "jobTitle":"Software Engineer",
        "lastName":"Adams",
        "postalOrZip":null,
        "provinceOrState":"ONTARIO"
    },
    "createdAt":"2021-09-07T20:56:12.229Z",
    "updatedAt":"2021-09-07T20:56:12.229Z"
}
```

--------------------------------

### Initialize API environment and helper functions

Source: https://postgrid.readme.io/docs/sending-letters-using-the-api

Set up the base URL, API key placeholder, and an asynchronous logging helper function for API responses.

```js
const fetch = require('node-fetch');

const POSTGRID_URL = 'https://api.postgrid.com/print-mail/v1';

const API_KEY = '' // Place your API key here

/**
 * @param {Promise<any>} x
 */
async function logAwait(x) {
    try {
        console.log(await x);
    } catch (e) {
        console.error(e);
    }
}
```

--------------------------------

### Initialize API Constants and Logging Helper

Source: https://postgrid.readme.io/docs/address-verification

Sets up the required node-fetch import, API endpoint constants, and an asynchronous wrapper for logging API responses.

```javascript
import fetch from 'node-fetch';

const POSTGRID_STANDARD_URL = 'https://api.postgrid.com/v1/addver';
const POSTGRID_INTL_URL = 'https://api.postgrid.com/v1/intl_addver';

const API_KEY = ''; // Your API key here

/**
 * @param {Promise<any>} x
 */
async function logAwait(x) {
    try {
        console.log(await x);
    } catch (e) {
        console.error(e);
    }
}
```

--------------------------------

### Initialize Stripe Client in Vanilla JS

Source: https://postgrid.readme.io/docs/collecting-payment-details-from-sub-orgs-using-the-api

Load the PostGrid Stripe service and retrieve the necessary session credentials for a sub-organization.

```javascript
import { loadPostGridStripe } from "./services";

const subOrgID = getSubOrgID(...);

const { stripeSetupSessionID, stripeSetupSessionClientSecret, pgStripe } =
  await loadPostgridStripe(subOrgID);
```

--------------------------------

### Postcard API response example

Source: https://postgrid.readme.io/docs/sending-postcards-using-the-api

Example JSON object returned by the API when successfully retrieving a postcard.

```json
{
    "id":"postcard_hX2CBfGfZLix34GdCeNVdA",
    "object":"postcard",
    "live":false,
    "description":"Activation code",
    "from":{
        "id":"contact_uYbXrhkRMbBwSJ77Ca2EYL",
        "object":"contact",
        "addressLine1":"200 UNIVERSITY AVE W",
        "addressLine2":"",
        "addressStatus":"verified",
        "city":"WATERLOO",
        "companyName":"PostGrid",
        "country":"CANADA",
        "countryCode":"CA",
        "description":"This contact will be used to send postcards.",
        "email":"nolan@postgrid.com",
        "firstName":"Nolan",
        "jobTitle":"Backend Customer Success Engineer",
        "phoneNumber":"",
        "postalOrZip":"N2L 3G1",
        "provinceOrState":"ON"
    },
    "mergeVariables":{
        "code":"xyz123",
        "to":{
            "companyName":"PostGrid"
            }
    },
    "size":"6x4",
    "express":true,
    "pageCount":2,
    "sendDate":"2022-05-17T14:07:04.940Z",
    "status":"ready",
    "frontTemplate":"template_8qSx8uRRPvugG8pSeaD6yW",
    "backTemplate":"template_iSoKNNNQUxxUoCmaQ1sACM",
    "to":{
        "id":"contact_bReKn6B2S3b5d7bpTYLcE8",
        "object":"contact",
        "addressLine1":"47 DIETZ AVE S",
        "addressLine2":null,
        "addressStatus":"verified",
        "city":"WATERLOO",
        "companyName":"Solutions Technology Inc.",
        "country":"CANADA",
        "countryCode":"CA",
        "firstName":"John",
        "jobTitle":"Software Engineer",
        "lastName":"Adams",
        "postalOrZip":null,
        "provinceOrState":"ONTARIO"
    },
    "url":"https://pg-prod-bucket-1.s3.amazonaws.com/test/postcard_hX2CBfGfZLix34GdCeNVdA.pdf?AWSAccessKeyId=AKIA5GFUILSULWTWCR64&Expires=1652812987&Signature=4yC%2BHB%2FHaE7e82KxlbXa44ZREiw%3D",
    "createdAt":"2022-05-17T14:07:04.944Z",
    "updatedAt":"2022-05-17T14:07:08.945Z"
}
```

--------------------------------

### Execute Address Verification Example

Source: https://postgrid.readme.io/docs/address-verification

Demonstrates calling the verifyAddress function with an address object and enabling both detail and proper case options.

```js
const testAddress = {
    line1: '145 Mulberry St Ph D',
    city: 'New York',
    provinceOrState: 'NY',
    country: 'US',
};

logAwait(verifyAddress(testAddress, true, true));
```

--------------------------------

### Verify Canadian Address String Example

Source: https://postgrid.readme.io/docs/address-verification

Example usage of the verifyAddress function using a freeform string for a Canadian address.

```javascript
const testStringAddress = '47 Dietz Ave S, Waterloo, ON';

logAwait(verifyAddress(testStringAddress));
```

--------------------------------

### API Response Examples

Source: https://postgrid.readme.io/docs/creating-contacts

Shows the JSON response structure for contact creation in test mode versus live mode.

```json
{
    "id": "contact_vG8h8EKBM5ZSfGBpCcSACd",
    "object": "contact",
    "live": false,
    "addressLine1": "3075 14TH AVE 212",
    "addressLine2": "",
    "addressStatus": "verified",
    "city": "MARKHAM",
    "country": "CANADA",
    "countryCode": "CA",
    "firstName": "John",
    "lastName": "Smith",
    "postalOrZip": "L3R0G9",
    "provinceOrState": "ON",
    "createdAt": "2021-09-07T15:22:13.956Z",
    "updatedAt": "2021-09-07T15:22:13.956Z"
}
```

```json
{
    "id": "contact_eakam7BFaxchRD65WsPgVG",
    "object": "contact",
    "live": true,
    "addressLine1": "200 UNIVERSITY AVE W",
    "addressLine2": "",
    "addressStatus": "corrected",
    "city": "WATERLOO",
    "country": "CANADA",
    "countryCode": "CA",
    "firstName": "John",
    "lastName": "Smith",
    "postalOrZip": "N2L 3G1",
    "provinceOrState": "ON",
    "createdAt": "2021-09-07T15:47:04.214Z",
    "updatedAt": "2021-09-07T15:47:04.214Z"
}
```

--------------------------------

### Template Editor Listener Implementation

Source: https://postgrid.readme.io/docs/template-editor-sessions

A complete HTML example showing how to embed the editor via iframe and listen for postMessage events from the editor origin.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Template Editor Listener Example</title>
  </head>
  <body>
    <h1>Template Editor Host Page</h1>

    <!-- Embedded Template Editor -->
    <iframe
      id="template-editor"
      src="https://editor.postgrid.com/session/SESSION_ID"
      width="100%"
      height="800"
      style="border: none;"
    ></iframe>

    <script>
      window.addEventListener("message", function (event) {
        // Always validate the origin
        if (event.origin !== "https://editor.postgrid.com") {
          return;
        }

        const data = event.data;

        if (!data || !data.type) {
          return;
        }

        switch (data.type) {
          case "template_saved":
            console.log("Template saved:", data.templateID);
            break;

          case "template_save_error":
            console.error(
              "Template save error:",
              data.templateID,
              data.error
            );
            break;
        }
      });
    </script>
  </body>
</html>
```

--------------------------------

### GET /bank_accounts

Source: https://postgrid.readme.io/docs/sending-cheques-using-the-api-1

Lists all bank accounts associated with the account.

```APIDOC
## GET /bank_accounts

### Description
Retrieves a list of all bank accounts.

### Method
GET

### Endpoint
/bank_accounts
```

--------------------------------

### Include PURL and QR Code in HTML Template

Source: https://postgrid.readme.io/docs/qr-code-purl-trackers

A complete HTML example demonstrating both PURL and QR code integration.

```html
<html>
  <!-- By using the Tracker's ID, a short URL will be generated in its place. -->
  <p>Visit our website at {{tracker_abcdefghijklmnopqrstuvwxyz}}</p> 
  <!-- 
		We can also use the Tracker's ID but access a `qrcode` field to generate a QR code.
		Here, a new data QR code data URL will be generated in its place.
	-->
  <p>Don&apos;t feel like typing out the URL? Scan the QR code below!</p>
  <img src="{{tracker_abcdefghijklmnopqrstuvwxyz.qrcode}}" />
</html>
```

--------------------------------

### GET /templates/:id

Source: https://postgrid.readme.io/docs/creating-templates-using-the-api

Retrieves a specific template by its unique identifier.

```APIDOC
## GET /templates/:id

### Description
Retrieves a template by its unique ID.

### Method
GET

### Endpoint
/templates/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the template.

### Response
#### Success Response (200)
- **id** (string) - Template ID
- **object** (string) - Object type
- **live** (boolean) - Live status
- **description** (string) - Template description
- **html** (string) - Template HTML content
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Last update timestamp
```

--------------------------------

### Load application file into Node.js REPL

Source: https://postgrid.readme.io/docs/sending-letters-using-the-api

Commands to load the app.js file into the Node.js REPL for interactive testing on different operating systems.

```bash
node -i -e "$(< app.js)"
```

```ps
node -i -e "$(type app.js)"
```

--------------------------------

### GET /v1/contacts

Source: https://postgrid.readme.io/docs/overview

Retrieve contacts filtered by a search query string.

```APIDOC
## GET /v1/contacts

### Description
Retrieve a list of contacts filtered by a specific search string.

### Method
GET

### Endpoint
/v1/contacts

### Parameters
#### Query Parameters
- **search** (string) - Optional - The search query string to filter contacts.
```

--------------------------------

### GET /letters/:id

Source: https://postgrid.readme.io/docs/sending-letters-using-the-api

Retrieves the details of a specific letter by its unique ID.

```APIDOC
## GET /letters/:id

### Description
Retrieves the full information for an individual letter using its unique ID.

### Method
GET

### Endpoint
/letters/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the letter to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the letter.
- **object** (string) - The object type (e.g., "letter").
- **status** (string) - The current status of the letter.
- **url** (string) - The URL to preview the letter.
- **createdAt** (string) - Timestamp of when the letter was created.

#### Response Example
{
    "id": "letter_cLW8gqY6iibzoHfjCAFAck",
    "object": "letter",
    "status": "ready",
    "url": "https://eksandbox.s3.amazonaws.com/test/letter_cLW8gqY6iibzoHfjCAFAck...",
    "createdAt": "2021-09-08T14:28:47.554Z"
}
```

--------------------------------

### GET /completions

Source: https://postgrid.readme.io/docs/standard-address-verification-and-autocomplete

Fetches address completions based on a partial street input.

```APIDOC
## GET /completions

### Description
Fetches address completions based on a partial street input. This endpoint does not consume lookups.

### Method
GET

### Endpoint
/completions

### Parameters
#### Query Parameters
- **partialStreet** (string) - Required - The partial street address to autocomplete.

### Response
#### Success Response (200)
- **status** (string) - Either 'success' or 'error'
- **message** (string) - Describes the result of the request
- **data** (object/array) - The response data.
```

--------------------------------

### Registering an Address Completion Callback

Source: https://postgrid.readme.io/docs/address-autocomplete

Example of registering a logging function to handle address completion events using the PostGrid API.

```html
<script>
    function logAddress(addr) {
        console.log(addr);
    }

    registerPostGridAddressCompletedCallback(logAddress);
</script>
```

--------------------------------

### Inspect table schema with SQL

Source: https://postgrid.readme.io/docs/enhanced-reports-1

Use the PRAGMA table_info command to retrieve column details for a specified table.

```sql
PRAGMA table_info('table_name');
```

```sql
PRAGMA table_info('letters');
```

--------------------------------

### GET /postcards

Source: https://postgrid.readme.io/docs/sending-postcards-using-the-api

Retrieves a list of postcards based on search criteria and pagination parameters.

```APIDOC
## GET /postcards

### Description
Retrieves a list of postcards. Supports pagination and searching by specific fields or arbitrary information in the metainfo field.

### Method
GET

### Endpoint
/postcards

### Parameters
#### Query Parameters
- **skip** (integer) - Optional - The number of records to skip (default: 0).
- **limit** (integer) - Optional - The maximum number of records to return (default: 10).
- **search** (string/object) - Optional - A string or object used to filter the results.

### Response
#### Success Response (200)
- **object** (string) - The type of object returned (e.g., "list").
- **limit** (integer) - The limit applied to the request.
- **skip** (integer) - The skip applied to the request.
- **totalCount** (integer) - The total number of results matching the search.
- **data** (array) - A list of postcard objects.

### Response Example
{
    "object": "list",
    "limit": 10,
    "skip": 0,
    "totalCount": 0,
    "data": []
}
```

--------------------------------

### GET /postcards/:id

Source: https://postgrid.readme.io/docs/sending-postcards-using-the-api

Retrieves the details of an individual postcard using its unique ID.

```APIDOC
## GET /postcards/:id

### Description
Retrieves the full details of a specific postcard by its unique ID.

### Method
GET

### Endpoint
/postcards/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the postcard.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the postcard.
- **object** (string) - The object type.
- **status** (string) - The current status of the postcard.
- **url** (string) - The URL to preview the postcard.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.

#### Response Example
{
    "id": "postcard_hX2CBfGfZLix34GdCeNVdA",
    "object": "postcard",
    "status": "ready",
    "url": "https://pg-prod-bucket-1.s3.amazonaws.com/test/postcard_hX2CBfGfZLix34GdCeNVdA.pdf",
    "createdAt": "2022-05-17T14:07:04.944Z",
    "updatedAt": "2022-05-17T14:07:08.945Z"
}
```

--------------------------------

### GET /cheques

Source: https://postgrid.readme.io/docs/sending-cheques-using-the-api-1

Retrieves a list of cheques. The results can be paginated using the skip parameter.

```APIDOC
## GET /cheques

### Description
Retrieves a list of cheques to analyze multiple records at once.

### Method
GET

### Endpoint
/cheques

### Parameters
#### Query Parameters
- **skip** (string) - Optional - The number of records to skip, defaults to 0.

### Response
#### Success Response (200)
- **object** (string) - The type of object returned (list).
- **limit** (number) - The limit of results returned.
- **skip** (number) - The number of records skipped.
- **totalCount** (number) - Total number of results in the search.
- **data** (array) - A list of cheque objects.

#### Response Example
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "cheque_dYwJ1uc428rg1pwzqcRirV",
      "object": "cheque",
      "status": "ready"
    }
  ]
}
```

--------------------------------

### GET /bank_accounts/:id

Source: https://postgrid.readme.io/docs/sending-cheques-using-the-api-1

Retrieves the details of a specific bank account by its unique identifier.

```APIDOC
## GET /bank_accounts/:id

### Description
Retrieves the details of a specific bank account using its unique ID.

### Method
GET

### Endpoint
/bank_accounts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the bank account.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the bank account.
- **object** (string) - The type of object (bank_account).
- **live** (boolean) - Whether the account is in live mode.
- **accountNumberLast4** (string) - The last 4 digits of the account number.
- **bankCountryCode** (string) - The country code of the bank.
- **bankName** (string) - The name of the bank.
- **bankPrimaryLine** (string) - The primary address line of the bank.
- **bankSecondaryLine** (string) - The secondary address line of the bank.
- **routeNumber** (string) - The routing number.
- **transitNumber** (string) - The transit number.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.

### Response Example
{
  "id": "bank_mycTFJcd2d5SHifVHidiwc",
  "object": "bank_account",
  "live": false,
  "accountNumberLast4": "3211",
  "bankCountryCode": "CA",
  "bankName": "Example Bank",
  "bankPrimaryLine": "100 Garden Street",
  "bankSecondaryLine": "Gananoque, ON K7G 1H9",
  "routeNumber": "678",
  "transitNumber": "12345",
  "createdAt": "2020-11-12T08:47:01.880Z",
  "updatedAt": "2020-11-12T08:47:01.880Z"
}
```

--------------------------------

### Configure PostGrid API Key

Source: https://postgrid.readme.io/docs/using-our-python-sdk-1

Import the library and set your API key retrieved from the PostGrid dashboard to authenticate your application.

```python
import postgrid

postgrid.pm_key = 'YOUR_API_KEY_HERE'
```

--------------------------------

### GET /templates

Source: https://postgrid.readme.io/docs/creating-templates-using-the-api

Searches for templates based on query parameters including search criteria.

```APIDOC
## GET /templates

### Description
Searches for templates using query parameters for pagination and search criteria.

### Method
GET

### Endpoint
/templates

### Parameters
#### Query Parameters
- **skip** (integer) - Optional - Number of records to skip
- **limit** (integer) - Optional - Maximum number of records to return
- **search** (string) - Optional - Search criteria string

### Response
#### Success Response (200)
- **object** (string) - Object type
- **limit** (integer) - Limit used
- **skip** (integer) - Skip used
- **totalCount** (integer) - Total number of matches
- **data** (array) - List of template objects
```

--------------------------------

### Define Template Data in JavaScript

Source: https://postgrid.readme.io/docs/creating-templates-using-the-api

Set up the HTML content and description variables required for the template creation request.

```js
// Replace this with the contents of an HTML file,
// below is only an example.
const templateHTML = `
<html>
	<body>
		<h1> Dear {{to.firstName}} </h1>

		<p> I hope that this letter finds you well. Here is the new policy ... </p>

		<p> Sincerely, </p>
		<p> {{from.firstName}} </p>
		<p> {{from.jobTitle}} </p>
		<p> {{from.companyName}} </p>
	</body>
</html>
`;

const templateDescription = 'This is a test Template' // Insert your description here
```

--------------------------------

### Search for templates

Source: https://postgrid.readme.io/docs/creating-templates-using-the-api

Performs a GET request to search for templates based on a search string.

```javascript
/**
 * @param {string} search
 */
async function searchTemplates(search) {
    const requestOptions = {
        method: 'GET',
        headers: {
            'x-api-key': API_KEY,
        },
    };

    const queryString = `?skip=0&limit=10&search=${search}`;

    const resp = await fetch(
        POSTGRID_URL + '/templates' + queryString,
        requestOptions
    );

    return await resp.json();
}
```

--------------------------------

### Retry Implementation with Axios

Source: https://postgrid.readme.io/docs/response-codes-and-retry-logic

A JavaScript example demonstrating exponential backoff, jitter, and idempotency key usage for creating letters.

```javascript
import axios from 'axios';
import { v4 as uuidv4 } from 'uuid';

// Retry schedule in milliseconds (~30 min total)
const retrySchedule = [30_000, 60_000, 120_000, 300_000, 900_000]; // 30s, 1m, 2m, 5m, 15m

function getJitteredDelay(baseDelay) {
  return Math.random() * baseDelay;
}

async function retryCreateLetterWithBackoffAndIdempotency() {
  const idempotencyKey = uuidv4();

  for (let attempt = 0; attempt < retrySchedule.length; attempt++) {
    try {
      const response = await axios.post(
        'https://api.postgrid.com/v1/letters',
        {
          // your body here
        },
        {
          headers: {
            'x-api-key': // <postgrid-api-key>,
            'Idempotency-Key': // <your-idempotency-key>,
            'Content-Type': 'application/json',
          },
        }
      );

      console.log('Letter created successfully!');
      return response.data;

    } catch (error) {
      const status = error?.response?.status;
      const isRetryable = [429, 503].includes(status);

      if (!isRetryable || attempt === retrySchedule.length - 1) {
        console.error('Letter creation failed permanently.');
        throw error;
      }

      const delay = getJitteredDelay(retrySchedule[attempt]);
      console.warn(`Attempt ${attempt + 1} failed (${status}). Retrying in ${Math.round(delay / 1000)}s...`);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}
```
Tokens:
Raw