Importing Contacts
There are multiple ways to import contacts
Importing Contacts
The fastest way to get an existing list into Humanic is a CSV import. If your contacts live in a spreadsheet, another email tool, or a CRM — you can have them in Humanic and ready to campaign in under five minutes.
This page covers every import method, how to format your file correctly, what happens to contacts after import, and how to troubleshoot common issues.
Import methods
Humanic gives you four ways to bring contacts in:
CSV upload
Migrating an existing list from any tool
Native integrations
Live sync from Shopify, Amplitude, Segment, PostHog
Webhook
Real-time contact creation from your backend or automation
REST API
Programmatic imports from custom systems
This page focuses on CSV import. For other methods, see the linked guides.
CSV import — step by step
Step 1 — Prepare your file
Your CSV needs at minimum one column: email. Everything else is optional but recommended.
Required column:
Recommended columns:
Full example:
csv
File requirements:
Format
.csv only
Encoding
UTF-8 (save as UTF-8 in Excel or Google Sheets)
Header row
Required — first row must be column names
Email column
Must be named email (lowercase)
File size
Up to the limit of your current plan
Duplicates
Handled by Humanic — see below
Step 2 — Upload the file
In Humanic, go to Contacts → Import CSV
Click Upload File and select your
.csvHumanic reads the header row and shows you a mapping screen
Step 3 — Map columns to contact fields
On the mapping screen, Humanic auto-detects standard column names. For any column it doesn't recognise, you'll see a dropdown to map it manually.
email
Email address
Identifies the contact (required)
first_name
First name
Personalisation token {{first_name}}
last_name
Last name
Personalisation token {{last_name}}
name
Full name
Personalisation token {{name}}
tags
Contact tags
Cohort filtering, campaign targeting
source
Contact source
Reporting and segmentation
Any other column
Custom field
Available as {{column_name}} in email copy
💡 Any column you map becomes a personalisation variable in your campaigns. If you import a
companycolumn, you can use{{company}}in your email subject lines and body copy.
Step 4 — Review and confirm
Humanic shows you a preview of the first few rows with your mapping applied. Check that:
Emails look correct (no extra spaces, no formatting errors)
Names are in the right fields
Tags and sources are mapped the way you expect
Click Import to start the upload.
Step 5 — Import complete
Humanic processes the file and adds contacts to your list. For large files, this may take a few minutes. You'll see a confirmation with:
Total contacts imported
Duplicates skipped
Rows with errors (if any)
Contacts are available immediately for cohort filtering and campaign targeting.
How Humanic handles duplicates
If a contact with the same email address already exists in your workspace, Humanic updates the existing contact rather than creating a duplicate. The merge logic works like this:
Fields with new values in your CSV overwrite the existing values
Fields that are blank in your CSV leave the existing values unchanged
Tags are merged — new tags are added, existing tags are not removed
This means you can safely re-import an updated list without worrying about duplicates. It also means intentional field updates (like changing a plan tier or company name) work as expected — just include the updated value in your new CSV.
Migrating from another email tool
If you're moving to Humanic from Mailchimp, Klaviyo, Kit (formerly ConvertKit), Customer.io, or another ESP, the typical export from those tools produces a CSV that's close to what Humanic expects. A few things to check:
Unsubscribed contacts: Most ESPs include an unsubscribed or status column in their exports. Before importing into Humanic, filter out any contact where this value is true, 1, unsubscribed, or cleaned — importing opted-out contacts and then emailing them damages your sender reputation and may violate local regulations.
Bounced contacts: Similarly, filter out hard bounces from your previous platform before importing. These addresses are invalid and will damage your deliverability if you send to them.
Tags and segments: ESPs export segments differently. Some use a tags column, others use a group column, and some export each segment as a separate file. Consolidate into a single tags column before importing, using comma-separated values for contacts in multiple segments (e.g., vip,active-2025,shopify).
Custom fields: Export with all custom fields included. Map each one during import — they'll all become usable personalisation variables in Humanic.
Best practices for clean imports
Validate emails before importing. Invalid email addresses hurt your deliverability immediately. If your list is old or sourced from a form without validation, run it through an email verification tool first. Even a 5% invalid rate is enough to affect your sender reputation.
Remove unsubscribes and bounces. See the migration section above. Sending to contacts who have previously opted out is a compliance risk and a deliverability risk.
Use consistent tag formatting. Tags are how you'll build cohorts and filter audiences. Decide on a naming convention before you import — lowercase with hyphens (vip, free-user, onboarding-complete) is the most portable format.
Include as much context as you have. Every extra column you import — plan tier, company name, signup source, feature used — becomes a personalisation variable and a segmentation option. The richer your contact data, the more targeted your campaigns can be.
Test with a small batch first. For large imports (10,000+ contacts), upload 50–100 rows first to confirm the mapping looks right before committing the full file.
Troubleshooting
Import fails with a server error
Most server errors are caused by formatting issues in the file. Check:
The file is saved as UTF-8 encoding, not UTF-16 or Windows-1252
There are no merged cells (common when saving from Excel)
The
emailcolumn header is spelled exactlyemail, lowercaseThere are no blank rows in the middle of the file
Special characters (accented letters, emoji) in name fields are encoded correctly
If the error persists after checking these, contact support with the error message and attach a sample of 5–10 rows from the file.
Contacts imported but emails aren't sending
Check two things: first, confirm your sending domain is verified — contacts can be imported before a domain is set up, but no emails will send until it is. Second, check that the contacts are in the cohort your campaign is targeting.
Some rows weren't imported
Rows are skipped when the email field is blank, the email value is not a valid email address format, or the row contains only whitespace. Humanic reports the number of skipped rows in the post-import summary. Download the error report to see which rows were affected.
I imported the wrong file and need to undo it
Humanic doesn't have a one-click bulk undo for imports. If you imported contacts in error, you can delete them individually from the Contact List, or use the search and filter tools to find and bulk-delete all contacts with a specific source tag — which is why adding a source value to your import is useful.
Frequently Asked Questions
Can I import contacts without a first name or last name? Yes. Only email is required. Contacts imported with just an email address are valid and can receive campaigns. If you use personalisation tokens like {{first_name}} in your emails, they'll render blank for contacts where that field is empty — so consider a fallback like {{first_name | default: "there"}}.
What happens if I import a contact who previously unsubscribed? If the contact has an unsubscribed status in Humanic, re-importing them via CSV does not override the unsubscribe. They remain suppressed. Their other fields (name, tags) may update, but they won't receive campaign emails.
Can I import contacts and immediately add them to a campaign? Yes. After import, go to Campaigns, create or open a campaign, and select a cohort that includes your newly imported contacts. If you tagged them with a specific source during import, create a cohort filtered by that tag.
Is there a maximum file size or contact limit per import? File size and import limits depend on your plan tier. Check your current plan in Billing → Plan Details for the specific limits that apply to your account.
Can I import contacts via API instead of CSV? Yes. Humanic's REST API lets you create and update contacts programmatically. Use this for automated or ongoing syncs from your backend. See the REST API Connector guide for full details.
How do I update a contact's email address? Email is the unique identifier in Humanic — there's no direct way to update it via import, because changing the email changes which contact the record refers to. For individual updates, edit the contact directly in the Contact List. For bulk updates, contact support
Last updated