# Stannp — how to use (mcp.ai)

Connect your Stannp account and use 32 tools for marketing automation straight from your AI agent. Connect with your own API key. Stannp provides a direct mail API enabling users to send postcards and letters programmatically.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_stannp?ms=1787291280000`
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. `stannp_add_recipient_to_group`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/stannp`
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/stannp/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/stannp/add/recipient/to/group` — Tool to add a recipient to a recipient group. Use when you need to add new mailing list subscribers.
  - body: { city: string, email?: string, company?: string, country?: string, custom1?: string, custom2?: string, custom3?: string, address1: string, address2?: string, address3?: string, group_id: string, postcode: string, last_name: string, first_name: string }
- `POST https://api.mcp.ai/api/stannp/add/recipients/to/group` — Tool to add existing recipients to a mailing list group. Use when you need to add recipients from your account to an existing group for campaign management.
  - body: { group_id: integer, recipients: string }
- `POST https://api.mcp.ai/api/stannp/cancel/postcard` — Tool to cancel a postcard if processing has not started yet. Use when you need to cancel a scheduled postcard before it enters production.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/stannp/create/campaign` — Tool to create a new direct mail campaign on the platform. Use when you need to set up a campaign with recipients and design templates. Requires a valid group_id with recipients.
  - body: { back?: string, file?: string, name: string, save?: boolean, size?: string, type: string, front?: string, addons?: string, group_id: integer, template_id?: integer, what_recipients?: string }
- `POST https://api.mcp.ai/api/stannp/create/campaign/sample` — Tool to produce a PDF sample of your campaign. The generated link will be valid for 30 minutes. Use when you need to preview a campaign before sending it to recipients.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/stannp/create/folder` — Tool to create a folder in your secure file transfer area. Use when you need to organize files or prepare a storage location before uploading documents.
  - body: { name: string }
- `POST https://api.mcp.ai/api/stannp/create/group` — Tool to create a new recipient group in Stannp. Use when you need to organize contacts into a distinct group before sending campaigns.
  - body: { name: string, description?: string }
- `POST https://api.mcp.ai/api/stannp/create/letter` — Tool to create a letter with mail merge to insert address and variable data. Use when you need to send physical mail via Stannp API.
  - body: { file?: string, tags?: string, test?: boolean, addons?: string, duplex?: boolean, template?: integer, clearzone?: boolean, recipient_id?: string, post_unverified?: boolean, recipient_details?: object }
- `POST https://api.mcp.ai/api/stannp/create/postcard` — Tool to create a postcard. Use when you need to send a postcard via direct mail.
  - body: { back?: string, size: string, tags?: string, test?: boolean, front?: string, message?: string, recipient: object }
- `POST https://api.mcp.ai/api/stannp/create/selection` — Tool to create a new recipient selection for targeting in Stannp. Use when you need to create an auto filter selection to target specific recipients within a group based on criteria.
  - body: { name?: string, filters: string, group_id: integer }
- `POST https://api.mcp.ai/api/stannp/delete/group` — Tool to delete a recipient group in Stannp. Recipients remain on your account unless delete_recipients is true. Use when you need to remove a mailing list group.
  - body: { id: integer, delete_recipients?: boolean }
- `POST https://api.mcp.ai/api/stannp/delete/recipient` — Tool to permanently delete a recipient from your account. Use when you need to remove a recipient from your mailing list.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/stannp/get/account/balance` — Tool to retrieve the current account balance. Use when you need to check available account funds.
- `POST https://api.mcp.ai/api/stannp/get/campaign` — Tool to retrieve details of a specific campaign. Use when you need to get information about a campaign by its ID.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/stannp/get/campaign/available/dates` — Tool to get available dates for scheduling a campaign (up to 30 days). Use when you need to check which dates are available for campaign dispatch.
  - body: { end: string, start: string }
- `POST https://api.mcp.ai/api/stannp/get/campaign/cost` — Tool to get the estimated cost of booking a campaign. Use when you need to calculate the total cost before booking a direct mail campaign.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/stannp/get/contact` — Tool to retrieve details of a specific contact. Use when you need all stored fields of a contact by its ID.
  - body: { contact_id: string }
- `POST https://api.mcp.ai/api/stannp/get/current/user` — Tool to get information about the currently authenticated user including rate limit status. Use when you need to retrieve the current user's account details or check API rate limit status.
- `POST https://api.mcp.ai/api/stannp/get/reporting/summary` — Tool to get a status summary on individual items within a date range. Use when you need reporting metrics for mailpieces including delivery status, printing status, and counts.
  - body: { end_date: string, start_date: string }
- `POST https://api.mcp.ai/api/stannp/import/recipients` — Tool to import recipients from a CSV or XLS file into a Stannp recipient group. Use when you have a mailing list file ready to upload.
  - body: { file: string, group_id: string, update_existing?: boolean }
- `POST https://api.mcp.ai/api/stannp/list/campaigns` — Tool to get a list of all campaigns. Use when you need to retrieve campaigns after authentication.
- `POST https://api.mcp.ai/api/stannp/list/contacts` — Tool to list all contacts. Use when you need to retrieve contacts with optional pagination filters.
  - body: { page?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/stannp/list/folders` — Tool to get a list of folders in your secure file transfer area. Use when you need to retrieve available folders for file organization.
- `POST https://api.mcp.ai/api/stannp/list/groups` — Tool to get a list of mailing groups on your account. Use when you need to retrieve all groups with optional pagination.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/stannp/list/mailpieces` — Tool to retrieve mailpiece objects sent within a date range. Use when you need to query mailing history with optional status or tag filters.
  - body: { tag?: string, status?: string, enddate: string, startdate: string }
- `POST https://api.mcp.ai/api/stannp/list/templates` — Tool to list all templates associated with the account. Use when you need to retrieve available templates after authentication.
  - body: { page?: integer, size?: integer }
- `POST https://api.mcp.ai/api/stannp/merge/pdfs` — Tool to merge multiple PDF files into a single file. Use when you need to consolidate multiple PDFs into one document.
  - body: { files: string[] }
- `POST https://api.mcp.ai/api/stannp/purge/group` — Tool to remove all recipients from a mailing list. Recipients remain on your account if delete_recipients is false.
  - body: { id: integer, delete_recipients?: boolean }
- `POST https://api.mcp.ai/api/stannp/recalculate/group` — Tool to recalculate a group to ensure stats are up to date. Use when you need to refresh group statistics after adding or removing recipients.
  - body: { group_id: integer }
- `POST https://api.mcp.ai/api/stannp/remove/recipients/from/group` — Tool to remove recipients from a group without deleting them. Use when you need to remove contacts from a mailing group while keeping them in your account.
  - body: { group_id: integer, recipients: string }
- `POST https://api.mcp.ai/api/stannp/upload/file` — Tool to upload a file to your secure file transfer area. Use when you need to upload files for direct mail campaigns. Supports both URL-based imports and binary file uploads.
  - body: { file: object|string, folder?: integer }
- `POST https://api.mcp.ai/api/stannp/validate/address` — Tool to validate a postal address. Currently supports UK and US addresses only. Use when you need to verify if a given address is valid before sending mail.
  - body: { city?: string, state?: string, company?: string, country?: string, zipcode?: string, address1?: string, address2?: string }

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

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