# Postgrid — how to use (mcp.ai)

Connect your Postgrid account and use 60 tools for developer tools straight from your AI agent. Connect with your own API key. 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.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_postgrid?ms=1787295780000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `postgrid_cancel_box`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/postgrid`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/postgrid/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/postgrid/cancel/box` — Tool to cancel a box order by its ID. Use when you need to cancel a pending box shipment.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/cancel/cheque` — Tool to cancel a cheque order by its ID. Only works when the cheque has 'ready' status. Use when you need to cancel a pending cheque before it is mailed.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/cancel/cheque/with/note` — Tool to cancel a cheque order with a cancellation note. Use when you need to cancel a cheque and provide a reason for the cancellation.
  - body: { id: string, note: string }
- `POST https://api.mcp.ai/api/postgrid/cancel/postcard` — Tool to cancel a postcard order. Use when you need to cancel a postcard that has status 'ready'.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/cancel/postcard/with/note` — Tool to cancel a postcard order with an optional cancellation note. Use when you need to cancel a postcard that is in 'ready' status. Once cancelled, the status changes to 'cancelled' and the response
  - body: { id: string, note: string }
- `POST https://api.mcp.ai/api/postgrid/cancel/return/envelope/order` — Tool to cancel a return envelope order. Use when you need to cancel a pending return envelope order using the return envelope ID and order ID.
  - body: { id: string, orderId: string }
- `POST https://api.mcp.ai/api/postgrid/create/bank/account` — Tool to create a new bank account for print & mail service.
  - body: { bankName: string, accountType: string, contactEmail: string, contactPhone?: string, accountNumber: string, routingNumber: string, signatureText?: string, signatureImage?: string, bankCountryCode: string, accountHolderName: string }
- `POST https://api.mcp.ai/api/postgrid/create/box` — Tool to create a box mailing order for letters with plastic cards or cheques. Use when you need to send multiple cheques in a secure box.
  - body: { to: string|object, from: string|object, cheques: object[], mailingClass?: string }
- `POST https://api.mcp.ai/api/postgrid/create/cheque` — Tool to create a cheque order for physical cheque mailing. Use when you need to send a payment via printed cheque. Requires a valid bank account ID and recipient contact details.
  - body: { to: object, memo?: string, amount: integer, number?: integer, message?: string, metadata?: object, sendDate?: string, bankAccount: string, fromAddress: object, extraService?: string, mailingClass?: string }
- `POST https://api.mcp.ai/api/postgrid/create/contact` — Tool to create a new contact in PostGrid. Use after collecting contact's name, address, and optional metadata.
  - body: { city: string, email?: string, lastName: string, metadata?: object, firstName: string, countryCode: string, phoneNumber?: string, postalOrZip: string, addressLine1: string, addressLine2?: string, organization?: string, provinceOrState: string }
- `POST https://api.mcp.ai/api/postgrid/create/letter` — Tool to create and send a letter via PostGrid. Use when recipient, sender, and content details are ready.
  - body: { to: object, pdf?: string, html?: string, express?: boolean, metadata?: object, description?: string, fromAddress: object, mergeVariables?: object, perforatedPage?: integer, returnEnvelope?: string }
- `POST https://api.mcp.ai/api/postgrid/create/postcard` — Tool to create and send a postcard via PostGrid. Use when recipient, sender, and content (HTML, template, or PDF) are ready.
  - body: { to: object, pdf?: string, from: object, size?: string, backHTML?: string, metadata?: object, sendDate?: string, frontHTML?: string, backTemplate?: string, mailingClass?: string, frontTemplate?: string, mergeVariables?: object }
- `POST https://api.mcp.ai/api/postgrid/create/return/envelope` — Tool to create a return envelope for mail recipients to respond. Use when you need to include a prepaid return envelope for recipients to send back responses.
  - body: { to: object, description?: string }
- `POST https://api.mcp.ai/api/postgrid/create/return/envelope/order` — Tool to create a batch order of return envelopes to be printed and delivered. Use when you need to order return envelopes in bulk (minimum 5000 units).
  - body: { id: string, quantityOrdered: integer }
