> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thanks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Recipients

> Retrieve recipients for a specific mailing list.



## OpenAPI

````yaml get /mailing-lists-utils/recipients/{mailingListId}
openapi: 3.1.0
info:
  title: thanks.io API
  description: >-
    Use the thanks.io API to send postcards, letters, notecards, windowless
    letters, and gift cards.
  contact:
    url: https://www.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
  - name: Mailing Lists
  - name: Send Mailer
  - name: Orders
  - name: Message Templates
  - name: Image Templates
  - name: Handwriting Styles
  - name: Giftcards
  - name: Dynamic Images
    description: ''
  - name: Image Builder
  - name: Sub Accounts
externalDocs:
  description: Learn more about thanks.io
  url: https://docs.thanks.io
paths:
  /mailing-lists-utils/recipients/{mailingListId}:
    get:
      tags:
        - Mailing Lists
      summary: List Recipients
      description: Retrieve recipients for a specific mailing list.
      parameters:
        - name: limit
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
            example: 1000
            maximum: 10000
            minimum: 1
        - name: updated_since
          in: query
          description: >-
            Return only recipients updated since this date/time. Format:
            YYYY-MM-DD HH:MM:SS
          schema:
            type: string
            example: '2020-04-06 01:55:50'
        - name: mailingListId
          in: path
          description: ID of mailing list
          required: true
          schema:
            type: integer
            example: 56
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        description: Array of recipient objects
                        items:
                          $ref: '#/components/schemas/recipient'
                  - $ref: '#/components/schemas/paginated'
              example:
                current_page: 1
                data:
                  - id: 293345
                    mailing_list_id: 514
                    session_id: null
                    name: John Doe
                    address: 123 Main Street
                    address2: null
                    city: Austin
                    province: TX
                    postal_code: '78703'
                    country: US
                    dob: null
                    custom1: null
                    custom2: null
                    deliverability: null
                    can_deliver: true
                    created_at: '2020-03-10 13:33:04'
                    updated_at: '2020-04-06 01:57:50'
                first_page_url: >-
                  http://api.thanks.io/api/v2/mailing-lists/514/recipients?page=1
                from: 1
                last_page: 1
                last_page_url: >-
                  http://api.thanks.io/api/v2/mailing-lists/514/recipients?page=1
                next_page_url: null
                path: http://api.thanks.io/api/v2/mailing-lists/514/recipients
                per_page: '1000'
                prev_page_url: null
                to: 1
                total: 1
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
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: www.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'
        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
        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'
    paginated:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
          description: Current page number
        first_page_url:
          type:
            - string
            - 'null'
          description: URL of the first page of results
          example: >-
            https://api.thanks.io/api/v2/mailing-lists-utils/recipients/3014?page=1
        from:
          type: integer
          example: 1
          description: Index of the first item on the current page
        last_page:
          type: integer
          example: 1
          description: Total number of pages
        last_page_url:
          type:
            - string
            - 'null'
          description: URL of the last page of results
          example: >-
            https://api.thanks.io/api/v2/mailing-lists-utils/recipients/3014?page=1
        next_page_url:
          type:
            - string
            - 'null'
          description: URL of the next page of results
        path:
          type: string
          description: Base URL for the resource
          example: https://api.thanks.io/api/v2/mailing-lists-utils/recipients/3014
        per_page:
          type: integer
          example: 50
          description: Number of items per page
        prev_page_url:
          type:
            - string
            - 'null'
          description: URL of the previous page of results
        to:
          type: integer
          example: 12
          description: Index of the last item on the current page
        total:
          type: integer
          example: 12
          description: Total number of items
    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:
    Unauthorized:
      description: Access token is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Not Found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your thanks.io API key

````