--- title: "Send Notecard" method: POST path: "/send/notecard" tags: ["Send Mailer"] --- # Send Notecard `POST /send/notecard` ## Request - Base URL: `https://api.thanks.io/api/v2` - URL: `https://api.thanks.io/api/v2/send/notecard` - Auth: HTTP bearer Send a folded 4.25x5.5 notecard in envelope. ## Request body - object - `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. On the Free and Business plans, preview images carry a DRAFT watermark; the mail you send never does. Professional and Enterprise previews have no watermark. - `mailing_list_ids` integer[]: Mailing list IDs to send to. Required if `recipients` and `radius_search` are not provided. - `recipients` RecipientCreateNoMailinglist[]: Recipients to send to. Required if `mailing_list_ids` and `radius_search` are not provided. - union - object: Create a recipient by providing address details - `name` string - `company` string - `address` string, required - `address2` string - `city` string - `province` string: State or Province - `postal_code` string - `country` string - `dob` string: 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. - `anniversary` string: Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date 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. - `email` string - `phone` string - `custom1` string: Custom field for additional information about the recipient - `custom2` string: Custom field for additional information about the recipient - `custom3` string: Custom field for additional information about the recipient - `custom4` string: Custom field for additional information about the recipient - `custom5` string: Custom field for additional information about the recipient - `custom6` string: Custom field for additional information about the recipient - `custom7` string: Custom field for additional information about the recipient - `custom8` string: Custom field for additional information about the recipient - `custom9` string: Custom field for additional information about the recipient - `custom10` string: Custom field for additional information about the recipient - `absentee_address` string: The property (absentee) address for this recipient, such as a house an absentee owner owns, as opposed to where they get mail. Give either the whole address here, or the street line here with `absentee_city`, `absentee_province` and `absentee_postal_code`. When set, the `~ABSENTEE_STREET~`, `~ABSENTEE_FULL_ADDRESS~`, `~FULL_ADDRESS~` and `~STREET_VIEW~` image template variables, and `%ABSENTEE_STREET%` in messages, use this address instead of the mailing address. The mailer is still delivered to `address`. Include the city, state and ZIP so Street View finds the right property. It is stored and returned in its own `absentee_address` field, and also copied into `custom2` when that is empty, so templates that print `%CUSTOM2%` keep working; a `custom2` you send is never changed. The older convention of `custom1` = `absentee` with `custom2` = the property address is still accepted and copied into `absentee_address`. - `absentee_city` string: City of the absentee (property) address. Requires `absentee_address` in the same request. - `absentee_province` string: State or province of the absentee (property) address. Requires `absentee_address` in the same request. - `absentee_postal_code` string: ZIP or postal code of the absentee (property) address. Requires `absentee_address` in the same request. - `mailing-list` MailingList - `id` integer - `user_id` integer - `sub_account_id` integer, nullable - `type` 'csv' | 'manual' | 'map' | 'friends' | 'retarget' | 'leads' | 'zapier' | 'radius' | 'highlevel' | 'qrscans' - `description` string - `qrcode_url` string, nullable - `total_recipients` integer - `processed` boolean - `is_suppression_list` boolean - `total_scans` integer - `unique_scans` integer - `last_scan` string, nullable - `total_sends` integer - `last_send` string, nullable - `api_key` string: API key that can be used to add recipients to this mailing list with thanks.io Webhooks - `created_at` string, date-time - `created_at_diff` string: Human-friendly relative time since creation - `updated_at` string, date-time - `created_at` string - `updated_at` string - object: Create a recipient by providing email address - `name` string - `company` string - `address` string - `address2` string - `city` string - `province` string: State or Province - `postal_code` string - `country` string - `dob` string: 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. - `anniversary` string: Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date 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. - `email` string, required - `phone` string - `custom1` string: Custom field for additional information about the recipient - `custom2` string: Custom field for additional information about the recipient - `custom3` string: Custom field for additional information about the recipient - `custom4` string: Custom field for additional information about the recipient - `custom5` string: Custom field for additional information about the recipient - `custom6` string: Custom field for additional information about the recipient - `custom7` string: Custom field for additional information about the recipient - `custom8` string: Custom field for additional information about the recipient - `custom9` string: Custom field for additional information about the recipient - `custom10` string: Custom field for additional information about the recipient - `absentee_address` string: The property (absentee) address for this recipient, such as a house an absentee owner owns, as opposed to where they get mail. Give either the whole address here, or the street line here with `absentee_city`, `absentee_province` and `absentee_postal_code`. When set, the `~ABSENTEE_STREET~`, `~ABSENTEE_FULL_ADDRESS~`, `~FULL_ADDRESS~` and `~STREET_VIEW~` image template variables, and `%ABSENTEE_STREET%` in messages, use this address instead of the mailing address. The mailer is still delivered to `address`. Include the city, state and ZIP so Street View finds the right property. It is stored and returned in its own `absentee_address` field, and also copied into `custom2` when that is empty, so templates that print `%CUSTOM2%` keep working; a `custom2` you send is never changed. The older convention of `custom1` = `absentee` with `custom2` = the property address is still accepted and copied into `absentee_address`. - `absentee_city` string: City of the absentee (property) address. Requires `absentee_address` in the same request. - `absentee_province` string: State or province of the absentee (property) address. Requires `absentee_address` in the same request. - `absentee_postal_code` string: ZIP or postal code of the absentee (property) address. Requires `absentee_address` in the same request. - `mailing-list` MailingList - `id` integer - `user_id` integer - `sub_account_id` integer, nullable - `type` 'csv' | 'manual' | 'map' | 'friends' | 'retarget' | 'leads' | 'zapier' | 'radius' | 'highlevel' | 'qrscans' - `description` string - `qrcode_url` string, nullable - `total_recipients` integer - `processed` boolean - `is_suppression_list` boolean - `total_scans` integer - `unique_scans` integer - `last_scan` string, nullable - `total_sends` integer - `last_send` string, nullable - `api_key` string: API key that can be used to add recipients to this mailing list with thanks.io Webhooks - `created_at` string, date-time - `created_at_diff` string: Human-friendly relative time since creation - `updated_at` string, date-time - `created_at` string - `updated_at` string - `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. - `preview` boolean: Return a preview of the number of matching recipients and the estimated cost. - `address` string: Full street address to use as the center point of the nearest-neighbor search. - `record_count` integer: Number of nearby records to return. - `record_types` 'all' | 'likelytomove' | 'likelytorefi' | 'absenteeowner' | 'highnetworth' | 'majorityhomeequity' | 'homefreeclear' | 'underwater' | 'kidsinhousehold' | 'newhomeowner' | 'firsttimehomebuyer' | 'renters' | 'retiring' | 'retired' | 'pool' | 'onlybusinesses' | 'newbusiness': Record type to search for - `include_condos` boolean: Include condos in search. - `append_data` boolean: Append phone and email to each record for an additional fee ($.20 per record). - `use_property_owner` boolean: Use the property owner's address when searching commercial records. - `include_search_address` boolean: Set to true to include the search address in the generated mailing list. - `handwriting_style_id` integer: ID of handwriting style to use. - `handwriting_color` 'blue' | 'black' | 'green' | 'purple' | 'red': Handwriting color to use. Options are preset named colors or specified as hex format, such as '#4287f5' - `handwriting_realism` boolean: Set to true to enable the realism effect for AI fonts. - `sub_account` integer: Sub-account ID to use for this order. - `notification_emails` string: Optional comma-separated list of email addresses to notify about order events such as QR scan notifications. - `email_lookup` boolean: Whether a recipient given an `email` but no street address has their postal address looked up from the email. Each address found is charged as an Email to Address lookup. Defaults to `true`. Set to `false` to skip the lookup: recipients without a street address are then left out of the order, which mails only the recipients that have one. Estimates never run the lookup and price such recipients as if found. - `postage_class` 'first_class' | 'standard': 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. - `return_name` string: Custom return name for the order. - `return_address` string: Custom return address for the order. - `return_address2` string: Custom return address line 2 for the order. - `return_city` string: Custom return city for the order. - `return_state` string: Custom return state/province for the order. - `return_postal_code` string: Custom return postal code for the order. - `metadata` object, nullable: 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. - `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`). - `image_template_id` integer: ID of image template to use for the exterior of the notecard. Required if not front_image_url is specified. - `front_image_url` string: URL to image to use for the exterior of the notecard. Required if image_template_id is not specified. - `message` string: Handwritten message content to use for interior of notecard. - `message_template_id` integer: ID of message template to use for interior of notecard. - `use_custom_background` boolean: Use custom interior background image. This can be used to turn off the default background image. - `custom_background_image` string: URL to custom background image to use for interior of notecard. This image will be placed behind the handwritten message. Must be 1650px by 2475px. - `qrcode_url` string: URL to Autogenerate QR Code in interior of notecard. ## Response `200` Send Mailer Success - union - SendMailerOrderResponse: Response when an Order is successfully submitted to Send Mailer - `id` integer: Unique identifier for the order - `user_id` integer: User ID for the order - `sub_account` SubAccount - `id` integer - `user_id` integer - `title` string - `return_name` string - `return_address` string - `return_address2` string - `return_city` string - `return_state` string - `return_postal_code` string - `sub_account_id` integer, nullable: Sub account ID for the order - `total_estimated_recipients` integer: Total estimated recipients for the order - `authorization_total` integer: Total authorization amount for the order in cents - `leads_fee` integer: Total leads fee for the order in cents - `mailing_list_ids_used` string: Mailing lists used for the order. Can be null if recipients or radius search is used. - `recipients` RecipientNoMailinglist[]: List of recipients for the order - `name` string - `company` string - `address` string - `address2` string - `city` string - `province` string: State or Province - `postal_code` string - `country` string - `dob` string: 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. - `anniversary` string: Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date 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. - `email` string - `phone` string - `custom1` string: Custom field for additional information about the recipient - `custom2` string: Custom field for additional information about the recipient - `custom3` string: Custom field for additional information about the recipient - `custom4` string: Custom field for additional information about the recipient - `custom5` string: Custom field for additional information about the recipient - `custom6` string: Custom field for additional information about the recipient - `custom7` string: Custom field for additional information about the recipient - `custom8` string: Custom field for additional information about the recipient - `custom9` string: Custom field for additional information about the recipient - `custom10` string: Custom field for additional information about the recipient - `absentee_address` string, nullable: The property (absentee) address the absentee image template and message variables use. Present only on recipients sent with an absentee address. Mail is delivered to `address`, not here. - `front_image` string: Front image URL for the order - `image_template_id` integer, nullable: Image template ID for the order - `custom_background_url` string, nullable: Custom background URL for the order. Only valid for postcard backs and the interior background of notecards and giftcards. - `message` string: Message content for the order - `message_template_id` integer, nullable: Message template ID for the order - `handwriting_color` string: Handwriting color to use - `font_size` 'auto' | 'small' | 'medium' | 'large': Font size for the order - `style` integer: Handwriting style ID for the order - `append_or_current_resident` boolean: Appended "Or Current Resident" for the order. This is helpful if you want to ensure delivery. - `return_name` string, nullable: Return name for the order - `return_address` string, nullable: Return address line 1 for the order - `return_address2` string, nullable: Return address line 2 for the order - `return_city` string, nullable: Return city for the order - `return_province` string, nullable: Return state/province for the order - `return_postal_code` string, nullable: Return postal code for the order - `type` 'postcard' | 'postcard6x9' | 'postcard6x11' | 'letter' | 'notecard' | 'giftcard' | 'windowlessletter': Type of the order - `size` '4x6' | '6x9' | '6x11': Size of the order (valid for postcards only) - `method` 'api' | 'cardbuilder' | 'drip' | 'email' | 'zapier': Method for the order - `status` 'reviewing' | 'processing' | 'fulfilled' | 'cancelled' | 'printed' | 'shipped' | 'paused' | 'delivered': Status of the order - `display_status` string: Display status for the order - `display_trigger` string: Display trigger for the order - `display_type` string: Display type for the order - `addons` object, nullable: Add-ons for the order - `standardmail` 'on' | 'off': Standard mail add-on status - `qrcode_url` string, nullable: QR code URL for the order - `giftcard_brand` string, nullable: Gift card brand for the order (valid for Giftcard orders only) - `giftcard_image` string, nullable: Gift card image URL for the order (valid for Giftcard orders only) - `giftcard_amount` integer, nullable: Gift card amount for the order in cents (valid for Giftcard orders only) - `giftcard_brand_longname` string: Gift card brand long name for the order (valid for Giftcard orders only) - `metadata` object, nullable: The metadata object submitted with the order, returned exactly as it was sent. Null when the order was created without metadata. - `updated_at` string, date-time: Last updated timestamp for the order - `created_at` string, date-time: Creation timestamp for the order - SendMailerPreviewResponse: Preview image URLs returned when `preview` is set to `true`. - `message` string: Response message - `data` object: Preview data containing image URLs - `previews` string[]: Array of preview image URLs ## Other responses - `400`: User error occurred - `403`: Access token is missing or invalid - `500`: An unknown error occurred ## Changes - **2026-10-19** `c403fbf3dc0f`: 1 info - added the new optional request property `allOf[#/components/schemas/send-mailer-base]/email_lookup` - **2026-10-19** `bbe02ffe74f3`: 1 info - added the optional property `oneOf[subschema #1: Send Mailer Order Submitted Response]/recipients/items/absentee_address` to the response with the `200` status - **2026-10-18** `c10cfeb34552`: 1 warning - removed the optional property `oneOf[subschema #1: Send Mailer Order Submitted Response]/recipients/items/absentee_address` from the response with the `200` status - **2026-10-17** `10023a95b079`: 1 info - added the optional property `oneOf[subschema #1: Send Mailer Order Submitted Response]/recipients/items/absentee_address` to the response with the `200` status - **2026-10-15** `4e41e9041848`: 1 warning, 1 info - removed the request property `allOf[#/components/schemas/send-mailer-base]/send_standard_mail` - added the new optional request property `allOf[#/components/schemas/send-mailer-base]/postage_class` [Operation history](https://skmtc.dev/thanks-io/apis/thanks-io-api/changes/send/notecard/post.md) --- [API](https://skmtc.dev/thanks-io/apis/thanks-io-api.md) · [All operations](https://skmtc.dev/thanks-io/apis/thanks-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thanks-io/apis/thanks-io-api/revisions/c403fbf3dc0f?raw)