Create Recipient

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: ''
  })
};

fetch('https://api.thanks.io/api/v2/recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
  }
}

{
  "message": "Mailing List Does Not Exist"
}

{
  "message": "Not Found"
}

POST

recipients

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: ''
  })
};

fetch('https://api.thanks.io/api/v2/recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
  }
}

{
  "message": "Mailing List Does Not Exist"
}

{
  "message": "Not Found"
}

Authorizations

Authorization

string

header

required

Bearer token authentication using your thanks.io API key

Body

application/json

Create Recipient by Address
Create Recipient by Email

Create a recipient by providing address details

mailing_list_id

integer

required

Example:

1

address

string

required

Example:

"123 Main Street"

name

string

Example:

"Tobias Example"

company

string

Example:

"thanks.io"

address2

string

Example:

"Apartment 1"

city

string

Example:

"Any Town"

province

string

State or Province

Example:

"KS"

postal_code

string

Example:

"12345"

country

string

Example:

"US"

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.

Example:

"1981-04-23"

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.

Example:

"2025-07-21"

string

Example:

"tobias@example.com"

phone

string

Example:

"+1 (555) 123-4567"

custom1

string

Custom field for additional information about the recipient

Example:

"Unique Info"

custom2

string

Custom field for additional information about the recipient

Example:

"For example a product code or customer ID"

custom3

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom4

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom5

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom6

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom7

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom8

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom9

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom10

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

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 as custom1 = absentee and custom2 = the full address and is returned that way, so it cannot be combined with custom1 or custom2: a recipient that sets either one as well is rejected with a 400.

Example:

"742 Evergreen Terrace"

absentee_city

string

City of the absentee (property) address. Requires absentee_address.

Example:

"Springfield"

absentee_province

string

State or province of the absentee (property) address. Requires absentee_address.

Example:

"IL"

absentee_postal_code

string

ZIP or postal code of the absentee (property) address. Requires absentee_address.

Example:

"62704"

Response

Successful Response

integer

read-only

Example:

18113288

mailing_list_id

integer

Example:

1

name

string

Example:

"Tobias Example"

company

string

Example:

"thanks.io"

address

string

Example:

"123 Main Street"

address2

string

Example:

"Apartment 1"

city

string

Example:

"Any Town"

province

string

State or Province

Example:

"KS"

postal_code

string

Example:

"12345"

country

string

Example:

"US"

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.

Example:

"1981-04-23"

anniversary

string

Example:

"2025-07-21"

string

Example:

"tobias@example.com"

phone

string

Example:

"+1 (555) 123-4567"

custom1

string

Custom field for additional information about the recipient

Example:

"Unique Info"

custom2

string

Custom field for additional information about the recipient

Example:

"For example a product code or customer ID"

custom3

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom4

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom5

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom6

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom7

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom8

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom9

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

custom10

string

Custom field for additional information about the recipient

Example:

"Any Extra Info"

mailing-list

object

The mailing list this recipient belongs to

Show child attributes

created_at

string

read-only

Example:

"2025-06-27T14:57:11.000000Z"

updated_at

string

read-only

Example:

"2025-06-27T14:57:11.000000Z"

Get Started

Authentication

API Endpoints

Examples

Authorizations

Body

Response