openapi: 3.0.3
info:
  title: Stannp Direct Mail Account 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:
  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          description: Result value (boolean, integer, or string depending on operation)
    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
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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.