PostGrid Python Library

2.1.1 verified Mon Apr 27 auth: no python

The official Python library for the PostGrid API. Provides convenient access to the PostGrid print-and-mail and address verification APIs. Current version 2.1.1, actively maintained with monthly releases.

pip install postgrid-python

Common errors

error ModuleNotFoundError: No module named 'postgrid' ↓

cause Package not installed or installed as 'postgrid-python' instead of 'postgrid'.

fix

Run pip install postgrid-python and import as from postgrid import PostGridClient.

error AttributeError: module 'postgrid' has no attribute 'Client' ↓

cause In v2.x the client class is renamed to PostGridClient.

fix

Use from postgrid import PostGridClient and instantiate PostGridClient(api_key='...').

error postgrid.errors.PostGridError: 422 Unprocessable Entity ↓

cause Address verification failed due to invalid or incomplete address.

fix

Double-check the address fields (e.g., firstLine, city, provinceOrState, zipOrPostalCode). Use the address verification endpoint to debug.

error AttributeError: 'PostGridClient' object has no attribute 'letter' ↓

cause The client's resource access pattern changed in v2.0.0; resources are accessed via the client instance, not a direct attribute.

fix

Use client.letters.create(...) (plural resource name) instead of client.letter.create(...).

Warnings

breaking In v2.0.0, the entire API surface was redesigned. v1.x had different resource names and method signatures. ↓

fix Upgrade to v2.0.0+ and refactor to use the new client pattern. See migration guide at https://github.com/postgrid/postgrid-python/releases/tag/v2.0.0

gotcha API keys are passed to the client as `api_key` parameter, not `key` or `apikey`. ↓

fix Use `PostGridClient(api_key='...')` or set `POSTGRID_API_KEY` environment variable.

deprecated The `letter.create()` method's `merge_variables` parameter is deprecated in favor of `to` block fields. ↓

fix Pass merge variables directly inside the `to` address dictionary (e.g., `to={'firstLine': '...', 'mergeVariables': {...}}`)

gotcha Address verification returns 422 if the address is invalid, not 404. Some users expect a 404. ↓

fix Handle `postgrid.errors.PostGridError` with status 422, not 404.

Imports

PostGridClient

wrong

import postgrid
client = postgrid.Client()

correct

from postgrid import PostGridClient

In v2.x the client class is PostGridClient, not Client.

Quickstart

Verify an address using the PostGrid API with environment variable for API key.

import os
from postgrid import PostGridClient

client = PostGridClient(api_key=os.environ.get('POSTGRID_API_KEY', ''))

# Verify an address
try:
    result = client.addresses.verify(
        firstLine='123 Main St',
        city='New York',
        provinceOrState='NY',
        zipOrPostalCode='10001',
        country='US'
    )
    print(result.to_dict())
except Exception as e:
    print(f'Error: {e}')