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.

​

Overview

Use the Send Mailer endpoints when your application needs to create direct mail orders on demand. These endpoints create the orders that are processed and fulfilled by thanks.io. If your users should manage campaign timing, creatives, and automation rules inside thanks.io, start with the campaign workflow instead of these direct-send endpoints.

​

Before You Start

Before using these endpoints, make sure you have:

• A valid API key or OAuth access token. See Bearer Token and OAuth.
• Enabled API Testing Mode while validating your integration.
• Decided whether you are sending to explicit recipients, a saved mailing list, or a radius search audience.

​

Which Endpoint Should I Use?

Choose the endpoint that matches the mailpiece you want to create: All of these endpoints follow the same core pattern: define the audience, provide creative content, and submit the order.

​

Preview

Any order can be previewed by setting the preview parameter to true. The response will return links to PNG previews of the mailer instead of creating a production order.

​

Requirements

In general, all mailers require recipients. Creative content is required unless you provide message content or use pdf_only_url, and the exact requirements vary by mailpiece type. The main exception is a letter created from a PDF only. In that case, you only need recipients and pdf_only_url, and you do not need front_image_url or image_template.

​

Recipients

Recipients can be specified in a variety of ways:

• Specify an existing mailing list using the mailing_lists field.
• Provide recipient addresses as JSON data directly in the recipients field.
• Buy a list of recipients using a radius search with the radius_search field.

​

Front Image

For postcards, notecards, magnacards, and gift cards, this is used for the front of the mailer. For windowed and windowless letters, this is used for the background of the cover letter unless you are sending a PDF-only letter. The creative can be specified in two ways:

• Use front_image_url to provide a PNG or JPEG image URL.
• Use image_template to provide a thanks.io image template ID.

If you provide image_template, you typically do not need front_image_url. If you provide message, a front creative is not required. If you provide pdf_only_url for a letter, you do not need either of these fields.

​

Back/Interior Image

• Use custom_background_image to provide a PNG or JPEG image URL for the back of postcards or magnacards, or the interior of notecards. This is not used for gift cards or letters.

​

Message

The message content specifies the content that the thanks.io handwriting engine places on the mailer. For postcards, this specifies the content for the back of the postcard. For notecards and gift cards, this specifies the interior content. For windowed and windowless letters, this specifies the cover letter content. In all cases, the message content is overlaid on top of the creative when applicable. The content can be specified in two ways:

• Use message to provide the text directly.
• Use message_template to reference a thanks.io message template. Message templates can include QR codes and handwriting settings.

​

Standard Mail

By default, mail is sent via first class. Use the send_standard_mail field if you want to send the order via standard mail instead.

​

Handwriting

The handwriting style can be customized using the handwriting_style, handwriting_color, and handwriting_realism fields.

​

QR Codes

Trackable QR codes can be included in mailers with the qrcode_url field to monitor engagement and response rates. thanks.io can notify you of each scan by email or text message, and an analytics dashboard is available to help you track template performance.