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/thanks-io:thanks-io-recipients-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

openapi: 3.2.0
info:
  title: thanks.io Recipients API
  description: Use the thanks.io API to send postcards, letters, notecards, windowless letters, and gift cards.
  contact:
    url: https://thanks.io
    email: support@thanks.io
  version: 1.0.0
servers:
- url: https://api.thanks.io/api/v2
  description: The main API server for thanks.io
security:
- bearerAuth: []
tags:
- name: Recipients
paths:
  /recipients/{recipientId}:
    parameters:
    - name: recipientId
      in: path
      description: Recipient ID
      required: true
      schema:
        type: integer
        example: 296446
    get:
      tags:
      - Recipients
      operationId: getRecipientsDetails
      summary: Get Recipient
      description: Get a recipient by ID.
      responses:
        '200':
          description: Successful Response
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/recipient'
              examples:
                recipient:
                  $ref: '#/components/examples/recipient-example'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Recipients
      summary: Update Recipient
      operationId: updateRecipientDetails
      description: 'Update details of a specific recipient by ID. Leave out `absentee_address` to keep the current absentee address. Sending it replaces the stored absentee address as a whole, so send it together with any of `absentee_city`, `absentee_province` and `absentee_postal_code`: those on their own, for example only a new ZIP, are refused with a 400 and nothing is updated. Send `absentee_address` as an empty string or null to remove the absentee address; if the same request also sets `custom1` to `absentee` with an address in `custom2`, that address is copied in instead.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/recipient'
              - type: object
                properties:
                  absentee_city:
                    $ref: '#/components/schemas/absentee-city'
                  absentee_province:
                    $ref: '#/components/schemas/absentee-province'
                  absentee_postal_code:
                    $ref: '#/components/schemas/absentee-postal-code'
      responses:
        '200':
          description: Successful Response
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/recipient'
              examples:
                recipient:
                  $ref: '#/components/examples/recipient-example'
        '400':
          description: The mailing list does not exist, or the absentee fields are invalid, such as `absentee_postal_code` sent without `absentee_address`
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Mailing list does not exist:
                  value:
                    message: Mailing List Does Not Exist
                Absentee fields without absentee_address:
                  value:
                    message: absentee_city, absentee_province and absentee_postal_code need absentee_address as well.
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Recipients
      operationId: deleteRecipient
      summary: Delete Recipient
      responses:
        '200':
          description: Successful Response
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                type: object
              example:
                message: success
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /recipients:
    post:
      tags:
      - Recipients
      operationId: createRecipient
      summary: Create Recipient
      description: Add a recipient. If you do not provide a valid mailing address but do provide a valid email address, thanks.io can attempt to look up a street address for an additional fee.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/recipient-create'
            examples:
              Adding By Address:
                value:
                  mailing_list_id: 1
                  name: Tobias Example
                  company: thanks.io
                  address: 12345 Main Street
                  address2: Apartment 1
                  city: Any Town
                  province: NY
                  postal_code: '12345'
                  country: US
                  dob: '1981-04-23'
                  anniversary: '2025-07-21'
                  email: tobias@example.com
                  phone: 845-988-6485
                  custom1: Unique Info
                  custom2: For example a product code or customer ID
                  custom3: ''
                  custom4: ''
              Adding By Email:
                value:
                  mailing_list_id: 1
                  email: tobias@example.com
      responses:
        '200':
          description: Successful Response
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/recipient'
              examples:
                recipient:
                  $ref: '#/components/examples/recipient-example'
        '400':
          $ref: '#/components/responses/MailingListDoesNotExist'
        '404':
          $ref: '#/components/responses/NotFound'
  /recipients-utils/create-multiple:
    post:
      tags:
      - Recipients
      operationId: createMultipleRecipients
      summary: Create Multiple Recipients
      description: Add multiple recipients at once using a JSON array of recipient objects. If a recipient does not include a valid mailing address but does include a valid email address, thanks.io can attempt to look up a street address for an additional fee.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/recipient-create'
              example:
              - mailing_list: 1
                name: Tobias First
                address: 987 Main Street
                address2: null
                city: LENEXA
                province: KS
                postal_code: '66216'
                country: US
                dob: 04/23/1981
                anniversary: 04/23/2025
                custom1: null
                custom2: null
                email: testemail@thanks.io
                phone: '1234567890'
              - mailing_list: 1
                email: another-testemail@thanks.io
                phone: '1234567890'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/recipient-array'
              example:
              - province: KS
                city: Lenexa
                name: Tobias First
                company: null
                dob: 04/23/1981
                anniversary: 04/23/2025
                country: US
                address: 987 Main Street
                address2: ''
                email: testemail@thanks.io
                phone: '1234567890'
                custom1: null
                custom2: null
                postal_code: '66216'
              - province: KS
                city: Lenexa
                name: Tobias Second
                company: null
                dob: 04/23/1981
                anniversary: 04/23/2025
                country: US
                address: 654 Main Street
                address2: ''
                email: testemail@thanks.io
                phone: '1234567890'
                custom1: null
                custom2: null
                postal_code: '66216'
                error: This address is already on this mailing list.
  /recipients-utils/delete-by-address:
    post:
      tags:
      - Recipients
      summary: Delete Recipient By Address
      description: Delete a recipient by using their address or their email address.
      operationId: deleteRecipientByAddress
      requestBody:
        content:
          application/json:
            schema:
              type: object
              anyOf:
              - title: Delete Recipient by Address
                description: Delete a recipient by providing address details
                required:
                - mailing_list_id
                - address
                - postal_code
              - title: Delete Recipient by Email
                description: Delete a recipient by providing email address
                required:
                - mailing_list_id
                - email
              properties:
                mailing_list_id:
                  type: integer
                  example: 1
                address:
                  type: string
                  example: 123 Main Street
                address2:
                  type: string
                  example: Apartment 1
                city:
                  type: string
                  example: Any Town
                province:
                  type: string
                  description: State or Province
                  example: KS
                postal_code:
                  type: string
                  example: '12345'
                country:
                  type: string
                  example: US
                email:
                  type: string
                  example: tobias@example.com
            examples:
              By Address:
                summary: Delete a recipient by address
                value:
                  mailing_list_id: 1
                  address: 123 Main Street
                  postal_code: '12345'
              By Email:
                summary: Delete a recipient by email
                value:
                  mailing_list_id: 1
                  email: tobias@example.com
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                type: object
              example:
                status: Recipient 297230 Deleted
        '400':
          $ref: '#/components/responses/MailingListDoesNotExist'
