Files and Formats
Recipients are supplied as a contact file uploaded on the Add Contacts step of the campaign wizard. This page is the reference for what a contact file may contain: the formats accepted, the fields expected, the limits enforced, and how a file that does not meet the rules is reported back to you.
For ready-made samples in each format, see Example Files.
Supported Formats
| Format | Extension | Structure expected |
|---|---|---|
| CSV | .csv | One row per recipient. A header row is optional — Outreach detects whether the first row contains headers. |
| JSON | .json | A flat array of objects, one object per recipient. No wrapper object and no nesting. |
| XML | .xml | A <contacts> root element wrapping one <contact> element per recipient, with each field as a child element. |
All three formats behave identically once uploaded. Outreach reads the columns (CSV) or fields (JSON and XML) it finds and presents the same mapping step regardless of which you chose, so the format is purely a matter of what your source system exports.
Files are expected to be UTF-8 encoded. Non-UTF-8 files may import with corrupted characters in personalisation variables, which will then appear in delivered messages.
Fields
There are no reserved field names. You name your fields however you like and assign each one a role during mapping.
| Role | Required? | Notes |
|---|---|---|
| Destination | Yes — exactly one | The recipient. A phone number for SMS, an email address for Email. You cannot map more than one field as the Destination. |
| Custom Variable | Optional, any number | Used as personalisation placeholders in the message template. |
| Priority | Optional, at most one | Carries each contact's send priority — High or Normal. Set per row in the file; there is no campaign-level or run-level equivalent. |
| Do not import | — | Fields you want excluded from the campaign entirely. |
Destination Format Rules
The Destination field is validated against the campaign's delivery channel:
- SMS: values must be valid E.164 phone numbers — a leading
+, then country code and subscriber number, with no spaces, dashes, or brackets. - Email: values must be well-formed email addresses, in the standard
name@example.comform.
Limits
| Limit | Value |
|---|---|
| Maximum rows | 300,000 per file |
| Maximum file size | 50 MB per file |
Whichever limit you reach first applies. As a rough guide, 50 MB is around 100,000 rows with ten columns of typical data, or around 300,000 rows with just a destination and one or two short variables — long variable strings push the file size up faster than extra rows do.
To send to more recipients than a single file allows, split the list across multiple campaigns.
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 message explains why. This happens when the file:
- Uses an extension other than
.csv,.json, or.xml - Exceeds the row or file size limit
- Contains duplicate field names
- 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. The contact summary panel reports a count of Total contacts that will be imported and Invalid contacts that will be skipped, and the campaign can be saved and run with the remaining valid rows.
What makes a contact invalid
A row is marked invalid if:
- The Destination field is empty or missing
- The Destination value does not match the format required for the channel
- Any field mapped as a Custom Variable has a missing value
That last rule catches a common surprise: a row with a perfectly valid phone number is still skipped if one of your personalisation variables is blank for that recipient. This is deliberate — it prevents a placeholder such as {{first_name}} being delivered verbatim. Make sure every mapped variable is populated for every row before uploading.
A missing or unrecognised priority value is the exception. It never invalidates a row: the row is not skipped, and its message is read as normal priority instead — see Message Priorities.
If you change which field is mapped to the Destination, validation re-runs automatically and the invalid count updates.
Related Guidance
- Example Files. Sample contact files in each supported format.
- Contacts Overview. Uploading, mapping, and reviewing contacts in the wizard.
- E.164 Phone Number Format. The required format for SMS destination numbers.
- Message Priorities. What the optional priority field does.