Custom fields

Custom fields store extra data on each contact, such as a company name, a plan or a birthday. You define the fields once for the workspace, then fill them in on contacts and use them to filter contacts, personalize campaigns and start automations.

Field types

Each field has a name, which the dashboard shows, and a key, which the API, imports, filters and merge tags use. Values are stored on the contact as a JSON object keyed by field key:

{
  "company": "Acme",
  "plan": "pro",
  "birthday": "1990-04-12",
  "interests": ["news", "offers"]
}

Create a custom field

1. Open Custom fields. Go to Workspace›Settings›Custom fields and select Add custom field.

2. Name the field. Enter a Name, for example Company size. Emailit builds the key from the name automatically: lowercase, with every run of other characters replaced by _, so Company size becomes company_size.

   To choose the key yourself, select Show advanced options and edit Key. Keys are always saved in that lowercase, underscore form, and each key can exist only once per workspace.

3. Pick the type. Choose Text, Number, Date, Boolean, Select or Multi select.

4. Add options for select fields. For Select and Multi select, enter at least one option and use Add option for more. These values appear in the dropdown on contacts.

5. Save. Select Create. The field appears on every contact, in the contact filters and as a merge tag in the campaign editors.

The Custom fields page lists every field with its name, type and options. Use Edit to rename a field, change its type or key, or edit its options.

Set values

With the API, pass custom_fields to Create a contact or Update a contact:

curl https://api.emailit.com/v2/contacts/ada@example.com \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": {
      "company": "Acme",
      "plan": "pro",
      "birthday": "1990-04-12",
      "interests": ["news", "offers"]
    }
  }'

Rules to know:

• custom_fields replaces the whole object. On update, include every value you want to keep, not only the ones that change.
• Use field keys, not names. Values for keys that aren’t defined in Custom fields are stored but don’t show in the dashboard.
• Dates must be YYYY-MM-DD. Emailit converts ISO date-times and Excel date cells to a date. Anything else returns 400 with “Custom field “Birthday” must be a date in YYYY-MM-DD format”. Dates have no time or time zone.
• Select values aren’t checked against the options. A value that isn’t in the option list is still stored, and the dashboard keeps showing it.

Filter contacts by a custom field

In the dashboard, open Email Marketing›Contacts, select Filter and pick the custom field by its name. Custom field filters compare the stored value as text, so use equals, does not equal, contains, does not contain, starts with, ends with, is empty or is not empty.

With the API, use custom_fields.<key>.<condition> on List contacts and Export contacts, with the same text conditions (exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty):

curl "https://api.emailit.com/v2/contacts?custom_fields.plan.exact=pro&custom_fields.company.contains=acme" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

For a range, such as birthdays in the 1990s, use the filter[custom_fields.<key>][gte] and [lte] parameters. They compare the stored text, which sorts correctly for YYYY-MM-DD dates:

curl -G "https://api.emailit.com/v2/contacts" \
  --data-urlencode "filter[custom_fields.birthday][gte]=1990-01-01" \
  --data-urlencode "filter[custom_fields.birthday][lte]=1999-12-31" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

See Filtering for how filters combine.

Use custom fields in campaigns

In campaign content and subjects, insert a custom field with the merge tag {{cf.<key>}}, for example {{cf.company}}. The rich-text and Dragit editors list your custom fields under their variables, so you don’t have to type the key.

<p>Hi {{first_name}}, here's what's new for {{cf.company}}.</p>

If a contact has no value, the tag is replaced with nothing. Multi select values render as a comma-separated list. See Merge tags.

Use custom fields in automations

• Date anniversary trigger. Pick a Date field to start a run every year on the month and day stored in it, for example a birthday. See Triggers.
• Contact updated trigger. Filter on a custom field, or on its previous value, to react when it changes.
• Condition step. Branch on a custom field value.
• Edit contact step. Set a custom field by entering its key.

API reference

Custom field definitions are managed in the dashboard only. Contact values use the custom_fields object on the Contacts API, and the same object is accepted when you add a subscriber to an audience.

Related