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

# Send Windowless Letter

> Send a letter in a windowless envelope.



## OpenAPI

````yaml post /send/windowlessletter
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:
  /send/windowlessletter:
    post:
      tags:
        - Send Mailer
      summary: Send Windowless Letter
      description: Send a letter in a windowless envelope.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/send-mailer-base'
                - type: object
                  properties:
                    image_template_id:
                      type: integer
                      description: >-
                        ID of image template to use for the background of the
                        cover letter. If neither image_template_id nor
                        front_image_url is specified, a blank background will be
                        used.
                      example: 6
                    front_image_url:
                      type: string
                      description: >-
                        URL to image to use for the background of the cover
                        letter. If neither image_template_id nor front_image_url
                        is specified, a blank background will be used.
                      example: >-
                        https://d2md0c8rpvzmz5.cloudfront.net/letter-backgrounds/bg0.png
                    message:
                      type: string
                      description: Handwritten message content used for cover letter.
                      example: >-
                        Hey %FIRST_NAME%!,


                        THANK YOU for allowing us the opportunity to HELP you
                        with your plan!
                    message_template_id:
                      type: integer
                      description: ID of message template to use for cover letter.
                      example: 12
                    qrcode_url:
                      type: string
                      description: URL to Autogenerate QR Code on cover letter.
                      example: https://www.google.com
                    additional_pages_url:
                      type: string
                      description: >-
                        URL to additional pages to include with the cover
                        letter.
                      example: >-
                        https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
                    pdf_only_url:
                      type: string
                      description: >-
                        URL to PDF file to use for entire mailer.  IF this is
                        specified, no cover letter is generated.
                      example: >-
                        https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
            examples:
              Image URL & Recipients:
                summary: Windowless Letter with Custom Image and Recipients
                description: >-
                  Example of sending a windowless letter using a custom front
                  image URL, handwritten message, and an array of recipients
                  with custom fields.
                value:
                  front_image_url: >-
                    https://d2md0c8rpvzmz5.cloudfront.net/letter-backgrounds/bg0.png
                  message: >-
                    Hey %FIRST_NAME%!,


                    THANK YOU for allowing us the opportunity to HELP you with
                    your plan!
                  handwriting_style_id: 4
                  recipients:
                    - name: Current Resident
                      address: 123 Main Street
                      city: Fake City
                      province: NY
                      postal_code: '55555'
                      country: US
                      custom1: Example Custom 1
                      custom2: Example Custom 2
                      custom3: Example Custom 3
                      custom4: Example Custom 4
                    - name: Jane Doe
                      address: 456 Another St
                      city: Fake City
                      province: NY
                      postal_code: '55555'
                      country: US
              PDF File Only:
                summary: Windowless Letter with PDF File Only
                description: >-
                  Example of sending a windowless letter with a PDF file
                  attachment, targeting specific mailing lists.
                value:
                  pdf_only_url: >-
                    https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
                  mailing_list_ids:
                    - 5166
                    - 514
              'Templates & QR Code ':
                summary: >-
                  Windowless Letter with Templates, QR Code, and Additional
                  PPages
                description: >-
                  Example of sending a windowless letter using predefined image
                  and message templates, targeting specific mailing lists, and
                  including a QR code for recipient engagement.
                value:
                  image_template_id: 6
                  message_template_id: 12
                  qrcode_url: https://www.google.com
                  mailing_list_ids:
                    - 5166
                    - 514
                  additional_pages_url: >-
                    https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
              Radius Search:
                summary: Windowless Letter with Radius Search Targeting
                description: >-
                  Example of sending a windowless letter using radius search to
                  automatically find and target recipients within a specific
                  geographic area, with custom message and image URL.
                value:
                  front_image_url: >-
                    https://d2md0c8rpvzmz5.cloudfront.net/letter-backgrounds/bg0.png
                  message: >-
                    Hey %FIRST_NAME%!,


                    THANK YOU for allowing us the opportunity to HELP you with
                    your plan!
                  radius_search:
                    address: 123 Main Street, Fake City, NY, 55555
                    record_types: likelytomove
                    record_count: 10
                    include_condos: false
                    append_data: true
              Preview:
                summary: Preview windowless Letter Before Sending
                description: >-
                  Example of generating a preview of a windowless letter before
                  actually sending it. Use the preview parameter to see how your
                  letter will look without placing an actual order.
                value:
                  front_image_url: >-
                    https://d2md0c8rpvzmz5.cloudfront.net/letter-backgrounds/bg0.png
                  message: >-
                    Hey %FIRST_NAME%!,


                    THANK YOU for allowing us the opportunity to HELP you with
                    your plan!
                  handwriting_style_id: 4
                  preview: true
                  recipients:
                    - name: Current Resident
                      address: 123 Main Street
                      city: Fake City
                      province: NY
                      postal_code: '55555'
                      country: US
                      custom1: Example Custom 1
                      custom2: Example Custom 2
                      custom3: Example Custom 3
                      custom4: Example Custom 4
                    - name: Jane Doe
                      address: 456 Another St
                      city: Fake City
                      province: NY
                      postal_code: '55555'
                      country: US
      responses:
        '200':
          description: Send Mailer Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/send-mailer-order-response'
                  - $ref: '#/components/schemas/send-mailer-preview-response'
              examples:
                Order Submitted Response:
                  summary: Order Submitted Response Example
                  value:
                    total_estimated_recipients: 1
                    authorization_total: 112
                    leads_fee: 0
                    mailing_list_ids_used: ''
                    additional_letter_pages_count: 0
                    handwriting_color: rgba(31,0,113,0.80)
                    front_image: >-
                      https://d2md0c8rpvzmz5.cloudfront.net/letter-backgrounds/bg0.png
                    message: >-








                      What is Lorem Ipsum? Lorem Ipsum is simply dummy text of
                      the printing and typesetting industry. Lorem Ipsum has
                      been the industry's standard dummy text ever since the
                      1500s, when an unknown printer took a galley of type and
                      scrambled it to make a type specimen book. It has survived
                      not only five centuries, but also the leap into electronic
                      typesetting, remaining essentially unchanged. It was
                      popularised in the 1960s with the release of Letraset
                      sheets containing Lorem Ipsum passages, and more recently
                      with desktop publishing software like Aldus PageMaker
                      including versions of Lorem Ipsum. Why do we use it? It is
                      a long established fact that a reader will be distracted
                      by the readable content of a page when looking at its
                      layout. The point of using Lorem Ipsum is that it has a
                      more-or-less normal distribution of letters, as opposed to
                      using 'Content here, content here', making it look like
                      readable English. Many desktop publishing packages and web
                      page editors now use Lorem Ipsum as their default model
                      text, and a search for 'lorem ipsum' will uncover many web
                      sites still in their infancy. Various versions have
                      evolved over the years, sometimes by accident, sometimes
                      on purpose (injected humour and the like).
                    append_or_current_resident: true
                    type: windowlessletter
                    return_name: Custom Return
                    return_address: 1 Main Street
                    return_address2: Unit 1
                    return_city: Woodbridge
                    return_province: NJ
                    return_postal_code: '07095'
                    message_template_id: null
                    image_template_id: null
                    method: api
                    sub_account_id: null
                    font_size: auto
                    qrcode_url: null
                    custom_background_url: null
                    giftcard_brand: null
                    giftcard_image: null
                    giftcard_amount: null
                    status: reviewing
                    addons:
                      standardmail: 'on'
                    style: 5
                    user_id: 2
                    updated_at: '2025-08-15 03:50:51'
                    created_at: '2025-08-15 03:50:51'
                    id: 42676
                    display_status: Reviewing
                    display_trigger: API
                    display_type: Windowless Letter
                    giftcard_brand_longname: ''
                    sub_account: null
                    recipients:
                      - name: Current Resident
                        address: 1 Main Street
                        city: Anytown
                        province: NY
                        postal_code: '55555'
                        country: US
                        address2: ''
                Preview Response:
                  summary: Preview Response Example
                  value:
                    success: true
                    code: 200
                    message: OK
                    data:
                      previews:
                        - >-
                          https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/9f0bddc8-7dd1-7b1c-8d7e-d9f20084ec5d.png
        '400':
          $ref: '#/components/responses/UserError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/UnknownError'
