HeyReach Custom Variables: The Complete Guide

A HeyReach custom variable is a named piece of text attached to each lead, such as connection_note or message_1. When you put {connection_note} in a campaign step, HeyReach swaps in that lead's own value. You add variables by importing a CSV with a column per variable, or by pushing leads through the API.

Custom variables are how you personalize outreach in HeyReach while the campaign still runs on autopilot. Each lead gets their own message, written ahead of time. Here is how they work and how to fill them with AI.

What is a custom variable

A custom variable is a value that belongs to one lead. Put {message_1} in a step and HeyReach replaces it with that lead's message_1 value. So instead of one template for everyone, each person gets their own line.

Where custom variables come from

HeyReach reads custom variables from the leads in a list. You add them in two ways:

• CSV import. Add a column per variable, such as Connection Note, Message 1, and Message 2, then import into a list.
• API. Push leads with a customUserFields array of name and value pairs. This is how HeyReplyAI sends your AI-written messages straight into HeyReach.

Variable names can only use letters, numbers, and underscores, so message_1 is valid. If your custom variable has the same name as a HeyReach default, the default wins. Name yours clearly to avoid that.

How to use them in a campaign

1. Import or push your leads with their variable values into a lead list.
2. Build or edit a campaign and pick that same list as the audience.
3. Open a message step, click Add variable, and choose your custom variable. Your custom values show in orange, below HeyReach's blue defaults.
4. Add a fallback. If a value is empty, the fallback sends instead.

Why variables sometimes do not show

If your custom variables are missing from the dropdown, it is usually one of three things. The campaign is not pointed at the list that has them. The editor needs a refresh after import. Or the values were empty when you imported. Make sure at least one lead has a value, then reopen the step.

Let AI fill your variables

Writing a unique message_1 for 1,000 leads by hand is not realistic. HeyReplyAI writes each lead's variables for you and sends them into HeyReach. That includes the connection note, follow-ups, and a cold email subject and body on the Pro plan. See how in our AI personalization guide.