components:
  schemas:
    recipient:
      type: object
      properties:
        id:
          type: integer
          example: 18113288
          readOnly: true
        mailing_list_id:
          type: integer
          example: 1
        name:
          type: string
          example: Tobias Example
        company:
          type: string
          example: thanks.io
        address:
          type: string
          example: 123 Main Street
        address2:
          type: string
          example: Apartment 1
        city:
          type: string
          example: Any Town
        province:
          type: string
          description: State or Province
          example: KS
        postal_code:
          type: string
          example: '12345'
        country:
          type: string
          example: US
        dob:
          type: string
          description: Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.
          example: '1981-04-23'
        anniversary:
          type: string
          description: Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone.  Anniversary date in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.
          example: '2025-07-21'
        email:
          type: string
          example: tobias@example.com
        phone:
          type: string
          example: +1 (555) 123-4567
        custom1:
          type: string
          description: Custom field for additional information about the recipient
          example: Unique Info
        custom2:
          type: string
          description: Custom field for additional information about the recipient
          example: For example a product code or customer ID
        custom3:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom4:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom5:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom6:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom7:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom8:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom9:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom10:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        absentee_address:
          type:
          - string
          - 'null'
          description: The property (absentee) address the absentee image template and message variables use, or null when none is set. Mail is delivered to `address`, not here.
          example: 742 Evergreen Terrace, Springfield, IL 62704
        mailing-list:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/mailing-list'
          description: The mailing list this recipient belongs to
        created_at:
          readOnly: true
          type: string
          example: '2025-06-27T14:57:11.000000Z'
        updated_at:
          readOnly: true
          type: string
          example: '2025-06-27T14:57:11.000000Z'
    recipient-array:
      type: array
      description: Array of recipient objects
      items:
        $ref: '#/components/schemas/recipient'
    recipient-create:
      type: object
      anyOf:
      - title: Create Recipient by Address
        description: Create a recipient by providing address details
        required:
        - mailing_list_id
        - address
      - title: Create Recipient by Email
        description: Create a recipient by providing email address
        required:
        - mailing_list_id
        - email
      properties:
        id:
          type: integer
          example: 18113288
          readOnly: true
        mailing_list_id:
          type: integer
          example: 1
        name:
          type: string
          example: Tobias Example
        company:
          type: string
          example: thanks.io
        address:
          type: string
          example: 123 Main Street
        address2:
          type: string
          example: Apartment 1
        city:
          type: string
          example: Any Town
        province:
          type: string
          description: State or Province
          example: KS
        postal_code:
          type: string
          example: '12345'
        country:
          type: string
          example: US
        dob:
          type: string
          description: Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.
          example: '1981-04-23'
        anniversary:
          type: string
          description: Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone.  Anniversary date in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.
          example: '2025-07-21'
        email:
          type: string
          example: tobias@example.com
        phone:
          type: string
          example: +1 (555) 123-4567
        custom1:
          type: string
          description: Custom field for additional information about the recipient
          example: Unique Info
        custom2:
          type: string
          description: Custom field for additional information about the recipient
          example: For example a product code or customer ID
        custom3:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom4:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom5:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom6:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom7:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom8:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom9:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        custom10:
          type: string
          description: Custom field for additional information about the recipient
          example: Any Extra Info
        absentee_address:
          $ref: '#/components/schemas/absentee-address'
        absentee_city:
          $ref: '#/components/schemas/absentee-city'
        absentee_province:
          $ref: '#/components/schemas/absentee-province'
        absentee_postal_code:
          $ref: '#/components/schemas/absentee-postal-code'
        mailing-list:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/mailing-list'
          description: The mailing list this recipient belongs to
        created_at:
          readOnly: true
          type: string
          example: '2025-06-27T14:57:11.000000Z'
        updated_at:
          readOnly: true
          type: string
          example: '2025-06-27T14:57:11.000000Z'
    absentee-city:
      type: string
      description: City of the absentee (property) address. Requires `absentee_address` in the same request.
      example: Springfield
    absentee-address:
      type: string
      description: The property (absentee) address for this recipient, such as a house an absentee owner owns, as opposed to where they get mail. Give either the whole address here, or the street line here with `absentee_city`, `absentee_province` and `absentee_postal_code`. When set, the `~ABSENTEE_STREET~`, `~ABSENTEE_FULL_ADDRESS~`, `~FULL_ADDRESS~` and `~STREET_VIEW~` image template variables, and `%ABSENTEE_STREET%` in messages, use this address instead of the mailing address. The mailer is still delivered to `address`. Include the city, state and ZIP so Street View finds the right property. It is stored and returned in its own `absentee_address` field, and also copied into `custom2` when that is empty, so templates that print `%CUSTOM2%` keep working; a `custom2` you send is never changed. The older convention of `custom1` = `absentee` with `custom2` = the property address is still accepted and copied into `absentee_address`.
      example: 742 Evergreen Terrace
    absentee-postal-code:
      type: string
      description: ZIP or postal code of the absentee (property) address. Requires `absentee_address` in the same request.
      example: '62704'
    absentee-province:
      type: string
      description: State or province of the absentee (property) address. Requires `absentee_address` in the same request.
      example: IL
    mailing-list:
      type: object
      properties:
        id:
          type: integer
          example: 1
        user_id:
          type: integer
          example: 2
        sub_account_id:
          type:
          - integer
          - 'null'
        type:
          type: string
          example: manual
          enum:
          - csv
          - manual
          - map
          - friends
          - retarget
          - leads
          - zapier
          - radius
          - highlevel
          - qrscans
        description:
          type: string
          example: Test
        qrcode_url:
          type:
          - string
          - 'null'
        total_recipients:
          type: integer
          example: 1
        processed:
          type: boolean
          example: true
        is_suppression_list:
          type: boolean
          example: false
        total_scans:
          type: integer
          example: 0
        unique_scans:
          type: integer
          example: 0
        last_scan:
          type:
          - string
          - 'null'
        total_sends:
          type: integer
          example: 0
        last_send:
          type:
          - string
          - 'null'
        api_key:
          type: string
          description: API key that can be used to add recipients to this mailing list with thanks.io Webhooks
          example: abcd1234efgh5678ijkl9012mnop3456
        created_at:
          type: string
          example: '2018-07-15T06:06:57.000000Z'
          format: date-time
        created_at_diff:
          type: string
          example: 6 years ago
          description: Human-friendly relative time since creation
        updated_at:
          type: string
          example: '2025-06-27T14:57:11.000000Z'
          format: date-time
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Not Found
    MailingListDoesNotExist:
      description: The specified mailing list does not exist
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Mailing List Does Not Exist
    Unauthorized:
      description: Access token is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
  examples:
    recipient-example:
      summary: Example Recipient
      value:
        id: 18113288
        mailing_list_id: 1
        name: Tobias Example
        company: thanks.io
        address: 12345 Main Street
        address2: Apartment 1
        city: Any Town
        province: NY
        postal_code: '12345'
        country: US
        dob: '1981-04-23'
        anniversary: '2025-07-21'
        email: tobias@example.com
        phone: 845-988-6485
        custom1: Unique Info
        custom2: For example a product code or customer ID
        custom3: ''
        custom4: ''
        created_at: '2025-06-27T14:57:11.000000Z'
        updated_at: '2025-06-27T14:57:11.000000Z'
        mailing_list:
          id: 1
          user_id: 2
          sub_account_id: null
          type: manual
          description: Sphere Contacts Mailing List
          qrcode_url: null
          total_recipients: 1
          processed: true
          is_suppression_list: false
          total_scans: 1
          unique_scans: 1
          last_scan: '2025-07-13T13:57:11.000000Z'
          total_sends: 2
          last_send: '2025-07-06T13:57:11.000000Z'
          created_at: 6 years ago
          updated_at: '2025-06-27T14:57:11.000000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your thanks.io API key
externalDocs:
  description: Learn more about thanks.io
  url: https://docs.thanks.io
x-mint:
  mcp:
    enabled: true
x-mcp:
  enabled: true