Replacement Variables
What it is
Replacement variables are placeholders you put in a message: the message of a creative, a ThanksAI Studio message, or the message you write in Send Mail. At send time, thanks.io replaces each variable with the corresponding value for that recipient - so every piece feels personally written.
Variables always appear in %UPPER_CASE% format surrounded by percent signs. Type them yourself, or click Personalize above the message box in the message editor to search the list and insert one where your cursor is.
Example
Hi %FIRST_NAME%,
Your neighbor on %STREET_ONLY% just got a new roof.
- %YOUR_FULL_NAME%
%YOUR_PHONE%
At send time: %FIRST_NAME% → "Sarah", %STREET_ONLY% → "Main Street" for a recipient at 123 Main Street, and %YOUR_FULL_NAME% and %YOUR_PHONE% pull from your Branding.
Full variable reference
Each variable has two forms. Use the Message Template Variable (%VARIABLE%) in message text. Use the QR Code Variable (~VARIABLE~) in a QR code destination URL or a Street View design field - see Tilde format below.
Branding variables (from Branding)
| Message Template Variable | QR Code Variable | What it inserts |
|---|---|---|
%YOUR_FULL_NAME% | ~YOUR_FULL_NAME~ | Your full name |
%YOUR_FIRST_NAME% | ~YOUR_FIRST_NAME~ | Your first name |
%YOUR_PHONE% | ~YOUR_PHONE~ | Your phone number |
%YOUR_COMPANY% | ~YOUR_COMPANY~ | Your company name |
%YOUR_EMAIL% | ~YOUR_EMAIL~ | Your email address |
AI Receptionist number
| Message Template Variable | QR Code Variable | What it inserts |
|---|---|---|
%YOUR_AI_PHONE% | ~YOUR_AI_PHONE~ | Your AI Receptionist phone number, such as 845-555-0142 |
%YOUR_AI_PHONE% prints the number of the account the mail is sent from: on a sub-account's mail, that sub-account's own AI number. It doesn't fall back to the main account's number or to %YOUR_PHONE%. Callers reach an AI receptionist that takes their details and texts and emails you the lead.
In Personalize, it's listed as Your AI phone number and shows your number. If the account has no AI Receptionist number yet, choosing it (or ~YOUR_AI_PHONE~ in a front design's personalization tags) opens Get an AI phone number first instead, with a link to buy one. The variable works as soon as you have a number.
A send that uses %YOUR_AI_PHONE% or ~YOUR_AI_PHONE~ when the account has no AI Receptionist number (for example, after the number was released) is refused rather than printed with a blank. This applies to sends from the dashboard, campaigns, the API, and AI assistants, and a refused send isn't mailed. In Send Mail, on the Review step, through the API, and through AI assistants, the refusal reads:
This mail uses %YOUR_AI_PHONE%, but the account has no AI Receptionist number yet - get one under AI Receptionist in your dashboard.
Get a number under Phone & Calls → AI Receptionist, or remove the variable, and send again.
To add the number to all your message templates at once, use Add to message templates on the AI Receptionist page. See Put the number on your mail.
Recipient name
| Message Template Variable | QR Code Variable | What it inserts |
|---|---|---|
%FIRST_NAME% | ~FIRST_NAME~ | Recipient's first name |
%LAST_NAME% | ~LAST_NAME~ | Recipient's last name |
%FULL_NAME% | ~FULL_NAME~ | Recipient's full name |
%NAME% | ~NAME~ | Alias for %FULL_NAME% |
Recipient address
| Message Template Variable | QR Code Variable | What it inserts |
|---|---|---|
%ADDRESS% | ~ADDRESS~ | Street address line 1 |
%STREET_ONLY% | ~STREET_ONLY~ | Street name without the house number, such as Main Street for 123 Main Street |
%ADDRESS2% | ~ADDRESS2~ | Address line 2 |
%CITY% | ~CITY~ | City |
%STATE% | ~STATE~ | State or province |
%ZIP% | ~ZIP~ | ZIP or postal code |
Recipient - other fields
| Message Template Variable | QR Code Variable | What it inserts |
|---|---|---|
%COMPANY% | ~COMPANY~ | Recipient's company name |
%CUSTOM1%-%CUSTOM10% | ~CUSTOM1~-~CUSTOM10~ | Custom fields 1-10 from the recipient record |
%FIELD1%-%FIELD4% | ~FIELD1~-~FIELD4~ | Aliases for %CUSTOM1%-%CUSTOM4% |
Real estate / Absentee Owner
| Message Template Variable | QR Code Variable | What it inserts |
|---|---|---|
%ABSENTEE_STREET% | ~ABSENTEE_STREET~ | The target/search address (Neighbor Blast and Absentee Owner Mode) |
Date
| Message Template Variable | QR Code Variable | What it inserts |
|---|---|---|
%CURRENT_DAY% | Not available | The current date when the mail piece is generated |
%CURRENT_MONTH% | ~CURRENT_MONTH~ | The name of the current month when the mail piece is generated, such as October |
Tips & best practices
- Set up Branding before using
%YOUR_*%variables. Empty fields render as blank text. The exception is%YOUR_AI_PHONE%, which comes from your AI Receptionist number rather than Branding: without a number, the send is refused. - Use
%FIRST_NAME%at the start of the message for instant personalization. - Give the reader a number to call.
%YOUR_AI_PHONE%makes sure every call from your mail is answered, day or night. - Custom fields (
%CUSTOM1%-%CUSTOM10%) let you carry any CRM data - lead score, product name, agent name - into your mailer. - If a recipient variable is missing for a recipient, it renders as empty. Before a large send, click Preview as a recipient in the message editor and pick a real recipient to see their merge tags filled in.
Tilde format for QR codes and dynamic image templates
The %VARIABLE% format is for the message body text only. A few other fields use a different format - ~VARIABLE~ (tilde instead of percent signs):
- QR code destination in the message editor - for example,
https://yoursite.com/welcome?name=~FIRST_NAME~ - Street View design fields on a creative's front - header, sub-header, QR code URL, background image, logo, and overlay image
- Lead Board stage webhook URLs - filled in for each lead when the webhook fires, for example
https://example.com/hooks/lead?name=~FIRST_NAME~. See Stage webhooks.
Use ~STREET_ONLY~ in these fields when you want the recipient's street name without their house number, and ~CURRENT_MONTH~ when you want the current month's name - for example, a header reading Your ~CURRENT_MONTH~ market update.
See Dynamic QR URLs and Dynamic Images for full details and variable lists.
Limits & gotchas
- Standard recipient and branding variables are available on all tiers.
%YOUR_AI_PHONE%needs an AI Receptionist number, which any plan can buy. - Do not modify the
%delimiters or change casing inside the variable name -%first_name%will not resolve. (%YOUR_AI_PHONE%is the one variable that also works in lower case.) %FIELD1%-%FIELD4%are interchangeable with%CUSTOM1%-%CUSTOM4%.%STREET_ONLY%usesyour streetwhen the recipient has no usable street name, such as for an empty address or PO box.%CURRENT_DAY%and%CURRENT_MONTH%use the date the piece is generated for printing, not the date it arrives. A piece generated on the last days of a month can land in the mailbox the following month, so word time-sensitive copy accordingly.