Send Giftcard

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    front_image_url: 'https://cdn.thanks.io/notecard-inspirations/note1.png',
    message: 'Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!',
    handwriting_style_id: 4,
    giftcard_brand: 'amazonus',
    giftcard_amount_in_cents: 10000,
    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/send/giftcard', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "total_estimated_recipients": 1,
  "authorization_total": 179,
  "leads_fee": 0,
  "mailing_list_ids_used": "",
  "handwriting_color": "#000001",
  "front_image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.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.",
  "append_or_current_resident": true,
  "type": "giftcard",
  "return_name": null,
  "return_address": null,
  "return_address2": null,
  "return_city": null,
  "return_province": null,
  "return_postal_code": null,
  "message_template_id": null,
  "image_template_id": 6,
  "method": "api",
  "sub_account_id": null,
  "font_size": "auto",
  "qrcode_url": null,
  "custom_background_url": null,
  "giftcard_brand": "amazonus",
  "giftcard_image": "https://cdn.thanks.io/giftcards/amazonus.png",
  "giftcard_amount": 10000,
  "status": "reviewing",
  "addons": {
    "standardmail": "on"
  },
  "style": 4,
  "user_id": 2,
  "updated_at": "2025-09-02 18:25:44",
  "created_at": "2025-09-02 18:25:44",
  "id": 42696,
  "display_status": "Reviewing",
  "display_trigger": "API",
  "display_type": "Giftcard",
  "giftcard_brand_longname": "Amazon.com",
  "sub_account": null,
  "recipients": [
    {
      "name": "Current Resident",
      "address": "1 Main Street",
      "city": "Anytown",
      "province": "NY",
      "postal_code": "55555",
      "country": "US",
      "address2": ""
    }
  ]
}

POST

send

giftcard

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    front_image_url: 'https://cdn.thanks.io/notecard-inspirations/note1.png',
    message: 'Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!',
    handwriting_style_id: 4,
    giftcard_brand: 'amazonus',
    giftcard_amount_in_cents: 10000,
    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/send/giftcard', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "total_estimated_recipients": 1,
  "authorization_total": 179,
  "leads_fee": 0,
  "mailing_list_ids_used": "",
  "handwriting_color": "#000001",
  "front_image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.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.",
  "append_or_current_resident": true,
  "type": "giftcard",
  "return_name": null,
  "return_address": null,
  "return_address2": null,
  "return_city": null,
  "return_province": null,
  "return_postal_code": null,
  "message_template_id": null,
  "image_template_id": 6,
  "method": "api",
  "sub_account_id": null,
  "font_size": "auto",
  "qrcode_url": null,
  "custom_background_url": null,
  "giftcard_brand": "amazonus",
  "giftcard_image": "https://cdn.thanks.io/giftcards/amazonus.png",
  "giftcard_amount": 10000,
  "status": "reviewing",
  "addons": {
    "standardmail": "on"
  },
  "style": 4,
  "user_id": 2,
  "updated_at": "2025-09-02 18:25:44",
  "created_at": "2025-09-02 18:25:44",
  "id": 42696,
  "display_status": "Reviewing",
  "display_trigger": "API",
  "display_type": "Giftcard",
  "giftcard_brand_longname": "Amazon.com",
  "sub_account": null,
  "recipients": [
    {
      "name": "Current Resident",
      "address": "1 Main Street",
      "city": "Anytown",
      "province": "NY",
      "postal_code": "55555",
      "country": "US",
      "address2": ""
    }
  ]
}

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 exterior of the giftcard. Required if not front_image_url is specified.

Example:

6

front_image_url

string

URL to image to use for the exterior of the giftcard. Required if image_template_id is not specified.

Example:

"https://cdn.thanks.io/notecard-inspirations/note1.png"

message

string

Handwritten message content to use for interior of giftcard.

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 interior of giftcard.

Example:

12

giftcard_brand

string

Brand of giftcard to use. Must be one of the supported brands. The /giftcard-brands endpoint can be used to retrieve a list of supported brands. Leave this out when sending a creative_id: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.

Example:

"amazonus"

giftcard_amount_in_cents

integer

