Postgrid | Composio Docs

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

API Key

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.

Select App

Navigate to Postgrid.

Configure Auth Config Settings

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

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

1 from composio import Composio
2 
3 # Replace these with your actual values
4 postgrid_auth_config_id = "ac_YOUR_POSTGRID_CONFIG_ID" # Auth config ID created above
5 user_id = "0000-0000-0000"  # UUID from database/app
6 
7 composio = Composio()
8 
9 def 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 
27 connection_id = authenticate_toolkit(user_id, postgrid_auth_config_id)
28 
29 # You can verify the connection using:
30 connected_account = composio.connected_accounts.get(connection_id)
31 print(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

OpenAI (Python)

Anthropic (TypeScript)

Google (Python)

Vercel (TypeScript)

Python

1 from composio import Composio
2 from openai import OpenAI
3 import json
4 
5 openai = OpenAI()
6 composio = Composio()
7 
8 # User ID must be a valid UUID format
9 user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10 
11 tools = composio.tools.get(user_id=user_id, toolkits=["POSTGRID"])
12 
13 print("[!] Tools:")
14 print(json.dumps(tools))
15 
16 def invoke_llm(task = "What can you do?"):
17     completion = openai.chat.completions.create(
18         model="gpt-4o",
19         messages=[
20             {
21                 "role": "user",
22                 "content": task,  # Your task here!
23             },
24         ],
25         tools=tools,
26     )
27 
28     # Handle Result from tool call
29     result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30     print(f"[!] Completion: {completion}")
31     print(f"[!] Tool call result: {result}")
32 
33 invoke_llm()

Tool List

POSTGRID_CREATE_BANK_ACCOUNT

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

string

routingNumber

stringRequired

signatureImage

string

signatureText

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_CREATE_CONTACT

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

string

city

stringRequired

countryCode

stringRequired

string

firstName

stringRequired

lastName

stringRequired

metadata

object

organization

string

phoneNumber

string

postalOrZip

stringRequired

provinceOrState

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_CREATE_LETTER

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

string

express

boolean

from_address

objectRequired

html

string

mergeVariables

object

metadata

object

pdf

string

perforatedPage

integer

returnEnvelope

boolean

objectRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_CREATE_TEMPLATE

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

string

html

stringRequired

name

stringRequired

testRenderModel

object

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_CREATE_WEBHOOK

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

string

url

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_DELETE_BANK_ACCOUNT

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

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_DELETE_CONTACT

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

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_DELETE_TEMPLATE

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

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_DELETE_WEBHOOK

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

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_GET_BANK_ACCOUNT

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

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_GET_CONTACT

Tool Name: Get Contact

Description

Tool to retrieve a contact. use after obtaining the contact id to fetch its details.

Action Parameters

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_GET_LETTER

Tool Name: Get Letter

Description

Tool to retrieve a letter. use after you have the letter id to fetch its details.

Action Parameters

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_GET_TEMPLATE

Tool Name: Get Template

Description

Tool to retrieve a template. use when you have the template id and need its details.

Action Parameters

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_GET_WEBHOOK

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

stringRequired

Action Response

data

objectRequired

error

string

successful

booleanRequired

POSTGRID_LIST_BANK_ACCOUNTS

Tool Name: List Bank Accounts

Description

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

Action Parameters

after

string

before

string

limit

integer

status

string

Action Response

data

arrayRequired

error

string

next_cursor

string

object

stringRequired

previous_cursor

string

successful

booleanRequired

POSTGRID_LIST_CHEQUES

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

string

count

integer

from_date

string

status

string

to_date

string

Action Response

data

arrayRequired

error

string

object

stringRequired

string

successful

booleanRequired

POSTGRID_LIST_CONTACTS

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

after

string

contact_name

string

from_date

string

limit

integer

metadata

object

to_date

string

Action Response

data

arrayRequired

error

string

next_cursor

string

object

stringRequired

prev_cursor

string

successful

booleanRequired

total_count

integerRequired

POSTGRID_LIST_LETTERS

Tool Name: List Letters

Description

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

Action Parameters

after

string

before

string

date_from

string

date_to

string

limit

integer

status

string

Action Response

data

arrayRequired

error

string

next_url

string

object

stringRequired

previous_url

string

successful

booleanRequired

POSTGRID_LIST_POSTCARDS

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

string

from_date

string

limit

integer

metadata

object

skip

integer

status

string

to_date

string

Action Response

data

arrayRequired

error

string

limit

integerRequired

next_url

string

object

stringRequired

previous_url

string

skip

integerRequired

successful

booleanRequired

POSTGRID_LIST_SELF_MAILERS

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

count

integer

from_date

string

metadata

object

offset

integer

status

string

to_date

string

Action Response

count

integerRequired

data

arrayRequired

error

string

next_url

string

object

stringRequired

offset

integerRequired

previous_url

string

successful

booleanRequired

total_count

integerRequired

url

stringRequired

POSTGRID_LIST_TEMPLATES

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

integer

page

integer

type

string

Action Response

data

arrayRequired

error

string

POSTGRID_LIST_WEBHOOKS

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

event

string

limit

integer

page

integer

target_url

string

Action Response

data

objectRequired

error

string

successful

booleanRequired