Thanks.io Recipients API
The Recipients API from Thanks.io — 4 operation(s) for recipients.
The Recipients API from Thanks.io — 4 operation(s) for recipients.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/thanks-io:thanks-io-recipients-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: thanks.io Recipients API
description: Use the thanks.io API to send postcards, letters, notecards, windowless letters, and gift cards.
contact:
url: https://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
paths:
/recipients/{recipientId}:
parameters:
- name: recipientId
in: path
description: Recipient ID
required: true
schema:
type: integer
example: 296446
get:
tags:
- Recipients
operationId: getRecipientsDetails
summary: Get Recipient
description: Get a recipient by ID.
responses:
'200':
description: Successful Response
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
$ref: '#/components/schemas/recipient'
examples:
recipient:
$ref: '#/components/examples/recipient-example'
'403':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
tags:
- Recipients
summary: Update Recipient
operationId: updateRecipientDetails
description: 'Update details of a specific recipient by ID. Leave out `absentee_address` to keep the current absentee address. Sending it replaces the stored absentee address as a whole, so send it together with any of `absentee_city`, `absentee_province` and `absentee_postal_code`: those on their own, for example only a new ZIP, are refused with a 400 and nothing is updated. Send `absentee_address` as an empty string or null to remove the absentee address; if the same request also sets `custom1` to `absentee` with an address in `custom2`, that address is copied in instead.'
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/recipient'
- type: object
properties:
absentee_city:
$ref: '#/components/schemas/absentee-city'
absentee_province:
$ref: '#/components/schemas/absentee-province'
absentee_postal_code:
$ref: '#/components/schemas/absentee-postal-code'
responses:
'200':
description: Successful Response
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
$ref: '#/components/schemas/recipient'
examples:
recipient:
$ref: '#/components/examples/recipient-example'
'400':
description: The mailing list does not exist, or the absentee fields are invalid, such as `absentee_postal_code` sent without `absentee_address`
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Mailing list does not exist:
value:
message: Mailing List Does Not Exist
Absentee fields without absentee_address:
value:
message: absentee_city, absentee_province and absentee_postal_code need absentee_address as well.
'403':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags:
- Recipients
operationId: deleteRecipient
summary: Delete Recipient
responses:
'200':
description: Successful Response
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
message: success
'403':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/recipients:
post:
tags:
- Recipients
operationId: createRecipient
summary: Create Recipient
description: Add a recipient. If you do not provide a valid mailing address but do provide a valid email address, thanks.io can attempt to look up a street address for an additional fee.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/recipient-create'
examples:
Adding By Address:
value:
mailing_list_id: 1
name: Tobias Example
company: thanks.io
address: 12345 Main Street
address2: Apartment 1
city: Any Town
province: NY
postal_code: '12345'
country: US
dob: '1981-04-23'
anniversary: '2025-07-21'
email: tobias@example.com
phone: 845-988-6485
custom1: Unique Info
custom2: For example a product code or customer ID
custom3: ''
custom4: ''
Adding By Email:
value:
mailing_list_id: 1
email: tobias@example.com
responses:
'200':
description: Successful Response
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
$ref: '#/components/schemas/recipient'
examples:
recipient:
$ref: '#/components/examples/recipient-example'
'400':
$ref: '#/components/responses/MailingListDoesNotExist'
'404':
$ref: '#/components/responses/NotFound'
/recipients-utils/create-multiple:
post:
tags:
- Recipients
operationId: createMultipleRecipients
summary: Create Multiple Recipients
description: Add multiple recipients at once using a JSON array of recipient objects. If a recipient does not include a valid mailing address but does include a valid email address, thanks.io can attempt to look up a street address for an additional fee.
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/recipient-create'
example:
- mailing_list: 1
name: Tobias First
address: 987 Main Street
address2: null
city: LENEXA
province: KS
postal_code: '66216'
country: US
dob: 04/23/1981
anniversary: 04/23/2025
custom1: null
custom2: null
email: testemail@thanks.io
phone: '1234567890'
- mailing_list: 1
email: another-testemail@thanks.io
phone: '1234567890'
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
$ref: '#/components/schemas/recipient-array'
example:
- province: KS
city: Lenexa
name: Tobias First
company: null
dob: 04/23/1981
anniversary: 04/23/2025
country: US
address: 987 Main Street
address2: ''
email: testemail@thanks.io
phone: '1234567890'
custom1: null
custom2: null
postal_code: '66216'
- province: KS
city: Lenexa
name: Tobias Second
company: null
dob: 04/23/1981
anniversary: 04/23/2025
country: US
address: 654 Main Street
address2: ''
email: testemail@thanks.io
phone: '1234567890'
custom1: null
custom2: null
postal_code: '66216'
error: This address is already on this mailing list.
/recipients-utils/delete-by-address:
post:
tags:
- Recipients
summary: Delete Recipient By Address
description: Delete a recipient by using their address or their email address.
operationId: deleteRecipientByAddress
requestBody:
content:
application/json:
schema:
type: object
anyOf:
- title: Delete Recipient by Address
description: Delete a recipient by providing address details
required:
- mailing_list_id
- address
- postal_code
- title: Delete Recipient by Email
description: Delete a recipient by providing email address
required:
- mailing_list_id
- email
properties:
mailing_list_id:
type: integer
example: 1
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
email:
type: string
example: tobias@example.com
examples:
By Address:
summary: Delete a recipient by address
value:
mailing_list_id: 1
address: 123 Main Street
postal_code: '12345'
By Email:
summary: Delete a recipient by email
value:
mailing_list_id: 1
email: tobias@example.com
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
status: Recipient 297230 Deleted
'400':
$ref: '#/components/responses/MailingListDoesNotExist'
components:
schemas:
recipient:
type: object
properties:
id:
type: integer
example: 18113288
readOnly: true
mailing_list_id:
type: integer
example: 1
name:
type: string
example: Tobias Example
company:
type: string
example: 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'
anniversary:
type: string
description: 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.
example: '2025-07-21'
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
custom5:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom6:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom7:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom8:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom9:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom10:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
absentee_address:
type:
- string
- 'null'
description: The property (absentee) address the absentee image template and message variables use, or null when none is set. Mail is delivered to `address`, not here.
example: 742 Evergreen Terrace, Springfield, IL 62704
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'
recipient-array:
type: array
description: Array of recipient objects
items:
$ref: '#/components/schemas/recipient'
recipient-create:
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:
id:
type: integer
example: 18113288
readOnly: true
mailing_list_id:
type: integer
example: 1
name:
type: string
example: Tobias Example
company:
type: string
example: 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'
anniversary:
type: string
description: 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.
example: '2025-07-21'
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
custom5:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom6:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom7:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom8:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom9:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
custom10:
type: string
description: Custom field for additional information about the recipient
example: Any Extra Info
absentee_address:
$ref: '#/components/schemas/absentee-address'
absentee_city:
$ref: '#/components/schemas/absentee-city'
absentee_province:
$ref: '#/components/schemas/absentee-province'
absentee_postal_code:
$ref: '#/components/schemas/absentee-postal-code'
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'
absentee-city:
type: string
description: City of the absentee (property) address. Requires `absentee_address` in the same request.
example: Springfield
absentee-address:
type: string
description: 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`.
example: 742 Evergreen Terrace
absentee-postal-code:
type: string
description: ZIP or postal code of the absentee (property) address. Requires `absentee_address` in the same request.
example: '62704'
absentee-province:
type: string
description: State or province of the absentee (property) address. Requires `absentee_address` in the same request.
example: IL
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:
NotFound:
description: Resource not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Not Found
MailingListDoesNotExist:
description: The specified mailing list does not exist
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Mailing List Does Not Exist
Unauthorized:
description: Access token is missing or invalid
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Unauthorized
examples:
recipient-example:
summary: Example Recipient
value:
id: 18113288
mailing_list_id: 1
name: Tobias Example
company: thanks.io
address: 12345 Main Street
address2: Apartment 1
city: Any Town
province: NY
postal_code: '12345'
country: US
dob: '1981-04-23'
anniversary: '2025-07-21'
email: tobias@example.com
phone: 845-988-6485
custom1: Unique Info
custom2: For example a product code or customer ID
custom3: ''
custom4: ''
created_at: '2025-06-27T14:57:11.000000Z'
updated_at: '2025-06-27T14:57:11.000000Z'
mailing_list:
id: 1
user_id: 2
sub_account_id: null
type: manual
description: Sphere Contacts Mailing List
qrcode_url: null
total_recipients: 1
processed: true
is_suppression_list: false
total_scans: 1
unique_scans: 1
last_scan: '2025-07-13T13:57:11.000000Z'
total_sends: 2
last_send: '2025-07-06T13:57:11.000000Z'
created_at: 6 years ago
updated_at: '2025-06-27T14:57:11.000000Z'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication using your thanks.io API key
externalDocs:
description: Learn more about thanks.io
url: https://docs.thanks.io
x-mint:
mcp:
enabled: true
x-mcp:
enabled: true