- `POST https://api.mcp.ai/api/postgrid/create/template` — 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.
  - body: { html: string, name: string, description?: string, testRenderModel?: object }
- `POST https://api.mcp.ai/api/postgrid/create/template/editor/session` — Tool to create a template editor session for interactive template editing. Use when you need to generate an embeddable URL for editing a template. The session URL allows users to modify template HTML 
  - body: { template: string }
- `POST https://api.mcp.ai/api/postgrid/create/tracker` — Tool to create a tracker for monitoring mail delivery status via URL tracking. Use when you need to track recipient engagement with personalized URLs.
  - body: { metadata?: object, description?: string, urlExpireAfterDays: integer, redirectURLTemplate: string }
- `POST https://api.mcp.ai/api/postgrid/create/webhook` — Tool to create a new webhook to receive order event notifications. Use after configuring your endpoint to handle webhook payloads.
  - body: { url: string, enabledEvents: string[], payloadFormat?: string }
- `POST https://api.mcp.ai/api/postgrid/delete/bank/account` — Tool to delete a bank account by its ID. Use when you need to remove a bank account after confirming its identifier.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/delete/contact` — Tool to delete a contact by its ID. Use when you need to remove obsolete contacts after confirming their identifier.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/delete/template` — Tool to delete a template by its ID. Use when you need to remove an existing template after confirming its identifier.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/delete/template/editor/session` — Tool to delete a template editor session by its ID. Use when you need to remove an existing template editor session.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/delete/tracker` — Tool to delete a tracker by its ID. Use when you need to remove an existing tracker after confirming its identifier.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/delete/webhook` — Tool to delete a webhook subscription. Use when you need to remove an existing webhook by its ID.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/fill/test/return/envelope/order` — Tool to fill a test return envelope order for testing purposes. This simulates filling a return envelope order in test mode, changing the status from 'placed' to 'filled'. Only works in test mode.
  - body: { id: string, orderId: string }
- `POST https://api.mcp.ai/api/postgrid/get/bank/account` — Tool to retrieve a bank account. Use after obtaining the bank account ID to fetch its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/box` — Tool to retrieve a specific box order by ID. Use after obtaining the box ID to fetch its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/cheque` — Tool to retrieve a specific cheque by ID. Use when you need to fetch details of a specific cheque order.
  - body: { id: string, expand?: string[] }
- `POST https://api.mcp.ai/api/postgrid/get/contact` — Tool to retrieve a contact. Use after obtaining the contact ID to fetch its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/letter` — Tool to retrieve a letter. Use after you have the letter ID to fetch its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/postcard` — Tool to retrieve a specific postcard by ID. Use when you have a postcard ID and need to fetch its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/return/envelope` — Tool to retrieve a return envelope. Use after obtaining the return envelope ID to fetch its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/return/envelope/order` — Tool to retrieve a specific return envelope order. Use when you need to get details about an order by its return envelope ID and order ID.
  - body: { id: string, orderId: string }
- `POST https://api.mcp.ai/api/postgrid/get/template` — Tool to retrieve a template. Use when you have the template ID and need its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/tracker` — Tool to retrieve a tracker. Use when you have the tracker ID and need its details.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/get/webhook` — Tool to retrieve details of a specific webhook by its ID. Use after creating a webhook to fetch its configuration and status.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/list/bank/accounts` — Tool to list bank accounts. Use when retrieving bank accounts with optional status filter and pagination.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/boxes` — Tool to list box orders. Use when you need to retrieve a paginated list of box orders from PostGrid.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/cheques` — Tool to list cheques with optional filters and pagination. Use when you need to retrieve batches of cheque records for processing or reporting.
  - body: { after?: string, count?: integer, status?: string, to_date?: string, from_date?: string }
- `POST https://api.mcp.ai/api/postgrid/list/contacts` — 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.
  - body: { skip?: integer, limit?: integer, search?: string }
