> ## 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.

# Create Multiple Recipients

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



## OpenAPI

````yaml post /recipients-utils/create-multiple
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:
  /recipients-utils/create-multiple:
    post:
      tags:
        - Recipients
      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.
      operationId: createMultipleRecipients
      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
                  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
                  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
                  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.
components:
  schemas:
    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: 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'
    recipient-array:
      type: array
      description: Array of recipient objects
      items:
        $ref: '#/components/schemas/recipient'
    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
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your thanks.io API key

````