Skip to main content

​
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. The recommended way to send is a complete creative from your Creatives library: design it once in your dashboard, then send it from your code with a single creative_id. See Send a Creative below. The per-request image and message parameters remain fully supported for dynamic content and custom pipelines. If your users should manage campaign timing, designs, 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, choose what prints, and submit the order.

​
Send a Creative

The recommended way to choose what prints is a creative from your Creatives library: a saved pairing of a front design (image template) and a message template. Pass the creative’s ID as creative_id and thanks.io sends it exactly as saved: the design, the message, its handwriting and its background all come from the creative.
Find creative IDs with List Creatives (GET /creatives), or copy one from the creative’s menu or preview in your dashboard. The order records which creative it was sent as. See Creatives Library for how creatives work. A send with creative_id is rejected with a 422 and an error on creative_id when:
  • It also sets a parameter that would change what the creative prints. To send a variation, save it as its own creative. These parameters can’t be combined with creative_id:
    • Front image: image_template_id (or image_template), front_image_url
    • Message: message, message_template_id (or message_template)
    • Handwriting: handwriting_style (or handwriting_style_id), handwriting_color, handwriting_size, handwriting_realism
    • Background: use_custom_background, custom_background_image
    • Letters: pdf_only_url, skip_creative_generation
    • Gift cards: giftcard_brand, giftcard_amount_in_cents
    Any other parameter that sets the front image, message, handwriting, or background is refused the same way. A parameter sent empty or null doesn’t count, so an integration that always sends every field can leave these blank.
  • The creative isn’t in your account, or was deleted.
  • The creative is a different mailer type from the endpoint. For postcards, the size counts too: a 6x9 send needs a postcard6x9 creative. Filter the list with mailer_type to find the right ones.
  • The creative is incomplete (is_complete: false): missing its front image or its message. Letters need only a message.
Two parameters can be added to a creative send: qrcode_url, to track the send with its own QR code, and, for letters, additional_pages_url.

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

​
Estimate

To see what an order will cost before you send it, post the same request body to the matching Order Estimates endpoint, such as /api/v2/estimate/postcard. The response returns the total, a cost breakdown, and whether your account balance covers it. Nothing is charged and no order is created.

​
Requirements

In general, all mailers require recipients. A creative_id satisfies both the front image and the message at once; otherwise a front image 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.
Each entry in recipients takes the same fields as a recipient: the address fields, name, company, email, phone, and custom1 through custom10. Set absentee_address (optionally with absentee_city, absentee_province, and absentee_postal_code) to a property address when the mailer is about a property the recipient doesn’t live at, so ~STREET_VIEW~ and ~ABSENTEE_STREET~ show that property while the mail still goes to address. See Absentee (property) address for the details. It can’t be combined with custom1 or custom2.

​
Front Image

If you send with creative_id, skip this section — the creative supplies the front design. 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 front image 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 image 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

If you send with creative_id, skip this section — the creative supplies the 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 front image 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.

​
Postage Class

Use the postage_class field to choose how an order is mailed:
  • first_class - First Class postage, with tracking status and return-to-sender.
  • standard - Standard Mail, also known as Marketing Mail. It costs less for US addresses and takes longer to deliver, with no tracking status and no return-to-sender.
If you leave postage_class out, the order uses your account’s default, which you set with Standard Mail Mode under Settings > Mail Preferences in your dashboard. The estimate endpoints accept the same field, so you can compare the cost of both classes before sending. Standard Mail only changes the price of US addresses, and nonprofit accounts always mail at their nonprofit rate. Standard Mail needs a paid plan: free plan accounts always mail First Class, and a request from one that sets postage_class to standard is rejected with a 422.

​
Handwriting

The handwriting style can be customized using the handwriting_style, handwriting_color, handwriting_size, 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.

​
Order Metadata

Use the optional metadata field to attach your own data to an order. thanks.io stores the object with the order and hands it back unchanged — it is never printed on the mailpiece and does not affect how the order is produced.
The same object comes back in three places: That means you can correlate an order and its delivery events back to a record in your own system without storing thanks.io order IDs. Two rules apply to the value you send:
  • It must be a JSON object of key/value pairs, not an array. Values themselves can be nested objects or arrays.
  • It must be no larger than 8,192 bytes once encoded as JSON.
Anything else is rejected with a validation error, and no order is created. Orders created without metadata — including orders created from the dashboard — return null.
Metadata is passthrough data for your own systems. It is not used for personalization — to vary content per recipient, use replacement variables backed by recipient custom fields.