Stannp

Stannp Groups API

Manage recipient groups

GitHub OpenAPI

Operations 7

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 /groups/list List recipient groups · List groups #
Ask an LLM
“What mailing groups have I set up?”
“Can I page through my recipient groups a few at a time?”
Tell an agent
List all my recipient groups.
Show the next {limit} mailing groups starting at offset {offset}.
POST /groups/new Create a recipient group · Create a group #
Ask an LLM
“How do I set up a new mailing list group to hold recipients?”
“Can I create an empty group now and add addresses to it later?”
Tell an agent
Create a new recipient group called {name}.
Set up a mailing group named {name} for my next campaign.
POST /groups/add/{group_id} Add existing recipients to a group · Add recipients to group #
Ask an LLM
“Can I put recipients I've already created into another mailing group?”
“Is there a way to add several existing contacts to a group in one call?”
Tell an agent
Add recipients {recipients} to group {group_id}.
Put these existing recipient IDs {recipients} into mailing group {group_id}.
POST /groups/remove/{group_id} Remove specific recipients from a group · Remove recipients from group #
Ask an LLM
“How can I take a few people out of a mailing group without deleting them?”
“Can I drop selected recipients from one group while keeping the rest?”
Tell an agent
Remove recipients {recipients} from group {group_id}.
Take recipient IDs {recipients} out of mailing group {group_id} but keep their records.
POST /groups/purge Empty all recipients out of a group · Purge a group #
Ask an LLM
“How do I clear every recipient out of a group but keep the group itself?”
“When I empty a group, can I also wipe the recipient records it contained?”
Tell an agent destructive · confirm first
Purge all recipients from group {id}.
Empty group {id} and also delete its recipient records.
POST /groups/calculate/{group_id} Recalculate a group's counts and validity · Recalculate group #
Ask an LLM
“Why does my group's recipient count look out of date, and can I refresh it?”
“Can I re-check how many addresses in a group are valid?”
Tell an agent
Recalculate recipient counts for group {group_id}.
Refresh the address validity totals on mailing group {group_id}.
POST /groups/delete Delete a recipient group · Delete a group #
Ask an LLM
“How do I delete a mailing group I no longer need?”
“If I remove a group entirely, do its recipients get deleted too?”
Tell an agent destructive · confirm first
Delete recipient group {id}.
Delete group {id} along with every recipient in it.

Documentation

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

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/stannp/refs/heads/main/openapi/stannp-groups-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/stannp/refs/heads/main/json-schema/recipient.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/stannp/refs/heads/main/json-schema/mailpiece.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/stannp/refs/heads/main/json-schema/campaign.json

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/stannp/refs/heads/main/overlays/stannp-groups-api-overlay.yaml
🔗
Vocabulary
https://raw.githubusercontent.com/api-evangelist/stannp/refs/heads/main/vocabulary/stannp-vocabulary.yml
🔗
JSONLDContext
https://raw.githubusercontent.com/api-evangelist/stannp/refs/heads/main/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-groups-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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-groups-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Stannp Direct Mail Groups 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: Groups
  description: Manage recipient groups
paths:
  /groups/list:
    get:
      operationId: listGroups
      summary: List groups
      description: Retrieve a paginated list of recipient groups.
      tags:
      - Groups
      parameters:
      - 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: Groups retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/new:
    post:
      operationId: createGroup
      summary: Create a group
      description: Create a new recipient group.
      tags:
      - Groups
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Group name
      responses:
        '200':
          description: Group created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: integer
                    description: New group ID
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/add/{group_id}:
    post:
      operationId: addRecipientsToGroup
      summary: Add recipients to group
      description: Add one or more existing recipients to a group.
      tags:
      - Groups
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
        description: Group ID
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - recipients
              properties:
                recipients:
                  type: string
                  description: Comma-separated recipient IDs
      responses:
        '200':
          description: Recipients added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: integer
                    description: Number of recipients added
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/remove/{group_id}:
    post:
      operationId: removeRecipientsFromGroup
      summary: Remove recipients from group
      description: Remove one or more recipients from a group.
      tags:
      - Groups
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
        description: Group ID
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - recipients
              properties:
                recipients:
                  type: string
                  description: Comma-separated recipient IDs
      responses:
        '200':
          description: Recipients removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: integer
                    description: Number of recipients removed
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/purge:
    post:
      operationId: purgeGroup
      summary: Purge a group
      description: Remove all recipients from a group, optionally deleting recipient records.
      tags:
      - Groups
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Group ID
                delete_recipients:
                  type: boolean
                  description: If true, delete all recipient records in the group
      responses:
        '200':
          description: Group purged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/calculate/{group_id}:
    post:
      operationId: recalculateGroup
      summary: Recalculate group
      description: Trigger a recalculation of group recipient counts and validity.
      tags:
      - Groups
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
        description: Group ID
      responses:
        '200':
          description: Recalculation triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/delete:
    post:
      operationId: deleteGroup
      summary: Delete a group
      description: Delete a recipient group, optionally deleting associated recipient records.
      tags:
      - Groups
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Group ID
                delete_recipients:
                  type: boolean
                  description: If true, also delete all recipients in the group
      responses:
        '200':
          description: Group deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    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)
    Group:
      type: object
      properties:
        id:
          type: integer
        account_id:
          type: integer
        name:
          type: string
        created:
          type: string
          format: date-time
        recipients:
          type: integer
          description: Total recipient count
        valid:
          type: integer
          description: Count of valid addresses
        international:
          type: integer
          description: Count of international addresses
        skipped:
          type: integer
        status:
          type: string
        import_progress:
          type: integer
          description: Import progress percentage
        is_seeds:
          type: boolean
  responses:
    Unauthorized:
      description: Authentication required or API key invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your API key as the username and leave the password blank.