Contact Files
A contact file is a list of contacts, one row per contact, supplied as a file. The same format is read in two places:
- Uploading Contacts, the Upload Contacts wizard on the Contacts page, which adds the contacts in the file to the organisation's contact store.
- Contact File Audiences, the File audience in a campaign, which sends to the contacts in the file.
What a file may contain is the same either way, and this page is the reference for it. For a working sample in each format, see Example Files.
Supported Formats
| Format | Extension | Structure expected |
|---|---|---|
| CSV | .csv | One row per contact. A header row is optional, and Outreach detects whether the first row holds headings. |
| JSON | .json | A flat array of objects, one object per contact. No wrapper object and no nesting. |
| XML | .xml | A <contacts> root element wrapping one <contact> element per contact, with each value as a child element. |
All three behave identically once uploaded. Outreach reads the columns (CSV) or elements (JSON and XML) it finds and presents the same mapping step whichever format was used, so the choice is only a matter of what the source system exports.
Files are read as UTF-8. A file saved in another encoding may import with corrupted characters, and those characters then appear in any message personalised with the affected values.
What a Row Needs
Each row describes one contact, and a row needs the identifier the send will use: a phone number for SMS, an email address for email. Phone numbers have to be in E.164 format, and email addresses in the standard name@example.com form. Identifiers covers how identifiers work on a contact.
Every other column is optional. A column can be matched to any reserved or custom contact field, or left out of the mapping if it has no place. One optional column carries message priority, which applies only when the file is used as a campaign audience.
Column headings are yours to choose. What a column does is decided when it is mapped, not by what it is called, so an export from another system can be uploaded without renaming its headings first.
Mapping Columns
Mapping is the step that decides what each column in the file is used for. A file is read the same way in both places, but what the dropdown beside a column offers is not the same, because the two flows do different things with the rows:
- Uploading Contacts writes the rows into the store, so each column is mapped to a contact field.
- Contact File Audiences sends to the rows, so each column is given a role in the campaign instead. The column holding the address the messages go to is labelled Recipient Email on an email campaign and Recipient Phone on an SMS campaign, and columns feeding the template are labelled Template Value.
In the Upload Contacts wizard a custom field has to exist before a column can be mapped to it, so create any field the file needs before starting, or from the mapping step itself. See Creating a Custom Field.
Limits
| Limit | Value |
|---|---|
| Maximum rows | 300,000 per file |
| Maximum file size | 50 MB per file |
Whichever limit is reached first applies. Long values across many columns push a file past the size limit well before it reaches 300,000 rows.
Both limits are per file, not per organisation. The contact store is not capped and neither is the number of contacts in a segment, so a store larger than 300,000 contacts is built by uploading more than one file. A campaign that sends to a file rather than to the store is limited to what that one file holds.
How Failures Surface
Problems appear at two different points, and they behave very differently.
The Whole File Is Rejected
If the file itself cannot be read, the upload fails and nothing is imported. An error explains why. This happens when the file:
- Uses an extension other than
.csv,.jsonor.xml - Exceeds the row or file size limit
- Contains duplicate column headings
- Is malformed for its format, for example invalid JSON or unclosed XML elements
Correct the file and upload it again.
Individual Rows Are Skipped
If the file reads successfully, each row is validated and bad rows are skipped rather than blocking the upload. A summary reports the count of contacts that will be imported and the count that will be skipped, and the upload can go ahead with the valid rows.
What Makes a Contact Invalid
A row is skipped if:
- It has no value in the column mapped to the identifier the send needs.
- That value is not in the format required for the channel, for example a phone number that is not E.164, or an address that is not a well-formed email.
A blank value in any other column does not skip the row. The contact is imported with that field empty, and a template can cover the gap with a default value.
A missing or unrecognised priority value never invalidates a row either. The row is imported and its message is read as normal priority instead, as covered in Message Priorities.
If the identifier mapping is changed, validation runs again and the counts update.
Where to Next
- Example Files. Sample contact files in each supported format.
- E.164 Phone Number Format. The required format for SMS phone numbers.
- Message Priorities. What the optional priority column does.
- Uploading Contacts. Importing a file into the contact store.
- Contact File Audiences. Using a file as a campaign's audience.