> ## 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. # Send Giftcard > Send a folded 4.25x5.5 giftcard in envelope. ## OpenAPI ````yaml post /send/giftcard openapi: 3.1.0 info: title: thanks.io API description: >- Use the thanks.io API to send postcards, letters, notecards, windowless letters, and gift cards. contact: url: https://www.thanks.io email: support@thanks.io version: 1.0.0 servers: - url: https://api.thanks.io/api/v2 description: The main API server for thanks.io security: - bearerAuth: [] tags: - name: Recipients - name: Mailing Lists - name: Send Mailer - name: Orders - name: Message Templates - name: Image Templates - name: Handwriting Styles - name: Giftcards - name: Dynamic Images description: '' - name: Image Builder - name: Sub Accounts externalDocs: description: Learn more about thanks.io url: https://docs.thanks.io paths: /send/giftcard: post: tags: - Send Mailer summary: Send Giftcard description: Send a folded 4.25x5.5 giftcard in envelope. requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/send-mailer-base' - type: object properties: image_template_id: type: integer description: >- 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: type: string description: >- 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: type: string description: >- Handwritten message content to use for interior of giftcard. example: >- Hey %FIRST_NAME%!, THANK YOU for allowing us the opportunity to HELP you with your plan! message_template_id: type: integer description: ID of message template to use for interior of giftcard. example: 12 giftcard_brand: type: string description: >- 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: type: integer description: >- Amount of giftcard in cents. The `/giftcard-brands` endpoint can be used to retrieve a list of supported amounts by brand. example: 10000 examples: Image URL & Recipients: summary: Giftcard with Custom Image and Recipients description: >- Example of sending a giftcard using a custom front image URL, handwritten message, and an array of recipients with custom fields. value: front_image_url: >- https://d2md0c8rpvzmz5.cloudfront.net/notecard-inspirations/note1.png message: >- Hey %FIRST_NAME%!, THANK 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 Templates: summary: Giftcard with Templates description: >- Example of sending a giftcard using predefined image and message templates & targeting specific mailing lists. value: image_template_id: 6 message_template_id: 12 mailing_list_ids: - 5166 - 514 giftcard_brand: amazonus giftcard_amount_in_cents: 10000 Radius Search: summary: Giftcard with Radius Search Targeting and Standard Shipping description: >- Example of sending a giftcard using radius search to automatically find and target recipients within a specific geographic area, with custom message and image URL. value: front_image_url: >- https://d2md0c8rpvzmz5.cloudfront.net/notecard-inspirations/note1.png message: >- Hey %FIRST_NAME%!, THANK YOU for allowing us the opportunity to HELP you with your plan! send_standard_mail: 'true' giftcard_brand: amazonus giftcard_amount_in_cents: 10000 radius_search: address: 123 Main Street, Fake City, NY, 55555 record_types: likelytomove record_count: 10 include_condos: false append_data: true Preview: summary: Preview Giftcard Before Sending description: >- Example of generating a preview of a giftcard before actually sending it. Use the preview parameter to see how your letter will look without placing an actual order. value: front_image_url: >- https://d2md0c8rpvzmz5.cloudfront.net/notecard-inspirations/note1.png message: >- Hey %FIRST_NAME%!, THANK YOU for allowing us the opportunity to HELP you with your plan! handwriting_style_id: 4 preview: true 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 responses: '200': description: Send Mailer Success content: application/json: schema: oneOf: - $ref: '#/components/schemas/send-mailer-order-response' - $ref: '#/components/schemas/send-mailer-preview-response' examples: Order Submitted Response: summary: Order Submitted Response Example value: 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: '' Preview Response: summary: Preview Response Example value: success: true code: 200 message: OK data: previews: - >- https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png - >- https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/de84e2b3-f3a7-9d35-edc8-4e8da81dbdc0.png '400': $ref: '#/components/responses/UserError' '403': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/UnknownError' components: schemas: send-mailer-base: type: object properties: preview: type: boolean description: >- 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: type: array description: >- Mailing list IDs to send to. Required if `recipients` and `radius_search` are not provided. items: type: integer example: - 5166 - 514 recipients: type: array description: >- Recipients to send to. Required if `mailing_list_ids` and `radius_search` are not provided. items: $ref: '#/components/schemas/recipient-create-no-mailinglist' radius_search: type: object description: >- 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. properties: preview: type: boolean description: >- Return a preview of the number of matching recipients and the estimated cost. default: false address: type: string example: 123 Main Street, Fake City, NY, 55555 description: >- Full street address to use as the center point of the nearest-neighbor search. record_count: type: integer description: Number of nearby records to return. minimum: 1 maximum: 10000 example: 1 record_types: type: string description: Record type to search for enum: - all - likelytomove - likelytorefi - absenteeowner - highnetworth - majorityhomeequity - homefreeclear - underwater - kidsinhousehold - newhomeowner - firsttimehomebuyer - renters - retiring - retired - pool - onlybusinesses - newbusiness default: all include_condos: type: boolean description: Include condos in search. default: false append_data: type: boolean description: >- Append phone and email to each record for an additional fee ($.20 per record). default: false use_property_owner: type: boolean description: >- Use the property owner's address when searching commercial records. default: false include_search_address: type: boolean description: >- Set to true to include the search address in the generated mailing list. handwriting_style_id: type: integer description: ID of handwriting style to use. example: 4 handwriting_color: type: string description: >- Handwriting color to use. Options are preset named colors or specified as hex format, such as '#4287f5' enum: - blue - black - green - purple - red examples: - blue - '#4287f5' handwriting_realism: type: boolean description: Set to true to enable the realism effect for AI fonts. example: true sub_account: type: integer description: Sub-account ID to use for this order. example: 7 notification_emails: type: string description: >- 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: type: boolean description: >- Set to true to use Standard Mail postage. If false or omitted, First Class postage is used. default: false return_name: type: string description: Custom return name for the order. example: Custom Return return_address: type: string description: Custom return address for the order. example: 1 Main Street return_address2: type: string description: Custom return address line 2 for the order. example: Unit 1 return_city: type: string description: Custom return city for the order. example: Woodbridge return_state: type: string description: Custom return state/province for the order. example: NJ return_postal_code: type: string description: Custom return postal code for the order. example: '07095' send-mailer-order-response: type: object title: Send Mailer Order Submitted Response description: Response when an Order is successfully submitted to Send Mailer properties: id: type: integer description: Unique identifier for the order example: 42664 user_id: type: integer description: User ID for the order example: 2 sub_account: description: Sub-account Info For Order. Can be null allOf: - $ref: '#/components/schemas/sub-account' type: - object - 'null' sub_account_id: type: - integer - 'null' description: Sub account ID for the order example: 12345 total_estimated_recipients: type: integer description: Total estimated recipients for the order example: 1 authorization_total: type: integer description: Total authorization amount for the order in cents example: 58 leads_fee: type: integer description: Total leads fee for the order in cents example: 99 mailing_list_ids_used: type: string description: >- Mailing lists used for the order. Can be null if recipients or radius search is used. example: 3046,3020 recipients: type: array description: List of recipients for the order items: $ref: '#/components/schemas/recipient-no-mailinglist' front_image: type: string description: Front image URL for the order example: >- https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png image_template_id: type: - integer - 'null' description: Image template ID for the order example: 6 custom_background_url: type: - string - 'null' description: 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: type: string description: 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: type: - integer - 'null' description: Message template ID for the order example: 12345 handwriting_color: type: string description: Handwriting color to use example: rgba(31,0,113,0.80) font_size: type: string description: Font size for the order enum: - auto - small - medium - large example: auto style: type: integer description: Handwriting style ID for the order example: 4 append_or_current_resident: type: boolean description: >- Appended "Or Current Resident" for the order. This is helpful if you want to ensure delivery. example: false return_name: type: - string - 'null' description: Return name for the order example: John Doe return_address: type: - string - 'null' description: Return address line 1 for the order example: 123 Main Street return_address2: type: - string - 'null' description: Return address line 2 for the order example: null return_city: type: - string - 'null' description: Return city for the order example: Anytown return_province: type: - string - 'null' description: Return state/province for the order example: NY return_postal_code: type: - string - 'null' description: Return postal code for the order example: '12345' type: type: string description: Type of the order enum: - postcard - postcard6x11 - letter - notecard - giftcard - windowlessletter example: postcard size: type: string description: Size of the order (valid for postcards only) enum: - 4x6 - 6x9 - 6x11 example: 4x6 method: type: string description: Method for the order enum: - api - cardbuilder - drip - email - zapier status: type: string description: Status of the order enum: - reviewing - processing - fulfilled - cancelled - printed - shipped - paused - delivered display_status: type: string description: Display status for the order example: Reviewing display_trigger: type: string description: Display trigger for the order example: API display_type: type: string description: Display type for the order example: Postcard-4x6 addons: type: - object - 'null' description: Add-ons for the order properties: standardmail: type: string description: Standard mail add-on status enum: - 'on' - 'off' example: 'on' qrcode_url: type: - string - 'null' description: QR code URL for the order example: >- https://www.google.com?name=~FULL_NAME~&custom_field_1=~CUSTOM1~&custom_field2=~CUSTOM2~ giftcard_brand: type: - string - 'null' description: Gift card brand for the order (valid for Giftcard orders only) example: null giftcard_image: type: - string - 'null' description: Gift card image URL for the order (valid for Giftcard orders only) example: null giftcard_amount: type: - integer - 'null' description: >- Gift card amount for the order in cents (valid for Giftcard orders only) example: null giftcard_brand_longname: type: string description: >- Gift card brand long name for the order (valid for Giftcard orders only) example: Amazon.com updated_at: type: string format: date-time description: Last updated timestamp for the order example: '2025-08-14 16:42:44' created_at: type: string format: date-time description: Creation timestamp for the order example: '2025-08-14 16:42:44' send-mailer-preview-response: type: object title: Send Mailer Preview Response description: Preview image URLs returned when `preview` is set to `true`. properties: message: type: string example: OK description: Response message data: type: object description: Preview data containing image URLs properties: previews: type: array description: Array of preview image URLs items: type: string format: uri example: https://s3.amazonaws.com/cdn.thanks.io/preview/12345.png recipient-create-no-mailinglist: type: object anyOf: - title: Create Recipient by Address description: Create a recipient by providing address details required: - mailing_list_id - address - title: Create Recipient by Email description: Create a recipient by providing email address required: - mailing_list_id - email properties: name: type: string example: Tobias Example company: type: string example: www.thanks.io address: type: string example: 123 Main Street address2: type: string example: Apartment 1 city: type: string example: Any Town province: type: string description: State or Province example: KS postal_code: type: string example: '12345' country: type: string example: US dob: type: string description: >- Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format. example: '1981-04-23' email: type: string example: tobias@example.com phone: type: string example: +1 (555) 123-4567 custom1: type: string description: Custom field for additional information about the recipient example: Unique Info custom2: type: string description: Custom field for additional information about the recipient example: For example a product code or customer ID custom3: type: string description: Custom field for additional information about the recipient example: Any Extra Info custom4: type: string description: Custom field for additional information about the recipient example: Any Extra Info mailing-list: readOnly: true allOf: - $ref: '#/components/schemas/mailing-list' description: The mailing list this recipient belongs to created_at: readOnly: true type: string example: '2025-06-27T14:57:11.000000Z' updated_at: readOnly: true type: string example: '2025-06-27T14:57:11.000000Z' sub-account: type: object properties: id: type: integer example: 1 user_id: type: integer example: 2 title: type: string example: My Sub Account return_name: type: string example: John Smith return_address: type: string example: 123 Smith Street return_address2: type: string example: Apartment 2 return_city: type: string example: Denver return_state: type: string example: CO return_postal_code: type: string example: '12345' recipient-no-mailinglist: type: object properties: name: type: string example: Tobias Example company: type: string example: www.thanks.io address: type: string example: 123 Main Street address2: type: string example: Apartment 1 city: type: string example: Any Town province: type: string description: State or Province example: KS postal_code: type: string example: '12345' country: type: string example: US dob: type: string description: >- Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format. example: '1981-04-23' email: type: string example: tobias@example.com phone: type: string example: +1 (555) 123-4567 custom1: type: string description: Custom field for additional information about the recipient example: Unique Info custom2: type: string description: Custom field for additional information about the recipient example: For example a product code or customer ID custom3: type: string description: Custom field for additional information about the recipient example: Any Extra Info custom4: type: string description: Custom field for additional information about the recipient example: Any Extra Info mailing-list: type: object properties: id: type: integer example: 1 user_id: type: integer example: 2 sub_account_id: type: - integer - 'null' type: type: string example: manual enum: - csv - manual - map - friends - retarget - leads - zapier - radius - highlevel - qrscans description: type: string example: Test qrcode_url: type: - string - 'null' total_recipients: type: integer example: 1 processed: type: boolean example: true is_suppression_list: type: boolean example: false total_scans: type: integer example: 0 unique_scans: type: integer example: 0 last_scan: type: - string - 'null' total_sends: type: integer example: 0 last_send: type: - string - 'null' api_key: type: string description: >- API key that can be used to add recipients to this mailing list with thanks.io Webhooks example: abcd1234efgh5678ijkl9012mnop3456 created_at: type: string example: '2018-07-15T06:06:57.000000Z' format: date-time created_at_diff: type: string example: 6 years ago description: Human-friendly relative time since creation updated_at: type: string example: '2025-06-27T14:57:11.000000Z' format: date-time responses: UserError: description: User error occurred content: application/json: schema: type: object properties: message: type: string example: Sub Account ID does not exist Unauthorized: description: Access token is missing or invalid content: application/json: schema: type: object properties: message: type: string example: Unauthorized UnknownError: description: An unknown error occurred content: application/json: schema: type: object properties: message: type: string example: Error Submitting Mailer securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token authentication using your thanks.io API key ````