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

# Usage

> Info on using thanks.io's Recipients endpoints

# Overview

Recipients represent the individual or entity to whom you are sending mail. They can be created, updated, and managed through these endpoints.

A mailing list ID is required when creating a recipient.

# Naming

A recipient name is not required.  In this case 'Resident' will be used.  You can also just specify a company using the `company` field.

The `company` field can also be used to add a secondary name (such as a spouse).

# Addressing

The `address` field can be used to specify the recipient's street address or it can also be used to specify the full address (in which case we'll autoparse and split into fields automatically).

# Lookup by Email

If no/invalid address is specified and a valid `email` address is, we’ll attempt to look up a valid street address using the email address for a fee.

# Additional fields

`custom1` through `custom10`, `phone`, and `email` can all be specified to help identify the recipient. The custom fields can also be used as replacement variables: `%CUSTOM1%` through `%CUSTOM10%` in messages, `~CUSTOM1~` through `~CUSTOM10~` in image templates, and in QR Code URLs.

# Absentee (property) address

Use `absentee_address` when the property a mailer is about is not where the recipient gets mail — for example, an absentee owner who lives elsewhere. Set `address` to where the mail should go and `absentee_address` to the property:

```json theme={null}
{
  "mailing_list": 12345,
  "name": "Jane Doe",
  "address": "500 Oak Ave",
  "city": "Chicago",
  "province": "IL",
  "postal_code": "60601",
  "absentee_address": "742 Evergreen Terrace",
  "absentee_city": "Springfield",
  "absentee_province": "IL",
  "absentee_postal_code": "62704"
}
```

You can also pass the whole property address in `absentee_address` on its own, for example `"742 Evergreen Terrace, Springfield, IL 62704"`. `absentee_city`, `absentee_province`, and `absentee_postal_code` are optional, and only work alongside `absentee_address`.

These variables then use the property address instead of the mailing address:

| Variable | Where | Uses |
| - | - | - |
| `~STREET_VIEW~` | Image templates | A Street View photo of the property |
| `~ABSENTEE_STREET~` | Image templates | The property's street line, e.g. `742 Evergreen Terrace` |
| `~ABSENTEE_FULL_ADDRESS~`, `~FULL_ADDRESS~` | Image templates | The full property address |
| `%ABSENTEE_STREET%` | Messages | The property's street line |

The absentee fields work the same way when creating a recipient, when [creating multiple recipients](/api-reference/endpoint/recipients/create-multiple-recipients), and on each entry in `recipients` on the [Send Mailer](/api-reference/send-mailer-usage) endpoints.

Things to know:

* **The mailer is still delivered to `address`.** The absentee fields only change what the variables above show.
* **Send the full address.** Street View looks the property up from it, so a street line alone (`742 Evergreen Terrace`) can land on the wrong town. Include the city, state, and ZIP, either in `absentee_address` or in the separate fields.
* **It uses `custom1` and `custom2`.** The property address is stored as `custom1` = `absentee` and `custom2` = the full address, and that is how the recipient comes back in API responses. Webhooks also report it as `recipient.absentee_address`.
* **It can't be combined with `custom1` or `custom2`.** A recipient that sets `absentee_address` and either of those fields is rejected with a `400`, rather than one silently overwriting the other. Use `custom3` through `custom10` for your own data. Setting `custom1` to `absentee` and `custom2` to the property address yourself has the same effect as `absentee_address`.
* **Without it, the variables fall back to the mailing address.** `~STREET_VIEW~` and `~ABSENTEE_STREET~` show the recipient's own `address` when no absentee address is set.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.