Skip to main content
POST
/
send
/
giftcard
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    front_image_url: 'https://d2md0c8rpvzmz5.cloudfront.net/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://d2md0c8rpvzmz5.cloudfront.net/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": ""
    }
  ]
}

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.

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

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

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

​
send_standard_mail
boolean
default:false

Set to true to use Standard Mail postage. If false or omitted, First Class postage is used.

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

​
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://d2md0c8rpvzmz5.cloudfront.net/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.

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.

Example:

10000

Response

Send Mailer Success

Response when an Order is successfully submitted to Send Mailer

​
id
integer

Unique identifier for the order

Example:

42664

​
user_id
integer

User ID for the order

Example:

2

​
sub_account
object

Sub-account Info For Order. Can be null

​
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

​
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

Example:

"https://s3.amazonaws.com/content-staging.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,
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

Add-ons for the order

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

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