Direct Mail Automation

Postgrid

Learn how to use Postgrid with Composio

Overview

SLUG: POSTGRID

Description

PostGrid provides APIs for automating direct mail and address verification services, enabling businesses to send letters, postcards, and checks, as well as verify and standardize addresses in real-time.

Authentication Details

generic_api_key
stringRequired

Connecting to Postgrid

Create an auth config

Use the dashboard to create an auth config for the Postgrid toolkit. This allows you to connect multiple Postgrid accounts to Composio for agents to use.

1

Select App

Navigate to Postgrid.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Postgrid Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4postgrid_auth_config_id = "ac_YOUR_POSTGRID_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000"  # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10    # Replace this with a method to retrieve an API key from the user.
11    # Or supply your own.
12    user_api_key = input("[!] Enter API key")
13
14    connection_request = composio.connected_accounts.initiate(
15        user_id=user_id,
16        auth_config_id=auth_config_id,
17        config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18    )
19
20    # API Key authentication is immediate - no redirect needed
21    print(f"Successfully connected Postgrid for user {user_id}")
22    print(f"Connection status: {connection_request.status}")
23    
24    return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, postgrid_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Postgrid toolkit’s playground

For code examples, see the Tool calling guide and Provider examples.

Tool List

Tool Name: CREATE_BANK_ACCOUNT

Description

Tool to create a new bank account for print & mail service.

Action Parameters

accountHolderName
stringRequired
accountNumber
stringRequired
accountType
stringRequired
bankCountryCode
stringRequired
bankName
stringRequired
contactEmail
stringRequired
contactPhone
routingNumber
stringRequired
signatureImage
signatureText

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create Contact

Description

Tool to create a new contact in PostGrid. Use after collecting contact's name, address, and optional metadata.

Action Parameters

addressLine1
stringRequired
addressLine2
city
stringRequired
countryCode
stringRequired
email
firstName
stringRequired
lastName
stringRequired
metadata
organization
phoneNumber
postalOrZip
stringRequired
provinceOrState
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create Letter

Description

Tool to create and send a letter via PostGrid. Use when recipient, sender, and content details are ready.

Action Parameters

description
express
from_address
objectRequired
html
mergeVariables
metadata
pdf
perforatedPage
returnEnvelope
to
objectRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create Template

Description

Tool to create a new mail template in PostGrid. Use when you need to define reusable HTML content with dynamic placeholders. Use after confirming required template details.

Action Parameters

description
html
stringRequired
name
stringRequired
testRenderModel

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create Webhook

Description

Tool to create a new webhook to receive order event notifications. Use after configuring your endpoint to handle webhook payloads.

Action Parameters

enabledEvents
arrayRequired
payloadFormat
url
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Delete Bank Account

Description

Tool to delete a bank account by its ID. Use when you need to remove a bank account after confirming its identifier.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Delete Contact

Description

Tool to delete a contact by its ID. Use when you need to remove obsolete contacts after confirming their identifier.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Delete Template

Description

Tool to delete a template by its ID. Use when you need to remove an existing template after confirming its identifier.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Delete Webhook

Description

Tool to delete a webhook subscription. Use when you need to remove an existing webhook by its ID.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get Bank Account

Description

Tool to retrieve a bank account. Use after obtaining the bank account ID to fetch its details.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get Contact

Description

Tool to retrieve a contact. Use after obtaining the contact ID to fetch its details.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get Letter

Description

Tool to retrieve a letter. Use after you have the letter ID to fetch its details.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get Template

Description

Tool to retrieve a template. Use when you have the template ID and need its details.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get Webhook

Description

Tool to retrieve details of a specific webhook by its ID. Use after creating a webhook to fetch its configuration and status.

Action Parameters

id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: List Bank Accounts

Description

Tool to list bank accounts. Use when retrieving bank accounts with optional status filter and pagination.

Action Parameters

limit
skip

Action Response

data
arrayRequired
error
limit
object
stringRequired
skip
successful
booleanRequired
totalCount

Tool Name: List Cheques

Description

Tool to list cheques with optional filters and pagination. Use when you need to retrieve batches of cheque records for processing or reporting.

Action Parameters

after
count
from_date
status
to_date

Action Response

data
arrayRequired
error
next
object
stringRequired
previous
successful
booleanRequired

Tool Name: List Contacts

Description

Tool to list contacts. Use when you need to retrieve a paginated list of contacts with optional filters like date range, metadata, name, or email.

Action Parameters

limit
search
skip

Action Response

data
arrayRequired
error
limit
integerRequired
object
stringRequired
skip
integerRequired
successful
booleanRequired
totalCount
integerRequired

Tool Name: List Letters

Description

Tool to list letters. Use when retrieving letters with optional filters and pagination.

Action Parameters

after
before
date_from
date_to
limit
status

Action Response

data
arrayRequired
error
limit
next_url
object
stringRequired
previous_url
skip
successful
booleanRequired
totalCount

Tool Name: List Postcards

Description

Tool to retrieve a list of postcards with optional filtering and pagination. Use when you need to browse or filter postcards list.

Action Parameters

contact_id
from_date
limit
metadata
skip
status
to_date

Action Response

data
arrayRequired
error
limit
integerRequired
next_url
object
stringRequired
previous_url
skip
integerRequired
successful
booleanRequired

Tool Name: List Self-Mailers

Description

Tool to list self-mailers. Use when you need to fetch self-mailers with filters and pagination.

Action Parameters

from_date
limit
metadata
skip
status
to_date

Action Response

data
arrayRequired
error
limit
integerRequired
object
stringRequired
skip
integerRequired
successful
booleanRequired
totalCount
integerRequired

Tool Name: List Templates

Description

Tool to list templates. Use when you need to retrieve a paginated list of templates with optional type filtering.

Action Parameters

limit
skip

Action Response

data
arrayRequired
error
limit
integerRequired
object
stringRequired
skip
integerRequired
successful
booleanRequired
totalCount
integerRequired

Tool Name: List Webhooks

Description

Tool to retrieve a list of configured webhooks with optional filtering and pagination. Use when you need to view your webhooks.

Action Parameters

limit
skip

Action Response

data
arrayRequired
error
limit
integerRequired
object
stringRequired
skip
integerRequired
successful
booleanRequired
totalCount
integerRequired