- `POST https://api.mcp.ai/api/postgrid/list/events` — Tool to retrieve a list of webhook events with optional pagination. Use when you need to view all webhook events that have occurred.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/letters` — Tool to list letters. Use when retrieving letters with optional filters and pagination.
  - body: { after?: string, limit?: integer, before?: string, dateTo?: string, status?: string, dateFrom?: string }
- `POST https://api.mcp.ai/api/postgrid/list/postal/statements` — Tool to list all postal statements for billing and tracking purposes. Use when you need to retrieve statements for accounting or audit purposes.
  - body: { skip?: integer, limit?: integer, search?: string }
- `POST https://api.mcp.ai/api/postgrid/list/postcards` — Tool to retrieve a list of postcards with optional filtering and pagination. Use when you need to browse or filter postcards list.
  - body: { skip?: integer, limit?: integer, status?: string, to_date?: string, metadata?: object, from_date?: string, contact_id?: string }
- `POST https://api.mcp.ai/api/postgrid/list/return/envelope/orders` — Tool to list all return envelope orders for a specific return envelope. Use when retrieving orders associated with a return envelope ID.
  - body: { id: string, skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/return/envelopes` — Tool to list return envelopes. Use when you need to retrieve a paginated list of business reply envelopes (BREs) with optional pagination.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/self/mailers` — Tool to list self-mailers. Use when you need to fetch self-mailers with filters and pagination.
  - body: { skip?: integer, limit?: integer, status?: string, to_date?: string, metadata?: object, from_date?: string }
- `POST https://api.mcp.ai/api/postgrid/list/sub/organizations` — Tool to list sub-organizations. Use when you need to retrieve a paginated list of sub-organizations with optional search filter.
  - body: { skip?: integer, limit?: integer, search?: string }
- `POST https://api.mcp.ai/api/postgrid/list/template/editor/sessions` — Tool to list template editor sessions. Use when you need to retrieve a paginated list of template editor sessions.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/templates` — Tool to list templates. Use when you need to retrieve a paginated list of templates with optional type filtering.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/tracker/visits` — Tool to list all visits for a tracker. Use when you need to retrieve visit information including device, IP address, and referred tracker/order ID for each visit.
  - body: { id: string, skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/trackers` — Tool to list all trackers. Use when you need to retrieve a paginated list of trackers for tracking mail interactions.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/webhook/invocations` — Tool to list previous invocations of a webhook with response status codes. Use when you need to view the history of webhook delivery attempts and their outcomes.
  - body: { id: string, skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/list/webhooks` — Tool to retrieve a list of configured webhooks with optional filtering and pagination. Use when you need to view your webhooks.
  - body: { skip?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/postgrid/progress/test/box` — Tool to progress a test box through processing stages for webhook testing. Use when testing webhook integration by advancing box status.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/progress/test/cheque` — Tool to progress a test cheque through processing stages for webhook testing. Use when you need to simulate cheque status changes (ready -> printing -> processed_for_delivery -> completed) to test web
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/progress/test/postcard` — Tool to progress a test postcard through processing stages for webhook testing. Use when testing webhook integration by advancing postcard status.
  - body: { id: string }
- `POST https://api.mcp.ai/api/postgrid/update/template` — Tool to update an existing mail template in PostGrid. Use when you need to modify the HTML content, description, or metadata of a template.
  - body: { id: string, html: string, metadata?: object, description?: string }
- `POST https://api.mcp.ai/api/postgrid/update/tracker` — Tool to update an existing tracker's redirect URL template and/or expiration settings. Use when you need to modify tracker configuration after obtaining its identifier.
  - body: { id: string, urlExpireAfterDays?: integer, redirectURLTemplate?: string }
- `POST https://api.mcp.ai/api/postgrid/update/webhook` — Tool to update an existing webhook configuration. Use when you need to modify webhook URL, events, or other settings.
  - body: { id: string, url?: string, enabled?: boolean, enabledEvents?: string[], payloadFormat?: string }

## Example prompts
- "What can I do in Postgrid?"
- "Show me a summary of my Postgrid account"

## More
- Page: https://mcp.ai/postgrid
- Agent spec (llms.txt): https://mcp.ai/postgrid/llms.txt
- Postman collection: https://mcp.ai/postgrid/postman.json