Amount of giftcard in cents. The /giftcard-brands endpoint can be used to retrieve a list of supported amounts by brand. Leave this out when sending a creative_id: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.

Example:

10000

Response

Send Mailer Success

Send Mailer Order Submitted Response
Send Mailer Preview Response

Response when an Order is successfully submitted to Send Mailer

integer

Unique identifier for the order

Example:

42664

user_id

integer

User ID for the order

Example:

2

sub_account

object | null

Sub-account Info For Order. Can be null

Show child attributes

sub_account_id

integer | null

Sub account ID for the order

Example:

12345

total_estimated_recipients

integer

Total estimated recipients for the order

Example:

1

authorization_total

integer

Total authorization amount for the order in cents

Example:

58

leads_fee

integer

Total leads fee for the order in cents

Example:

99

mailing_list_ids_used

string

Mailing lists used for the order. Can be null if recipients or radius search is used.

Example:

"3046,3020"

recipients

object[]

List of recipients for the order

Show child attributes

front_image

string

Front image URL for the order

Example:

"https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png"

image_template_id

integer | null

Image template ID for the order

Example:

6

custom_background_url

string | null

Custom background URL for the order. Only valid for postcard backs and the interior background of notecards and giftcards.

Example:

"https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/4524cce0-78cb-11f0-b937-17570cbedaf4.png"

message

string

Message content for the order

Example:

"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

integer | null

Message template ID for the order

Example:

12345

handwriting_color

string

Handwriting color to use

Example:

"rgba(31,0,113,0.80)"

font_size

enum<string>

Font size for the order

Available options:

auto,

small,

medium,

large

Example:

"auto"

style

integer

Handwriting style ID for the order

Example:

4

append_or_current_resident

boolean

Appended "Or Current Resident" for the order. This is helpful if you want to ensure delivery.

Example:

false

return_name

string | null

Return name for the order

Example:

"John Doe"

return_address

string | null

Return address line 1 for the order

Example:

"123 Main Street"

return_address2

string | null

Return address line 2 for the order

Example:

null

return_city

string | null

Return city for the order

Example:

"Anytown"

return_province

string | null

Return state/province for the order

Example:

"NY"

return_postal_code

string | null

Return postal code for the order

Example:

"12345"

type

enum<string>

Type of the order

Available options:

postcard,

postcard6x9,

postcard6x11,

letter,

notecard,

giftcard,

windowlessletter

Example:

"postcard"

size

enum<string>

Size of the order (valid for postcards only)

Available options:

4x6,

6x9,

6x11

Example:

"4x6"

method

enum<string>

Method for the order

Available options:

api,

cardbuilder,

drip,

email,

zapier

status

enum<string>

Status of the order

Available options:

reviewing,

processing,

fulfilled,

cancelled,

printed,

shipped,

paused,

delivered

display_status

string

Display status for the order

Example:

"Reviewing"

display_trigger

string

Display trigger for the order

Example:

"API"

display_type

string

Display type for the order

Example:

"Postcard-4x6"

addons

object | null

Add-ons for the order

Show child attributes

qrcode_url

string | null

QR code URL for the order

Example:

"https://www.google.com?name=~FULL_NAME~&custom_field_1=~CUSTOM1~&custom_field2=~CUSTOM2~"

giftcard_brand

string | null

Gift card brand for the order (valid for Giftcard orders only)

Example:

null

giftcard_image

string | null

Gift card image URL for the order (valid for Giftcard orders only)

Example:

null

giftcard_amount

integer | null

Gift card amount for the order in cents (valid for Giftcard orders only)

Example:

null

giftcard_brand_longname

string

Gift card brand long name for the order (valid for Giftcard orders only)

Example:

"Amazon.com"

metadata

object | null

The metadata object submitted with the order, returned exactly as it was sent. Null when the order was created without metadata.

Example:

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

updated_at

string<date-time>

Last updated timestamp for the order

Example:

"2025-08-14 16:42:44"

created_at

string<date-time>

Creation timestamp for the order

Example:

"2025-08-14 16:42:44"

Get Started

Authentication

API Endpoints

Examples

Authorizations

Body

Response