# Stannp

Stannp provides a direct mail API enabling users to send postcards and letters programmatically.

- **Category:** marketing automation
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 32
- **Triggers:** 0
- **Slug:** `STANNP`
- **Version:** 20260307_00

## Tools

### Add recipients to group

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `group_id` | integer | Yes | ID of the group to add recipients to. |
| `recipients` | string | Yes | Comma-separated list of recipient IDs to add to the group (e.g., '1,2' or '45112,45113'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add Recipient to Group

**Slug:** `STANNP_ADD_RECIPIENT_TO_GROUP`

Tool to add a recipient to a recipient group. Use when you need to add new mailing list subscribers.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | Yes | Recipient city. |
| `email` | string | No | Recipient email address. |
| `company` | string | No | Recipient company name. |
| `country` | string | No | Recipient country code; defaults to 'GB'. |
| `custom1` | string | No | Custom field 1. |
| `custom2` | string | No | Custom field 2. |
| `custom3` | string | No | Custom field 3. |
| `address1` | string | Yes | First line of recipient address. |
| `address2` | string | No | Second line of recipient address. |
| `address3` | string | No | Third line of recipient address. |
| `group_id` | string | Yes | The ID of the recipient group to add the recipient to. |
| `postcode` | string | Yes | Recipient postcode. |
| `last_name` | string | Yes | Recipient last name. |
| `first_name` | string | Yes | Recipient first name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Cancel Postcard

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | The ID of the postcard to cancel. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Campaign

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `back` | string | No | A PDF or JPG file for the back image. |
| `file` | string | No | A PDF file URL or binary for the design artwork. |
| `name` | string | Yes | Name your campaign for reference. |
| `save` | boolean | No | Save the uploaded file as a new design template. |
| `size` | string | No | Required when using file or front/back. Example: A4, A5, A6. |
| `type` | string ("a6-postcard" | "a5-postcard" | "letter") | Yes | The type of campaign: a6-postcard, a5-postcard, or letter. |
| `front` | string | No | A PDF or JPG file for the front image. |
| `addons` | string | No | Addon code if available. |
| `group_id` | integer | Yes | A group ID for the recipients. |
| `template_id` | integer | No | A template ID to copy. If left out, a blank template will be used. |
| `what_recipients` | string ("all" | "valid" | "not_valid" | "int") | No | Filter for what recipients to include in the campaign. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create campaign sample

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | ID of the campaign to produce a sample for. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create folder

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | The name of the folder you wish to create. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create recipient group

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name of the group (must be unique within your account). |
| `description` | string | No | Optional description for the group. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Letter

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | string | No | URL to a PDF/DOC file or base64-encoded file content. Maximum of 10 pages. Use this as alternative to template parameter. |
| `tags` | string | No | Comma-separated tags for reference, searchable in reporting |
| `test` | boolean | No | If true, produces a sample PDF without dispatching or charging. Defaults to false. |
| `addons` | string | No | Addon codes to upgrade your letter (e.g., FIRST_CLASS for first-class postage) |
| `duplex` | boolean | No | Set to false to print only on the front of each page. Defaults to true. |
| `template` | integer | No | ID of a template already set up on the platform |
| `clearzone` | boolean | No | If true, overlay clear zones with white background. Defaults to true. |
| `recipient_id` | string | No | ID of an existing recipient in your account. Use this OR recipient_details, not both. |
| `post_unverified` | boolean | No | If false, the item will not be posted if the recipient address cannot be verified. Defaults to true. |
| `recipient_details` | object | No | Detailed recipient information for creating a new recipient. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Postcard

**Slug:** `STANNP_CREATE_POSTCARD`

Tool to create a postcard. Use when you need to send a postcard via direct mail.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `back` | string | No | URL or path to back image (JPG or PDF) |
| `size` | string | Yes | Postcard size: "4x6", "6x9", or "6x11" |
| `tags` | string | No | Tags for tracking and reporting |
| `test` | boolean | No | Test mode - generates PDF but doesn't dispatch |
| `front` | string | No | URL or path to front image (JPG or PDF) |
| `message` | string | No | Message text to include on the postcard |
| `recipient` | object | Yes | Recipient information including firstname, lastname, address1, city, zipcode, country |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create recipient selection

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional name for the filter selection to help identify it. |
| `filters` | string | Yes | Specially formatted filter string: [column_name]:::[operator]:::[value]. Valid operators: matches, contains, begins, ends, before, after, less_than, more_than, is_not. Chain multiple filters with :::AND:::. Example: 'firstname:::contains:::test' or 'firstname:::contains:::john:::AND:::age:::more_than:::25'. |
| `group_id` | integer | Yes | The ID of the group to associate this selection with. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete recipient group

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | ID of the group to delete. |
| `delete_recipients` | boolean | No | If true, completely delete all recipients in the group. Defaults to false (recipients remain on your account). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Recipient

**Slug:** `STANNP_DELETE_RECIPIENT`

Tool to permanently delete a recipient from your account. Use when you need to remove a recipient from your mailing list.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | ID of the recipient to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account Balance

**Slug:** `STANNP_GET_ACCOUNT_BALANCE`

Tool to retrieve the current account balance. Use when you need to check available account funds.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Campaign

**Slug:** `STANNP_GET_CAMPAIGN`

Tool to retrieve details of a specific campaign. Use when you need to get information about a campaign by its ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | ID of the campaign to retrieve |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Campaign Available Dates

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | Yes | End date in YYYY-MM-DD format for the date range query. |
| `start` | string | Yes | Start date in YYYY-MM-DD format for the date range query. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Campaign Cost

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | ID of the campaign to get the cost of booking. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact

**Slug:** `STANNP_GET_CONTACT`

Tool to retrieve details of a specific contact. Use when you need all stored fields of a contact by its ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contact_id` | string | Yes | The ID of the contact to retrieve |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Current User

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Reporting Summary

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end_date` | string | Yes | End date in YYYY-MM-DD format for the reporting period |
| `start_date` | string | Yes | Start date in YYYY-MM-DD format for the reporting period |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Import Recipients

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | string | Yes | Base64-encoded CSV or XLS file content to upload |
| `group_id` | string | Yes | ID of the recipient group to import into |
| `update_existing` | boolean | No | Whether to update existing recipients if duplicates are found |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Campaigns

**Slug:** `STANNP_LIST_CAMPAIGNS`

Tool to get a list of all campaigns. Use when you need to retrieve campaigns after authentication.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Contacts

**Slug:** `STANNP_LIST_CONTACTS`

Tool to list all contacts. Use when you need to retrieve contacts with optional pagination filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number for paginated results |
| `limit` | integer | No | Number of results per page |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Folders

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Mailing Groups

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Limit for pagination. Specifies the maximum number of groups to return. |
| `offset` | integer | No | Offset for pagination. Specifies the starting point for the result set. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Mailpieces

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | string | No | Filter by custom tag associated with mailpieces |
| `status` | string | No | Filter by delivery status (e.g., delivered, returned, printing, local_delivery) |
| `enddate` | string | Yes | End date of the reporting period in YYYY-MM-DD format |
| `startdate` | string | Yes | Start date of the reporting period in YYYY-MM-DD format |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Templates

**Slug:** `STANNP_LIST_TEMPLATES`

Tool to list all templates associated with the account. Use when you need to retrieve available templates after authentication.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | Page number for paginated results |
| `size` | integer | No | Number of records per page |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Merge PDF files

**Slug:** `STANNP_MERGE_PDFS`

Tool to merge multiple PDF files into a single file. Use when you need to consolidate multiple PDFs into one document.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `files` | array | Yes | An array of URLs for the PDF files to merge. Provide at least 2 URLs to merge. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Purge Group

**Slug:** `STANNP_PURGE_GROUP`

Tool to remove all recipients from a mailing list. Recipients remain on your account if delete_recipients is false.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | ID of the group to purge. |
| `delete_recipients` | boolean | No | If true, completely delete all recipients. Defaults to false. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recalculate group

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `group_id` | integer | Yes | The ID of the group to recalculate. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove Recipients from Group

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `group_id` | integer | Yes | ID of the group to remove recipients from. |
| `recipients` | string | Yes | Comma-separated recipient IDs to remove from the group. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload File

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | string | Yes | File to upload. Can be either a file or a URL string pointing to a remote file to be imported (e.g., 'https://example.com/file.pdf'). |
| `folder` | integer | No | A folder ID for placing the file in a specific folder |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Address

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | No | Address city. |
| `state` | string | No | Two-letter state abbreviation if possible. |
| `company` | string | No | Company name. |
| `country` | string | No | ISO 3166-1 Alpha 2 Country Code (US, GB, CA, FR...). |
| `zipcode` | string | No | Address zipcode. |
| `address1` | string | No | Address line 1. |
| `address2` | string | No | Address line 2. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |