Estimate Windowless Letter

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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!',
    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'
      }
    ]
  })
};

fetch('https://api.thanks.io/api/v2/estimate/windowlessletter', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.thanks.io/api/v2/estimate/windowlessletter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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!",
  "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"
    }
  ]
}
'

import requests

url = "https://api.thanks.io/api/v2/estimate/windowlessletter"

payload = {
    "front_image_url": "https://cdn.thanks.io/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"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "OK",
  "data": {
    "type": "windowlessletter",
    "size": null,
    "total_recipients": 2,
    "recipients": {
      "united_states": 2,
      "international": 0
    },
    "pending_email_lookups": 0,
    "costs_in_cents": {
      "united_states": 236,
      "international": 0,
      "additional_pages": 0,
      "giftcard_face_value": 0,
      "grand_total": 236
    },
    "total_cost_in_cents": 236,
    "total_cost": "$2.36",
    "current_balance_in_cents": 5000,
    "covered_by_balance": true,
    "test_mode": false,
    "notes": []
  }
}

{
  "message": "Sub Account ID does not exist"
}

{
  "message": "Unauthorized"
}

{
  "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.",
  "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.",
  "code": "api_disabled_payment_failures"
}

Order Estimates

Estimate Windowless Letter

Price a windowless letter order without placing it. Send the same request body you would send to Send Windowless Letter: nothing is charged, nothing is printed or mailed, and no order is created.

The request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in pending_email_lookups. A radius_search is counted and priced, but no records are purchased.

POST

estimate

windowlessletter

Estimate Windowless Letter

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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!',
    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'
      }
    ]
  })
};

fetch('https://api.thanks.io/api/v2/estimate/windowlessletter', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.thanks.io/api/v2/estimate/windowlessletter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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!",
  "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"
    }
  ]
}
'

import requests

url = "https://api.thanks.io/api/v2/estimate/windowlessletter"

payload = {
    "front_image_url": "https://cdn.thanks.io/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"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "OK",
  "data": {
    "type": "windowlessletter",
    "size": null,
    "total_recipients": 2,
    "recipients": {
      "united_states": 2,
      "international": 0
    },
    "pending_email_lookups": 0,
    "costs_in_cents": {
      "united_states": 236,
      "international": 0,
      "additional_pages": 0,
      "giftcard_face_value": 0,
      "grand_total": 236
    },
    "total_cost_in_cents": 236,
    "total_cost": "$2.36",
    "current_balance_in_cents": 5000,
    "covered_by_balance": true,
    "test_mode": false,
    "notes": []
  }
}

{
  "message": "Sub Account ID does not exist"
}

{
  "message": "Unauthorized"
}

{
  "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.",
  "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.",
  "code": "api_disabled_payment_failures"
}

Authorizations

Authorization

string

header

required

Bearer token authentication using your thanks.io API key

Body

application/json

preview

boolean

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

integer[]

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

Example:

[5166, 514]

recipients

(Create Recipient by Address · object | Create Recipient by Email · object)[]

Recipients to send to. Required if mailing_list_ids and radius_search are not provided.

Create a recipient by providing address details

Create Recipient by Address
Create Recipient by Email

Show child attributes

radius_search

object

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.

Show child attributes

handwriting_style_id

integer

ID of handwriting style to use.

Example:

4

handwriting_color

enum<string>

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

Available options:

blue,

black,

green,

purple,

red

Examples:

"blue"

"#4287f5"

handwriting_realism

boolean

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

Example:

true

sub_account

integer

Sub-account ID to use for this order.

Example:

7

notification_emails

string

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

Example:

"ops@example.com,sales@example.com"

postage_class

enum<string>

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.

Available options:

first_class,

standard

Example:

"standard"

return_name

string

Custom return name for the order.

Example:

"Custom Return"

return_address

string

Custom return address for the order.

Example:

"1 Main Street"

return_address2

string

Custom return address line 2 for the order.

Example:

"Unit 1"

return_city

string

Custom return city for the order.

Example:

"Woodbridge"

return_state

string

Custom return state/province for the order.

Example:

"NJ"

return_postal_code

string

Custom return postal code for the order.

Example:

"07095"

metadata

object | null

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.

Example:

{
  "crm_deal_id": "D-1042",
  "campaign": "spring-winback",
  "source": "hubspot"
}

creative_id

integer

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

Example:

501

image_template_id

integer

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

string

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://cdn.thanks.io/letter-backgrounds/bg0.png"

message

string

Handwritten message content used for cover letter.

Example:

"Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!"

message_template_id

integer

ID of message template to use for cover letter.

Example:

12

qrcode_url

string

URL to Autogenerate QR Code on cover letter.

Example:

"https://www.google.com"

additional_pages_url

string

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

string

URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. The recipient's address is printed on the envelope, so do not include it in your PDF; the full page is available for your content.

Example:

"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"

Response

The order was priced. Nothing was charged and no order was created.

message

string

Example:

"OK"

data

object

Show child attributes

Get Started

Authentication

API Endpoints

Examples

Estimate Windowless Letter

Authorizations

Body

Response