Importing contacts from CSV
By Clint ParsleyLast updated
In short. Open Contacts and click Import from CSV. The wizard auto-maps common columns, you pick how duplicates are handled, confirm the contacts consented to hear from you, and rows that fail validation come back as a downloadable error CSV.
Contact import is a short wizard: upload the file, confirm the column mapping, pick a duplicate strategy, and confirm the contacts consented to hear from you. Open Contacts and click Import from CSV. Contacts are unlimited on every tier, so the only real constraints are file size and data quality.
Why does the import ask me to confirm consent?
Before an import can start, you confirm that the contacts in the file consented to receive commercial email from your organization — through an opt-in or an existing business relationship. That checkbox is required on every file, because it's the rule the whole platform runs on: purchased, scraped, or harvested lists aren't allowed on any plan, under our Terms of Service and the inbox providers' own sender guidelines. The compliance guide covers what counts as consent and why lists without it suspend themselves through bounces, and get their senders penalized by inbox providers through complaints.
How does column mapping work?
The import wizard reads your header row and auto-detects the common fields, ignoring capitals and spaces at either end. These headers map themselves:
| Contact field | Headers it recognizes |
|---|---|
| Email (required) | email, email_address, e-mail, mail |
| First name | first_name, firstname, first name, fname, given name |
| Last name | last_name, lastname, last name, lname, surname, family name |
| Company | company, company name, account, account_name, organization, organisation |
| Title | title, job title, position, role |
| Phone (work) | phone, work phone, office_phone |
| Phone (mobile) | mobile, mobile phone, cell, cellphone |
| Lead status | lead status, status, stage |
A custom field you created under Settings maps itself when a header matches its key or its label. Anything else you map by hand, or leave unmapped to skip that column. Email is the one required column; a row without a valid email address fails validation rather than creating an unreachable contact.
The file is parsed as standard CSV, the format described in RFC 4180: a value that contains a comma, a line break or a double quote goes inside double quotes, and a double quote inside a value is written twice. Spreadsheet apps do this for you when they export to CSV.
What happens with duplicates?
When a row's email address already exists in your contacts, the mode you picked decides:
- Skip leaves the existing contact untouched and ignores the row. The safe default for a first import.
- Overwrite updates the existing contact with the values in your file. A column you didn't map, or a blank cell, leaves that field as it was, so an import that only carries phone numbers changes only phone numbers. Use it when the CSV is the fresher source of truth.
- Merge fills in fields the existing contact is missing but keeps its existing values where both have one. The usual choice for enriching what's already there.
The same rule applies when one email appears more than once in your file. The first valid row creates or matches the contact, and each later row with that email is handled as a duplicate of it: skipped, overwriting it, or merged into it. You get one contact, not an error. Under Overwrite or Merge, those later rows count as Updated in the import results.
How big can the file be?
Up to 50 MB, which in practice is roughly 150,000 rows. Files over about half a megabyte route through an asynchronous pipeline: the upload goes straight to storage, processing runs in the background, and you can leave the page while it works. Progress and results show under Contacts → Import history.
What happens to rows that fail?
They don't block the rest. Valid rows import, failing rows are collected, and the import's detail page offers an error CSV listing every rejected row with the reason (bad email format, missing required column, and so on). Fix those rows in your spreadsheet and re-import just that file; with duplicate mode set to skip, the already-imported rows pass through harmlessly.
What should I import first?
Your opt-out list, before any contacts. If you're migrating from another tool, its unsubscribes should land in Settings → Suppression ahead of your first send, so a contact who opted out there can never be mailed here. The compliance guide covers why that ordering matters.
One more habit worth keeping: import in named batches rather than one giant everything file. Smaller imports make the error CSV manageable, and if a list turns out to be stale, its bounces are traceable to one import instead of poisoning your whole database's reputation history. The deliverability guide explains what stale lists do to your bounce rate.