Stannp

Stannp Recipients API

Manage individual recipients and bulk imports

GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /recipients/list List recipients · List recipients #
Ask an LLM
“Who is on my mailing list?”
“Can I list only the recipients that belong to one group?”
Tell an agent
List all my recipients.
Show the recipients in group {group_id}, {limit} at a time.
GET /recipients/get/{id} Look up a single recipient · Get a recipient #
Ask an LLM
“What address do I have on file for a specific recipient?”
“Can I fetch one contact's full record by recipient ID?”
Tell an agent
Show the details of recipient {id}.
Get the name and address saved for recipient {id}.
POST /recipients/new Add a recipient address · Create a recipient #
Ask an LLM
“How do I add one new person's postal address to my mailing list?”
“What happens if I add a recipient who already exists?”
Tell an agent
Add {firstname} {lastname} at {address1}, {city} {postcode}, {country} as a recipient.
Create a recipient for {company} at {address1}, {postcode} and put them in group {group_id}.
POST /recipients/delete Delete a recipient · Delete a recipient #
Ask an LLM
“How do I permanently remove someone's address record?”
“Can a deleted recipient be recovered afterwards?”
Tell an agent destructive · confirm first
Delete recipient {id} permanently.
Erase the address record for recipient {id}.
POST /recipients/import Bulk import recipients from a spreadsheet · Import recipients from file #
Ask an LLM
“Can I upload a CSV or Excel file of addresses instead of adding them one by one?”
“What if my spreadsheet of contacts has no header row?”
Tell an agent
Import the recipients in {file} into group {group_id}.
Bulk load the CSV at {file} into group {group_id} using column mappings {mappings}.

Documentation

📖
Documentation
https://www.stannp.com/us/direct-mail-api/guide

Specifications

⚙
OpenAPI
https://artifacts.apis.io/stannp/openapi/stannp-recipients-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/stannp/json-schema/recipient.json
📊
JSONSchema
https://artifacts.apis.io/stannp/json-schema/mailpiece.json
📊
JSONSchema
https://artifacts.apis.io/stannp/json-schema/campaign.json

Other Resources

🔗
Overlay
https://artifacts.apis.io/stannp/overlays/stannp-recipients-api-overlay.yaml
🔗
AgentSkill
https://artifacts.apis.io/stannp/skills/stannp-sync-recipients-and-track-engagement.md
🔗
Vocabulary
https://artifacts.apis.io/stannp/vocabulary/stannp-vocabulary.yml
🔗
JSONLDContext
https://artifacts.apis.io/stannp/json-ld/stannp-context.jsonld

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/stannp:stannp-recipients-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

stannp-recipients-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Stannp Direct Mail Recipients API
  description: REST API for programmatically sending physical letters and postcards, managing recipient groups, configuring campaigns, triggering individual mail pieces, and tracking delivery status through webhooks and event callbacks. Authentication uses API key-based HTTP Basic Auth over HTTPS.
  version: 1.0.0
  contact:
    name: Stannp Support
    url: https://www.stannp.com/us/direct-mail-api/guide
  termsOfService: https://www.stannp.com
servers:
- url: https://api-us1.stannp.com/v1
  description: US API server
- url: https://api-eu1.stannp.com/v1
  description: EU API server
security:
- basicAuth: []
tags:
- name: Recipients
  description: Manage individual recipients and bulk imports
paths:
  /recipients/list:
    get:
      operationId: listRecipients
      summary: List recipients
      description: Retrieve a paginated list of recipients, optionally filtered by group.
      tags:
      - Recipients
      parameters:
      - name: group_id
        in: query
        schema:
          type: integer
        description: Filter by group ID
      - name: offset
        in: query
        schema:
          type: integer
        description: Pagination offset
      - name: limit
        in: query
        schema:
          type: integer
        description: Number of results to return
      responses:
        '200':
          description: Recipients retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Recipient'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recipients/get/{id}:
    get:
      operationId: getRecipient
      summary: Get a recipient
      description: Retrieve details of a single recipient.
      tags:
      - Recipients
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Recipient ID
      responses:
        '200':
          description: Recipient retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Recipient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /recipients/new:
    post:
      operationId: createRecipient
      summary: Create a recipient
      description: Add a new recipient, optionally to a mailing group.
      tags:
      - Recipients
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RecipientInput'
      responses:
        '200':
          description: Recipient created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: New recipient ID
                      valid:
                        type: boolean
                        description: Whether the address is valid
                      created:
                        type: string
                        format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recipients/delete:
    post:
      operationId: deleteRecipient
      summary: Delete a recipient
      description: Permanently delete a recipient record.
      tags:
      - Recipients
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Recipient ID to delete
      responses:
        '200':
          description: Recipient deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /recipients/import:
    post:
      operationId: importRecipients
      summary: Import recipients from file
      description: Bulk import recipients from a CSV or XLS file into a group.
      tags:
      - Recipients
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - group_id
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV or XLS file (binary, base64, or URL)
                group_id:
                  type: integer
                  description: Group to import recipients into
                duplicates:
                  type: string
                  enum:
                  - update
                  - ignore
                  - duplicate
                  description: How to handle duplicate recipients
                no_headings:
                  type: boolean
                  description: Set true if the file has no header row
                mappings:
                  type: string
                  description: Column remapping instructions
      responses:
        '200':
          description: Import initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication required or API key invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    RecipientInput:
      type: object
      properties:
        group_id:
          type: integer
          description: Group to add the recipient to
        title:
          type: string
          description: Title (Mr, Mrs, Dr, etc.)
        firstname:
          type: string
        lastname:
          type: string
        company:
          type: string
        job_title:
          type: string
        address1:
          type: string
          description: First line of address
        address2:
          type: string
        address3:
          type: string
        city:
          type: string
        county:
          type: string
          description: State or county
        postcode:
          type: string
          description: Postcode or ZIP code
        zipcode:
          type: string
          description: ZIP code (US alternative to postcode)
        country:
          type: string
          description: ISO 3166-1 Alpha-2 country code
          example: US
        email:
          type: string
          format: email
        phone_number:
          type: string
        ref_id:
          type: string
          description: Custom external reference ID
        on_duplicate:
          type: string
          enum:
          - update
          - ignore
          - duplicate
          description: Behaviour when duplicate is found
        test_level:
          type: string
          enum:
          - email
          - fullname
          - initial
          - ref_id
          description: Field(s) used to detect duplicates
    Recipient:
      type: object
      properties:
        id:
          type: integer
        account_id:
          type: integer
        title:
          type: string
        firstname:
          type: string
        lastname:
          type: string
        company:
          type: string
        job_title:
          type: string
        address1:
          type: string
        address2:
          type: string
        address3:
          type: string
        city:
          type: string
        county:
          type: string
        country:
          type: string
        zipcode:
          type: string
        dps:
          type: string
          description: Delivery Point Suffix
        email:
          type: string
        phone_number:
          type: string
        ref_id:
          type: string
        blacklist:
          type: boolean
          description: Whether recipient is on the block list
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Error message
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          description: Result value (boolean, integer, or string depending on operation)
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your API key as the username and leave the password blank.