Personalize and segment messages with custom fields

(information)

Covers Marketing Campaigns v3

These tutorials cover the latest version of Marketing Campaigns. If you're using the legacy version of Marketing Campaigns, your experience might differ.

To add extra information about a contact, create custom fields. Common use cases for custom fields include:

Creating dynamic segments.
Personalizing the subject lines or content of Marketing Campaign email messages you send.

You can create up to 500 custom fields using the labels and values of your choice.

Custom field rules

Custom fields must meet the following requirements:

Field names

The field name must:

Include alphanumeric characters (A-Z and 0-9) and underscores (_).
Begin with letters A-Z or underscores (_).

Data types

You can create three different types of custom fields according to their data type. The data type impacts the queries used for segmentation:

Type	Query method	Example
Date	Find contacts before, after, or on a specific date.	1/1/2014
Text	Find contacts who match the specific text.	A `pet` field that says `Dog`
Number	Find decimal or integer values greater than, less than, or equal to a specific number.	Contact age: `27`

(warning)

Warning

Twilio limits the length of text custom fields to 1,000 characters.

Reserved fields

Your account comes preloaded with immutable reserved fields. Twilio reserves the following field names:

Field name	Field type
`first_name`	text
`last_name`	text
`email`	text
`phone_number_id`	text
`external_id`	text
`anonymous_id`	text
`alternate_emails`	text
`address_line_1`	text
`address_line_2`	text
`city`	text
`state_province_region`	text
`postal_code`	text
`country`	text
`phone_number`	text
`whatsapp`	text
`line`	text
`facebook`	text
`unique_name`	text

Twilio deprecated the following contact custom fields:

whatsapp
line
facebook
unique_name

Twilio SendGrid populates six reserved fields:

lists
created_at
updated_at
last_emailed
last_clicked
last_opened

Reserved fields track useful metrics for your contacts.

Create a custom field

To add a custom field, add the field using one of the following methods:

Upload CSVAPIConsole

To add multiple contacts at a time, upload a comma-separated value (CSV) file. These CSV files can contain a maximum of one million contacts or 5 GB in file size, whichever is less.

Download this CSV template. It ensures the correct format for your import.
Log in to the Twilio SendGrid console if needed.
Go to Marketing > Contacts in the Twilio SendGrid console.
From the Add Contacts menu, select Upload CSV.
A page displays where you can choose where you want to add your contacts:
- All Contacts
- To an existing list
- To a new list you create
Upload your CSV file using one of two options:
- Drag and drop it onto the upload box.
- Click the select a CSV file to upload.
Click Next: Review CSV Upload.
Another page displays that lists all fields related to your contacts. This displays fields without a corresponding reserved or system field.
With each unmapped field, choose one of three options:
1. Select a custom field from the drop-down.
2. Click Create New Custom Field for a new custom field.
3. Choose Skip Column for any fields you don't want to map.
When you're done mapping the fields, click Next: Add Contacts.
This queues your contacts for upload. Added contacts might take some time to display depending on the number of contacts added.
After Twilio processes the CSV file, it sends you a notification email.

If you'd like to add custom fields using the API, send a POST request to the Field Definitions resource.

Create Custom Field Definition

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const data = {
5  name: "My_Custom_Field",
6  field_type: "Text",
7};
8
9const request = {
10  url: `/v3/marketing/field_definitions`,
11  method: "POST",
12  body: data,
13};
14
15client
16  .request(request)
17  .then(([response, body]) => {
18    console.log(response.statusCode);
19    console.log(response.body);
20  })
21  .catch((error) => {
22    console.error(error);
23  });

Delete a custom field

To delete a custom field:

Go to Marketing and select Custom Fields.
Locate the field you wish to remove.
Hover over the action menu next to the field name entry.
Click the delete icon.
A confirmation modal appears: Are you sure you want to delete this custom field?.
- To delete the contact from your account, click Delete Field.
- To keep the contact in your account, click Cancel.
The panel closes and a banner displays Success! Your custom field has been deleted!

This deletion process may take several minutes. The custom field remains on this page until the process completes.

(warning)

Deleting custom fields deletes their values

When you delete a custom field, you also delete the field values for every contact. It also breaks single sends or automation emails using the custom field as a tag or segments using the field as a condition.

How custom fields impact your campaigns

Segmentation criteria

If you delete a custom field used as criteria within a segment, the segment fails to load. You can't send email messages to a segment based on a deleted custom field.

Email substitution tags

When you delete a custom field used as a substitution tag of an email message, the fallback works in this order:

Twilio SendGrid replaces it with the default value you set.
Twilio SendGrid replaces it with the system default.
Twilio SendGrid displays nothing in the custom field's place.

If a custom field value doesn't appear in place of the corresponding Substitution Tag, try one of these two solutions:

Verify that the contact has a custom field value. In custom fields without values, Twilio uses a space.
Check the spelling of the substitution tag in your message.