components:
  schemas:
    send-mailer-base:
      type: object
      properties:
        preview:
          type: boolean
          description: >-
            Set to true to return a preview instead of sending the mail piece.
            You can use this with any send call to inspect the output before
            submitting the order.
          example: true
        mailing_list_ids:
          type: array
          description: >-
            Mailing list IDs to send to. Required if `recipients` and
            `radius_search` are not provided.
          items:
            type: integer
          example:
            - 5166
            - 514
        recipients:
          type: array
          description: >-
            Recipients to send to. Required if `mailing_list_ids` and
            `radius_search` are not provided.
          items:
            $ref: '#/components/schemas/recipient-create-no-mailinglist'
        radius_search:
          type: object
          description: >-
            Use a radius search to find recipients near an address. Required if
            `mailing_list_ids` and `recipients` are not provided. Lookup fees
            are $0.05 per record.
          properties:
            preview:
              type: boolean
              description: >-
                Return a preview of the number of matching recipients and the
                estimated cost.
              default: false
            address:
              type: string
              example: 123 Main Street, Fake City, NY, 55555
              description: >-
                Full street address to use as the center point of the
                nearest-neighbor search.
            record_count:
              type: integer
              description: Number of nearby records to return.
              minimum: 1
              maximum: 10000
              example: 1
            record_types:
              type: string
              description: Record type to search for
              enum:
                - all
                - likelytomove
                - likelytorefi
                - absenteeowner
                - highnetworth
                - majorityhomeequity
                - homefreeclear
                - underwater
                - kidsinhousehold
                - newhomeowner
                - firsttimehomebuyer
                - renters
                - retiring
                - retired
                - pool
                - onlybusinesses
                - newbusiness
              default: all
            include_condos:
              type: boolean
              description: Include condos in search.
              default: false
            append_data:
              type: boolean
              description: >-
                Append phone and email to each record for an additional fee
                ($.20 per record).
              default: false
            use_property_owner:
              type: boolean
              description: >-
                Use the property owner's address when searching commercial
                records.
              default: false
            include_search_address:
              type: boolean
              description: >-
                Set to true to include the search address in the generated
                mailing list.
        handwriting_style_id:
          type: integer
          description: ID of handwriting style to use.
          example: 4
        handwriting_color:
          type: string
          description: >-
            Handwriting color to use. Options are preset named colors or
            specified as hex format, such as '#4287f5'
          enum:
            - blue
            - black
            - green
            - purple
            - red
          examples:
            - blue
            - '#4287f5'
        handwriting_realism:
          type: boolean
          description: Set to true to enable the realism effect for AI fonts.
          example: true
        sub_account:
          type: integer
          description: Sub-account ID to use for this order.
          example: 7
        notification_emails:
          type: string
          description: >-
            Optional comma-separated list of email addresses to notify about
            order events such as QR scan notifications.
          example: ops@example.com,sales@example.com
        send_standard_mail:
          type: boolean
          description: >-
            Set to true to use Standard Mail postage. If false or omitted, First
            Class postage is used.
          default: false
        return_name:
          type: string
          description: Custom return name for the order.
          example: Custom Return
        return_address:
          type: string
          description: Custom return address for the order.
          example: 1 Main Street
        return_address2:
          type: string
          description: Custom return address line 2 for the order.
          example: Unit 1
        return_city:
          type: string
          description: Custom return city for the order.
          example: Woodbridge
        return_state:
          type: string
          description: Custom return state/province for the order.
          example: NJ
        return_postal_code:
          type: string
          description: Custom return postal code for the order.
          example: '07095'
    send-mailer-order-response:
      type: object
      title: Send Mailer Order Submitted Response
      description: Response when an Order is successfully submitted to Send Mailer
      properties:
        id:
          type: integer
          description: Unique identifier for the order
          example: 42664
        user_id:
          type: integer
          description: User ID for the order
          example: 2
        sub_account:
          description: Sub-account Info For Order.  Can be null
          allOf:
            - $ref: '#/components/schemas/sub-account'
          type:
            - object
            - 'null'
        sub_account_id:
          type:
            - integer
            - 'null'
          description: Sub account ID for the order
          example: 12345
        total_estimated_recipients:
          type: integer
          description: Total estimated recipients for the order
          example: 1
        authorization_total:
          type: integer
          description: Total authorization amount for the order in cents
          example: 58
        leads_fee:
          type: integer
          description: Total leads fee for the order in cents
          example: 99
        mailing_list_ids_used:
          type: string
          description: >-
            Mailing lists used for the order.  Can be null if recipients or
            radius search is used.
          example: 3046,3020
        recipients:
          type: array
          description: List of recipients for the order
          items:
            $ref: '#/components/schemas/recipient-no-mailinglist'
        front_image:
          type: string
          description: Front image URL for the order
          example: >-
            https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png
        image_template_id:
          type:
            - integer
            - 'null'
          description: Image template ID for the order
          example: 6
        custom_background_url:
          type:
            - string
            - 'null'
          description: Custom background URL for the order
          example: >-
            https://s3.amazonaws.com/content-staging.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/4524cce0-78cb-11f0-b937-17570cbedaf4.png
        message:
          type: string
          description: Message content for the order
          example: >-
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
            ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
            aliquip ex ea commodo consequat. Duis aute irure dolor in
            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
            pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
            culpa qui officia deserunt mollit anim id est laborum.
        message_template_id:
          type:
            - integer
            - 'null'
          description: Message template ID for the order
          example: 12345
        handwriting_color:
          type: string
          description: Handwriting color to use
          example: rgba(31,0,113,0.80)
        font_size:
          type: string
          description: Font size for the order
          enum:
            - auto
            - small
            - medium
            - large
          example: auto
        style:
          type: integer
          description: Handwriting style ID for the order
          example: 4
        append_or_current_resident:
          type: boolean
          description: >-
            Appended "Or Current Resident" for the order.  This is helpful if
            you want to ensure delivery.
          example: false
        return_name:
          type:
            - string
            - 'null'
          description: Return name for the order
          example: John Doe
        return_address:
          type:
            - string
            - 'null'
          description: Return address line 1 for the order
          example: 123 Main Street
        return_address2:
          type:
            - string
            - 'null'
          description: Return address line 2 for the order
          example: null
        return_city:
          type:
            - string
            - 'null'
          description: Return city for the order
          example: Anytown
        return_province:
          type:
            - string
            - 'null'
          description: Return state/province for the order
          example: NY
        return_postal_code:
          type:
            - string
            - 'null'
          description: Return postal code for the order
          example: '12345'
        type:
          type: string
          description: Type of the order
          enum:
            - postcard
            - postcard6x11
            - letter
            - notecard
            - giftcard
            - windowlessletter
          example: postcard
        size:
          type: string
          description: Size of the order (valid for postcards only)
          enum:
            - 4x6
            - 6x9
            - 6x11
          example: 4x6
        method:
          type: string
          description: Method for the order
          enum:
            - api
            - cardbuilder
            - drip
            - email
            - zapier
        status:
          type: string
          description: Status of the order
          enum:
            - reviewing
            - processing
            - fulfilled
            - cancelled
            - printed
            - shipped
            - paused
            - delivered
        display_status:
          type: string
          description: Display status for the order
          example: Reviewing
        display_trigger:
          type: string
          description: Display trigger for the order
          example: API
        display_type:
          type: string
          description: Display type for the order
          example: Postcard-4x6
        addons:
          type:
            - object
            - 'null'
          description: Add-ons for the order
          properties:
            standardmail:
              type: string
              description: Standard mail add-on status
              enum:
                - 'on'
                - 'off'
              example: 'on'
        qrcode_url:
          type:
            - string
            - 'null'
          description: QR code URL for the order
          example: >-
            https://www.google.com?name=~FULL_NAME~&custom_field_1=~CUSTOM1~&custom_field2=~CUSTOM2~
        giftcard_brand:
          type:
            - string
            - 'null'
          description: Gift card brand for the order (valid for Giftcard orders only)
          example: null
        giftcard_image:
          type:
            - string
            - 'null'
          description: Gift card image URL for the order (valid for Giftcard orders only)
          example: null
        giftcard_amount:
          type:
            - integer
            - 'null'
          description: >-
            Gift card amount for the order in cents (valid for Giftcard orders
            only)
          example: null
        giftcard_brand_longname:
          type: string
          description: >-
            Gift card brand long name for the order (valid for Giftcard orders
            only)
          example: Amazon.com
        updated_at:
          type: string
          format: date-time
          description: Last updated timestamp for the order
          example: '2025-08-14 16:42:44'
        created_at:
          type: string
          format: date-time
          description: Creation timestamp for the order
          example: '2025-08-14 16:42:44'
    send-mailer-preview-response:
      type: object
      title: Send Mailer Preview Response
      description: Preview image URLs returned when `preview` is set to `true`.
      properties:
        message:
          type: string
          example: OK
          description: Response message
        data:
          type: object
          description: Preview data containing image URLs
          properties:
            previews:
              type: array
              description: Array of preview image URLs
              items:
                type: string
                format: uri
                example: https://s3.amazonaws.com/cdn.thanks.io/preview/12345.png
    recipient-create-no-mailinglist:
      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:
        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'
    sub-account:
      type: object
      properties:
        id:
          type: integer
          example: 1
        user_id:
          type: integer
          example: 2
        title:
          type: string
          example: My Sub Account
        return_name:
          type: string
          example: John Smith
        return_address:
          type: string
          example: 123 Smith Street
        return_address2:
          type: string
          example: Apartment 2
        return_city:
          type: string
          example: Denver
        return_state:
          type: string
          example: CO
        return_postal_code:
          type: string
          example: '12345'
    recipient-no-mailinglist:
      type: object
      properties:
        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:
      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:
    UserError:
      description: User error occurred
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Sub Account ID does not exist
    Unauthorized:
      description: Access token is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
    UnknownError:
      description: An unknown error occurred
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Error Submitting Mailer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your thanks.io API key

````