Why it matters
Import problems usually come from source file structure, field mapping, identifiers, or consent settings. A focused troubleshooting article helps users fix the source data before they create messy contact records.
Key Concepts
Source file: The csv, spreadsheet, or pasted data used for the import.
Headers: The column names that help the importer understand which data belongs in each contact field.
Identifiers: Values such as phone, email, or external ID that help distinguish one contact from another.
Opt-in state: Whether imported contacts are allowed to receive messages through selected channels.
Static list: The fixed list created by the import.
Step-by-Step: Fix an import issue
Open the source file before importing.
Confirm the first row contains clear column headers.
Check that phone numbers, emails, and external IDs are in consistent formats.
Remove blank rows, merged cells, duplicate header rows, and unrelated notes.
Save the file as csv or xlsx when possible.
Start the import from Contacts > All contacts > Add > Import CSV.
Map columns carefully in the importer.
Review the imported static list and spot-check several contact records.
Tips and Best Practices
Use one column for each contact field.
Keep country codes and phone formatting consistent.
Use external ID when contacts come from another system.
Test with a small file before importing a large audience.
Troubleshooting
Issue | Possible Cause | Fix |
The importer cannot read the file | The file has unsupported formatting, merged cells, or hidden header rows | Clean the file and save it as csv or xlsx |
Contacts import without phone or email values | The columns were not mapped to the correct contact fields | Repeat the import with clearer headers and check the mapping step |
Imported contacts are not opted in | Opt in to channels was not selected or consent was not provided | Review consent requirements and select the correct opt-in channels during import |