Skip to main content
POST
Estimate Postcard

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

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.

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:
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 front of postcard. Use a template of the matching type: postcard for 4x6, postcard6x9 for 6x9, postcard6x11 for 6x11. A 6x9 send also accepts a postcard template. Required if front_image_url is not specified.

Example:

6

front_image_url
string

URL to image to use for front of postcard. Must be 1875px by 1275px for 4x6 postcards, 2738px by 1838px for 6x9 postcards, or 3337px by 1777px for 6x11 postcards. Required if image_template_id is not specified.

Example:

"https://cdn.thanks.io/letter-backgrounds/bg0.png"

message
string

Handwritten message content used for content on back of postcard.

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 content on back of postcard. Use a template of the matching type: postcard for 4x6, postcard6x9 for 6x9, postcard6x11 for 6x11. A 6x9 send also accepts a postcard template.

Example:

12

use_custom_background
boolean
default:false

Use custom background image. This can be used to turn off the default background image.

custom_background_image
string

URL to custom background image to use for back of postcard. This image will be placed behind the handwritten message. Must be 1875px by 1275px for 4x6 postcards, 2738px by 1838px for 6x9 postcards, or 3337px by 1777px for 6x11 postcards.

Example:

"https://cdn.thanks.io/letter-backgrounds/bg0.png"

qrcode_url
string

URL to Autogenerate QR Code on back of postcard. If not specified, account default QR code URL will be used.

Example:

"https://www.google.com"

size
enum<string>
default:4x6

Size of the postcard. A 6x9 postcard is placed as a postcard6x9 order and a 6x11 postcard as a postcard6x11 order.

Available options:
4x6,
6x9,
6x11

Response

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

message
string
Example:

"OK"

data
object