Set Custom Fields (Variables) on Users

Welcome to our new Audience pages! Please take our brief survey at the bottom of this page.

To store user data within Sailthru, you can add custom fields (a.k.a. “variables” or “vars”) to the user profiles of each user. These exist alongside other user data that is collected directly by Sailthru, including users’ interactions with your site and emails. You can later access these custom fields through Zephyr template code, Audience Builder queries, the User API, and data exports.

Setting custom fields allows you to easily personalize communications and segment lists for sends and reporting. You can set these vars through your initial list upload, and then add or update them in a number of ways, including using the Sailthru API. If you ever need to download your data – any or all of the variables that exist on your users – you can perform an export.

Variable names:

  • Are case sensitive. For example, if you create a variable named “Survey_Score” it will not be accessible using all lowercase letters.
  • May not start with a number or be only numbers. For example, don’t upload phone numbers using var name “#”.
  • May not contain special characters (such as %, -, or $).  These characters will be scrubbed from variable names upon import.
  • May not contain spaces. If the variable name is submitted with a space, it will be converted to an underscore.

Variable values:

Our best practices dictate that the variable value is not longer than 140 characters.

Ways to Set a Variable

There are four methods below for setting vars. You can:

Regardless of the method used to add or update user variable data, the following parameters should be followed.

Note that you can view variables on individual user profiles once the list has finished by entering an email address in the User Lookup search field in My Sailthru.

Date and Time Formats

In order to maintain strict JSON compatibility, Sailthru vars do not support a native date or time type. Instead, if you use the following naming and formatting conventions, Sailthru will treat these values as dates and times throughout our system, for example, when performing queries in Audience Builder.

Dates

  • Value: For dates, such as birthdays, store a string in the date format: YYYY-MM-DD (for example, 2013-12-15). If the year is unknown, set it to 0000 (for example, 0000-12-15).
  • Var name:_date is required at the end of the var name in order for values to be interpreted as dates. (For example, birth_date or first_login_date.)

Times

  • Values: For time, such as the moment a user signed up, store in UNIX timestamp format (i.e. the number of seconds since Jan 1, 1970 00:00:00 GMT). For example, 1388087892.
  • Var names: _time is required at the end of the var name in order for values to be interpreted as timestamps. (For example, last_discount_time or signup_time.)

NOTE: The above naming conventions are required to properly set the data type.

Using Zephyr, you can work with dates and times in templates using the date and time functions.

  • date returns the current date — or the date of any UNIX timestamp you pass it — in a custom, reader-friendly format (e.g. November 8, 2016).
  • time returns the current UNIX timestamp, or that of any date/time you pass it. It accepts a variety of formats of dates and or times, including relative dates and times, e.g. “-3 hours” or “+2 weeks Wednesday 3 PM”.

For example, suppose a user’s birth_date is stored as 1980-02-14. To render this as a formatted date, use the following syntax: {date(‘MMMM dd, YYYY’, time(birth_date))}

Recommended Variables

Adhering to Sailthru’s best practices allows us to tailor your analytics experience. When collecting data for your users at signup, purchase, etc., you can use the following custom vars names and values so we can provide a more customized reporting experience.

Suggested Name

Description

Example Values

name

This refers to the user’s full name; Sailthru uses this as the “to:” friendly name when emailing users, populating it is recommended for optimal delivery rates

John Doe

first_name

User’s first/given/personal name; useful for easily personalizing templates or hosted pages without having to parse the “name” var above

John

last_name

User’s last/family/surname

Doe

source

The referral source of the subscription; Sailthru uses this to generate the Source Signup Report in My Sailthru. Learn more about how to set a source.

Fall2015campaign

Facebook

Twitter

postal_address

Physical mailing address, line 1

123 Main Street

postal_address2

Physical mailing address, line 2; useful for apartments, floors and building numbers

Apt 6A

postal_city

Physical mailing address city

New York

postal_state

Physical mailing address state

NY

postal_code

Physical mailing address postal code (ZIP Code in US)

Note: When submitted via CSV, numeric postal codes must be submitted in quotes (e.g. “01234”) to preserve leading zeroes

10011

10011-1234

K8N 5W6

country

Shorthand code for country of residence as stipulated by ISO 3166-1

US

AU

FR

locale

Shorthand codes for spoken language and country code, use format [language code],[_country_code]. Click here for a list. Not case-sensitive.

en_US

cs_CA

en_AU

phone

Full phone number including international country calling code and area code

+12125551234

timezone

Timezone in country/state of residence

For a full list of supported time zones, see the “TZ” column within this list, you can also reference this PHP article.

America/New York

America/Chicago

Canada/Eastern

gender

Gender identification

“m” for male

 “f” for female

 “o” for other

birth_date

Date of birth in “YYYYMMDD” or “YYYY-MM-DD” format

19801230

19780916

marital

marital status

single

married

divorced

domestic partner

widowed

other

income

Occupational income amount or level; wherever possible, enter exact integer value as local currency; if exact amount is not available default to the lowest value in range

If you wish to not collect specific income information, use the suggested ranges below and select the lowest value of each level.Range to display to users [var value to pass]

  • Pass “9999” for “Less than $10,000″
  • Pass “10000” for $10,000 to $14,999
  • Pass “15000” for $15,000 to $24,999
  • Pass “25000” for $25,000 to $49,999
  • Pass “50000” for $50,000 to $99,999
  • Pass “100000” for $100,000 to $149,999
  • Pass “150000” for $150,000 to $199,999
  • Pass “200000” for $200,000 or greater

65000 ($65,000)

education_level

Highest level of education achieved

no diploma

high school

ged

some college

associates

masters

household_size

Integer value for total household size including user

4

children

Integer value for total children in household/family

3

industry

Occupational categorization; suggested values from United States Department of Labor (suggested to use only top-level “Major groups”)

See the above link for a complete list, using the aforementioned examples as a style guide. (i.e., lowercase, with commas)

  • computer and mathematical occupations
  • management occupations
  • legal occupations
  • personal care and service occupations

Note: Each user profile can store up to 1000 variables.

Top