Send Mailer

Send Windowed Letter

Changed on

Send a letter in a windowed envelope.

post/send/windowedletter

Request

  • Base URL: https://api.thanks.io/api/v2
  • URL: https://api.thanks.io/api/v2/send/windowedletter
  • Auth: HTTP bearer

Request body

previewboolean

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. On the Free and Business plans, preview images carry a DRAFT watermark; the mail you send never does. Professional and Enterprise previews have no watermark.

mailing_list_idsinteger[]

Mailing list IDs to send to. Required if recipients and radius_search are not provided.

handwriting_style_idinteger

ID of handwriting style to use.

handwriting_color'blue' | 'black' | 'green' | 'purple' | 'red'

Handwriting color to use. Options are preset named colors or specified as hex format, such as '#4287f5'

handwriting_realismboolean

Set to true to enable the realism effect for AI fonts.

sub_accountinteger

Sub-account ID to use for this order.

notification_emailsstring

Optional comma-separated list of email addresses to notify about order events such as QR scan notifications.

email_lookupboolean

Whether a recipient given an email but no street address has their postal address looked up from the email. Each address found is charged as an Email to Address lookup. Defaults to true. Set to false to skip the lookup: recipients without a street address are then left out of the order, which mails only the recipients that have one. Estimates never run the lookup and price such recipients as if found.

postage_class'first_class' | 'standard'

Postage class for this order. first_class mails First Class. standard mails Standard Mail (also known as Marketing Mail): lower cost for US addresses and slower to deliver, with no tracking status and no return-to-sender. Omit it to use your account's default, set with Standard Mail Mode under Settings > Mail Preferences. Standard Mail only changes the price of US addresses. Nonprofit accounts always mail at their nonprofit rate. standard needs a paid plan: free plan accounts always mail First Class, and standard from one is rejected with a 422.

return_namestring

Custom return name for the order.

return_addressstring

Custom return address for the order.

return_address2string

Custom return address line 2 for the order.

return_citystring

Custom return city for the order.

return_statestring

Custom return state/province for the order.

return_postal_codestring

Custom return postal code for the order.

metadataobject nullable

Your own key/value data to store with the order. It is returned unchanged by the order endpoints and included in every webhook event for the order as order.metadata. Must be a JSON object rather than an array, and no larger than 8,192 bytes once encoded as JSON. thanks.io does not print or otherwise act on these values.

creative_idinteger

Recommended: send a saved creative instead of assembling image and message parameters per request. ID of a creative from your Creatives library (see List Creatives). The creative is sent exactly as saved: its image template, message template, handwriting and background all come from it. It cannot be combined with any parameter that changes those (image_template_id, message_template_id, front_image_url, message, the handwriting and custom background parameters, pdf_only_url, skip_creative_generation, or for gift cards giftcard_brand and giftcard_amount_in_cents); a request that does is rejected with a 422 naming them. Only qrcode_url and additional_pages_url can be added. The creative must belong to your account, be of the mailer type being sent (for postcards, the size being sent), and be complete (is_complete: true).

image_template_idinteger

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.

front_image_urlstring

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.

messagestring

Handwritten message content used for cover letter.

message_template_idinteger

ID of message template to use for cover letter.

qrcode_urlstring

URL to Autogenerate QR Code on cover letter.

additional_pages_urlstring

URL to additional pages to include with the cover letter.

pdf_only_urlstring

URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. Do not include the recipient's address in your PDF: thanks.io prints each recipient's name and address in the upper-left area of page 1, where it shows through the envelope window. Leave that area blank; an address already in the PDF is printed over.

Example request

