Stannp

Stannp Campaigns API

Manage batch direct mail campaigns

Documentation GitHub OpenAPI

Business capability

Operations 9

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 /campaigns/list List direct mail campaigns · List campaigns #

Ask an LLM

“What mail campaigns have I created so far?”

“Can I see all my Stannp campaigns in one list?”

Tell an agent

List all my direct mail campaigns.

Show every campaign on my account.

GET /campaigns/get/{id} Look up a campaign · Get a campaign #

Ask an LLM

“What are the settings and status of one particular campaign?”

“Can I pull up a single campaign's details by its ID?”

Tell an agent

Show the details of campaign {id}.

Check the current status of mail campaign {id}.

POST /campaigns/create Create a direct mail campaign for a group · Create a campaign #

Ask an LLM

“How do I set up a bulk mailing to everyone in one of my recipient groups?”

“Can a campaign go only to the valid addresses in a group?”

Tell an agent

Create a {type} campaign named {name} for group {group_id} using template {template_id}.

Start a letter campaign called {name} of type {type} to group {group_id} from the PDF at {file}.

POST /campaigns/sample Generate a sample PDF of a campaign · Get campaign sample #

Ask an LLM

“Can I see a proof of what a campaign's mailpiece will look like before approving it?”

“How long does a campaign's sample PDF link stay valid?”

Tell an agent

Generate a sample PDF proof for campaign {id}.

Give me a preview of the mailpiece in campaign {id}.

POST /campaigns/approve Approve a campaign for booking · Approve a campaign #

Ask an LLM

“What do I need to do before a campaign can be scheduled?”

“How do I sign off on a campaign's design so it's ready to book?”

Tell an agent

Approve campaign {id} so it can be booked.

Mark campaign {id} as signed off and ready for booking.

POST /campaigns/cost Calculate what a campaign will cost · Get campaign cost #

Ask an LLM

“How much will it cost to send a campaign, including VAT?”

“Can I see a per-recipient cost breakdown before I book a mailing?”

Tell an agent

Work out the total cost of campaign {id}.

Show the recipient breakdown and VAT for campaign {id}.

POST /campaigns/availableDates Find available campaign dispatch dates · Get available booking dates #

Ask an LLM

“Which dates can my campaign be sent out on?”

“Is there an open dispatch slot for a mailing within a particular date range?”

Tell an agent

List the available dispatch dates between {start} and {end}.

Show which upcoming days I can book a campaign to go out.

POST /campaigns/book Schedule a campaign for dispatch · Book a campaign #

Ask an LLM

“How do I schedule an approved campaign to go out on a specific day?”

“What if the date I pick for my mailing is unavailable?”

Tell an agent

Book campaign {id} for dispatch on {send_date}.

Schedule campaign {id} for {send_date}, falling back to the next available date, paid from my balance.

POST /campaigns/delete Delete a campaign · Delete a campaign #

Ask an LLM

“Can I get rid of a campaign I no longer plan to send?”

“Is deleting a mail campaign permanent?”

Tell an agent destructive · confirm first

Delete campaign {id} permanently.

Remove mail campaign {id} from my account.

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-campaigns-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

openapi: 3.2.0
info:
  title: Stannp Direct Mail Campaigns 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: Campaigns
  description: Manage batch direct mail campaigns
paths:
  /campaigns/list:
    get:
      operationId: listCampaigns
      summary: List campaigns
      description: Retrieve a list of all campaigns.
      tags:
      - Campaigns
      responses:
        '200':
          description: Campaigns retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns/get/{id}:
    get:
      operationId: getCampaign
      summary: Get a campaign
      description: Retrieve details of a single campaign.
      tags:
      - Campaigns
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Campaign ID
      responses:
        '200':
          description: Campaign retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /campaigns/create:
    post:
      operationId: createCampaign
      summary: Create a campaign
      description: Create a new direct mail campaign targeting a recipient group.
      tags:
      - Campaigns
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - name
              - type
              - group_id
              properties:
                name:
                  type: string
                  description: Campaign name
                type:
                  type: string
                  enum:
                  - a6-postcard
                  - a5-postcard
                  - letter
                  description: Campaign type
                template_id:
                  type: integer
                  description: Template ID to use for the campaign
                file:
                  type: string
                  format: uri
                  description: URL to PDF file for letters
                front:
                  type: string
                  format: uri
                  description: URL to front design for postcards
                back:
                  type: string
                  format: uri
                  description: URL to back design for postcards
                size:
                  type: string
                  description: Mail piece size (when using files)
                save:
                  type: boolean
                  description: Save the campaign as a draft
                group_id:
                  type: integer
                  description: ID of the recipient group
                what_recipients:
                  type: string
                  description: 'Filter: all, valid, not_valid, or integer count'
                addons:
                  type: string
                  description: Upgrade codes (e.g. FIRST_CLASS)
      responses:
        '200':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns/sample:
    post:
      operationId: getCampaignSample
      summary: Get campaign sample
      description: Generate a sample PDF for the campaign (valid for 30 minutes).
      tags:
      - Campaigns
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Campaign ID
      responses:
        '200':
          description: Sample PDF generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: string
                    format: uri
                    description: URL to sample PDF (valid for 30 minutes)
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns/approve:
    post:
      operationId: approveCampaign
      summary: Approve a campaign
      description: Approve a campaign, making it ready for booking.
      tags:
      - Campaigns
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Campaign ID
      responses:
        '200':
          description: Campaign approved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns/cost:
    post:
      operationId: getCampaignCost
      summary: Get campaign cost
      description: Calculate the cost of a campaign including recipient breakdown and VAT.
      tags:
      - Campaigns
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Campaign ID
      responses:
        '200':
          description: Campaign cost calculated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      rate:
                        type: string
                        description: Per-item rate
                      valid:
                        type: integer
                        description: Count of valid recipients
                      invalid:
                        type: integer
                        description: Count of invalid recipients
                      total:
                        type: string
                        description: Total cost before tax
                      total_with_vat:
                        type: string
                        description: Total cost including VAT
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns/availableDates:
    post:
      operationId: getCampaignAvailableDates
      summary: Get available booking dates
      description: Retrieve available dates on which a campaign can be dispatched.
      tags:
      - Campaigns
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                start:
                  type: string
                  format: date
                  description: Start of date range (YYYY-MM-DD)
                end:
                  type: string
                  format: date
                  description: End of date range (YYYY-MM-DD)
      responses:
        '200':
          description: Available dates retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: string
                      format: date
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns/book:
    post:
      operationId: bookCampaign
      summary: Book a campaign
      description: Schedule a campaign for dispatch on a specific date.
      tags:
      - Campaigns
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              - send_date
              properties:
                id:
                  type: integer
                  description: Campaign ID
                send_date:
                  type: string
                  format: date
                  description: Dispatch date (YYYY-MM-DD)
                next_available_date:
                  type: boolean
                  default: true
                  description: Use next available date if chosen date is unavailable
                use_balance:
                  type: boolean
                  default: true
                  description: Pay from account balance
      responses:
        '200':
          description: Campaign booked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns/delete:
    post:
      operationId: deleteCampaign
      summary: Delete a campaign
      description: Permanently delete a campaign.
      tags:
      - Campaigns
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Campaign ID
      responses:
        '200':
          description: Campaign deleted 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:
    Campaign:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
          - a6-postcard
          - a5-postcard
          - letter
        status:
          type: string
        recipients:
          type: integer
        cost:
          type: string
        created:
          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.

Stannp Campaigns API

Operations 9

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification