Campaign Personalization

Overview

Campaign personalization lets you pull values from your contacts into campaign emails. You can use built-in fields like {{firstName}} and {{email}}, plus custom variables such as {{company}}, {{plan}}, or {{registrationCode}}.

How it works

Add the custom variable names you want to use, such as company or plan, on the contact book.

Store values on each contact

Save the matching values on each contact through the dashboard, CSV import, or API.

Use variables in your campaign

Select that contact book in your campaign and insert variables into the subject or email content.

Send the campaign

useSend replaces each variable with that contact’s value when the campaign is rendered.

Available variables

These built-in variables are always available in campaigns:

{{email}}
{{firstName}}
{{lastName}}
{{usesend_unsubscribe_url}}

Custom variables come from the contact book’s variable list. Every campaign must include an unsubscribe link. Use the recipient-specific {{usesend_unsubscribe_url}} variable as the link destination:

<a href="{{usesend_unsubscribe_url}}">Unsubscribe</a>

Custom variables must be added to the contact book before they can be used in a campaign. Variable names can only contain letters, numbers, and underscores.

Set up personalization in the dashboard

1. Add variables to your contact book

Go to Contacts
Create a new contact book or open an existing one
Add your variables as a comma-separated list, for example:

company, plan, registrationCode

2. Add values to your contacts

For each contact, save values for the variables you registered. For example, a contact might look like this:

{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "properties": {
    "company": "Acme",
    "plan": "Pro",
    "registrationCode": "WELCOME-2026"
  }
}

You can add these values:

manually from the contact editor
through CSV import using matching column names
through the Contacts API using properties

3. Insert variables in your campaign

Open or create a campaign
Select the contact book that contains your variables
Insert variables into the subject or email body

Examples:

Subject: Welcome to {{company}}

Hi {{firstName}},

You're currently on the {{plan}} plan.
Your registration code is {{registrationCode}}.

If a contact book is selected, the campaign editor will suggest the available variables automatically.

Fallback values

If a variable might be empty, you can provide a fallback value:

Hi {{firstName,fallback=there}},

This renders there when firstName is empty.

Using the API

Create a contact book with variables

curl -X POST https://app.usesend.com/api/v1/contactBooks \
  -H "Authorization: Bearer us_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customers",
    "variables": ["company", "plan", "registrationCode"]
  }'

Create a contact with variable values

curl -X POST https://app.usesend.com/api/v1/contactBooks/{contactBookId}/contacts \
  -H "Authorization: Bearer us_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "properties": {
      "company": "Acme",
      "plan": "Pro",
      "registrationCode": "WELCOME-2026"
    }
  }'

Create a campaign that uses variables

curl -X POST https://app.usesend.com/api/v1/campaigns \
  -H "Authorization: Bearer us_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome campaign",
    "from": "Acme <[email protected]>",
    "subject": "Welcome to {{company}}",
    "contactBookId": "{contactBookId}",
    "html": "<p>Hi {{firstName,fallback=there}}, your plan is {{plan}}.</p><p><a href=\"{{usesend_unsubscribe_url}}\">Unsubscribe</a></p>"
  }'

Best practices

Best practice	Why it helps
Register variables before importing contacts	Keeps CSV columns and API properties aligned with the contact book
Keep variable names simple	Makes templates easier to read and maintain
Use fallbacks for optional data	Prevents awkward empty spaces when a contact is missing a value
Test with a small segment first	Helps you verify rendered output before sending to a larger audience

Getting Started

Self Hosting

Guides

Campaign Personalization

Overview

How it works

Available variables

Set up personalization in the dashboard

1. Add variables to your contact book

2. Add values to your contacts

3. Insert variables in your campaign

Fallback values

Using the API

Create a contact book with variables

Create a contact with variable values

Create a campaign that uses variables

Best practices

​Overview

​How it works

​Available variables

​Set up personalization in the dashboard

​1. Add variables to your contact book

​2. Add values to your contacts

​3. Insert variables in your campaign

​Fallback values

​Using the API

​Create a contact book with variables

​Create a contact with variable values

​Create a campaign that uses variables

​Best practices

Overview

How it works

Available variables

Set up personalization in the dashboard

1. Add variables to your contact book

2. Add values to your contacts

3. Insert variables in your campaign

Fallback values

Using the API

Create a contact book with variables

Create a contact with variable values

Create a campaign that uses variables

Best practices