{
  "preview": true,
  "mailing_list_ids": [
    5166,
    514
  ],
  "recipients": [
    {
      "name": "Tobias Example",
      "company": "thanks.io",
      "address": "123 Main Street",
      "address2": "Apartment 1",
      "city": "Any Town",
      "province": "KS",
      "postal_code": "12345",
      "country": "US",
      "dob": "1981-04-23",
      "anniversary": "2025-07-21",
      "email": "tobias@example.com",
      "phone": "+1 (555) 123-4567",
      "custom1": "Unique Info",
      "custom2": "For example a product code or customer ID",
      "custom3": "Any Extra Info",
      "custom4": "Any Extra Info",
      "custom5": "Any Extra Info",
      "custom6": "Any Extra Info",
      "custom7": "Any Extra Info",
      "custom8": "Any Extra Info",
      "custom9": "Any Extra Info",
      "custom10": "Any Extra Info",
      "absentee_address": "742 Evergreen Terrace",
      "absentee_city": "Springfield",
      "absentee_province": "IL",
      "absentee_postal_code": "62704",
      "mailing-list": {
        "id": 1,
        "user_id": 2,
        "type": "manual",
        "description": "Test",
        "total_recipients": 1,
        "processed": true,
        "api_key": "abcd1234efgh5678ijkl9012mnop3456",
        "created_at": "2018-07-15T06:06:57.000000Z",
        "created_at_diff": "6 years ago",
        "updated_at": "2025-06-27T14:57:11.000000Z"
      },
      "created_at": "2025-06-27T14:57:11.000000Z",
      "updated_at": "2025-06-27T14:57:11.000000Z"
    }
  ],
  "radius_search": {
    "address": "123 Main Street, Fake City, NY, 55555",
    "record_count": 1
  },
  "handwriting_style_id": 4,
  "handwriting_color": "blue",
  "handwriting_realism": true,
  "sub_account": 7,
  "notification_emails": "ops@example.com,sales@example.com",
  "postage_class": "standard",
  "return_name": "Custom Return",
  "return_address": "1 Main Street",
  "return_address2": "Unit 1",
  "return_city": "Woodbridge",
  "return_state": "NJ",
  "return_postal_code": "07095",
  "metadata": {
    "crm_deal_id": "D-1042",
    "campaign": "spring-winback",
    "source": "hubspot"
  },
  "creative_id": 501,
  "image_template_id": 6,
  "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png",
  "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!",
  "message_template_id": 12,
  "qrcode_url": "https://www.google.com",
  "additional_pages_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "pdf_only_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
}

Response

Send Mailer Success

OR

Example response

{
  "id": 42664,
  "user_id": 2,
  "sub_account": {
    "id": 1,
    "user_id": 2,
    "title": "My Sub Account",
    "return_name": "John Smith",
    "return_address": "123 Smith Street",
    "return_address2": "Apartment 2",
    "return_city": "Denver",
    "return_state": "CO",
    "return_postal_code": "12345"
  },
  "sub_account_id": 12345,
  "total_estimated_recipients": 1,
  "authorization_total": 58,
  "leads_fee": 99,
  "mailing_list_ids_used": "3046,3020",
  "recipients": [
    {
      "name": "Tobias Example",
      "company": "thanks.io",
      "address": "123 Main Street",
      "address2": "Apartment 1",
      "city": "Any Town",
      "province": "KS",
      "postal_code": "12345",
      "country": "US",
      "dob": "1981-04-23",
      "anniversary": "2025-07-21",
      "email": "tobias@example.com",
      "phone": "+1 (555) 123-4567",
      "custom1": "Unique Info",
      "custom2": "For example a product code or customer ID",
      "custom3": "Any Extra Info",
      "custom4": "Any Extra Info",
      "custom5": "Any Extra Info",
      "custom6": "Any Extra Info",
      "custom7": "Any Extra Info",
      "custom8": "Any Extra Info",
      "custom9": "Any Extra Info",
      "custom10": "Any Extra Info",
      "absentee_address": "742 Evergreen Terrace, Springfield, IL 62704"
    }
  ],
  "front_image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png",
  "image_template_id": 6,
  "custom_background_url": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/4524cce0-78cb-11f0-b937-17570cbedaf4.png",
  "message": "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": 12345,
  "handwriting_color": "rgba(31,0,113,0.80)",
  "font_size": "auto",
  "style": 4,
  "return_name": "John Doe",
  "return_address": "123 Main Street",
  "return_city": "Anytown",
  "return_province": "NY",
  "return_postal_code": "12345",
  "type": "postcard",
  "size": "4x6",
  "display_status": "Reviewing",
  "display_trigger": "API",
  "display_type": "Postcard-4x6",
  "addons": {
    "standardmail": "on"
  },
  "qrcode_url": "https://www.google.com?name=~FULL_NAME~&custom_field_1=~CUSTOM1~&custom_field2=~CUSTOM2~",
  "giftcard_brand_longname": "Amazon.com",
  "metadata": {
    "crm_deal_id": "D-1042",
    "campaign": "spring-winback",
    "source": "hubspot"
  },
  "updated_at": "2025-08-14 16:42:44",
  "created_at": "2025-08-14 16:42:44"
}

Changes

  • c403fbf3dc0fRevision changes
    • info

      added the new optional request property ////

  • bbe02ffe74f3Revision changes
    • info

      added the optional property /// to the response with the status