Formatting a CSV

To upload a CSV into Marketing Campaigns, format your data using the following rules. To see an example, download this sample CSV.

Your CSV requires the following information about each contact:

• email or phone_number_id or external_id or anonymous_id (choose one)
• first_name
• last_name

You can use other reserved fields such as city and zipcode. You can also include custom fields with additional identifying information for each contact in the CSV.

For example: You could specify birthday, occupation, and age as the custom fields. The data in the custom fields aid in segmentation and content personalization.

The first row of your CSV must include labels for each column. These labels are also called fields.

• These labels can only use letters, numbers, and underscores.
• Header fields don't need to be in your CSV, but must be assigned a label and defined data type during the upload process.
• If you add custom field data to your CSV, use the defined custom field label as the header label.
• One of the header fields must be the unique identifier for your contacts: email, phone_number_id, external_id, or anonymous_id.
  • Without one of the required identifier columns, Twilio SendGrid doesn't add your contact, but continues with the remainder of the upload. For this reason, the number of contacts might change between your CSV and your Marketing Campaigns list.

If your contacts list has non-English characters, encode your CSV file with UTF-8.

Twilio SendGrid removes duplicate and invalid identifiers.

• Invalid identifers include email addresses with any special characters except for underscores.
• Each contact requires at least one unique identifier per contact.
• When updating a contact, include all of its existing identifiers.

• When uploading your CSV, choose the correct data type as your Field type.

• Numbers data types can't include anything other than numbers or a decimal separator.
  Twilio considers the inclusion of any other character makes the value a string.

  Examples of string field types with numbers in them

  Copy code block

  1
  - US Zip Code: 80202-1713
  2
  - Phone numbers: "(555) 555-5555" or "555.555.5555"
  3
  - Monetary Values with the currency indicator such as $3.50 or €5.73

Use one of the following date formats:

• MM/DD/YYYY
• `MM/D/YYYY
• M/D/YYYY
• M/DD/YYYY

When uploading a CSV to Marketing Campaigns, you might encounter the following errors. To correct the root issue, see the offered options.

• If you include a header labeled as one of the accepted identifiers, move it to the first position in your header row.
• Your CSV must include a header with one of the accepted identifiers.

• Look for hidden characters in your CSV file.
• Select all data in your spreadsheet and copy your data to a new CSV spreadsheet. This should remove any hidden characters.

Your CSV can't have duplicate fields. This applies to fields with values that match your email, first_name and last_name fields. These reserved field names can't be edited.

• For example: If you have a Name field, it may conflict with your first_name reserved field.

Include header fields at the top of each column. All CSV uploads must contain the email header. Header fields can be blank in your CSV but must be defined later during the upload process.

• Categorize dashes or decimal places that are past the hundredth place as text_fields (-100, 123.123 are text fields, 100, 12.12 can be number fields).
• Number fields can include monetary values without the currency symbols. For example, 19.95 would be a number field, and $19.95, including the ($), would be a text field.
• As you are uploading your CSV, make sure you select the correct fields for your Field type.

• Contacts API
• Segmenting your Contacts
• Building your Contact list