# Importing 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:

| Method                  | Best for                                                   |
| ----------------------- | ---------------------------------------------------------- |
| **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:**

```
email
```

**Recommended columns:**

```
email, first_name, last_name, name, tags, source
```

**Full example:**

csv

```csv
email,first_name,last_name,name,tags,source
alex@example.com,Alex,Rivera,Alex Rivera,VIP,shopify
priya@example.com,Priya,Sharma,Priya Sharma,,csv
tom@example.com,Tom,Lee,Tom Lee,beta-user,internal
```

**File requirements:**

| Requirement  | Detail                                          |
| ------------ | ----------------------------------------------- |
| 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

1. In Humanic, go to **Contacts → Import CSV**
2. Click **Upload File** and select your `.csv`
3. Humanic 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.

| Your CSV column  | Maps to Humanic field | Used for                                     |
| ---------------- | --------------------- | -------------------------------------------- |
| `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 `company` column, 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 `email` column header is spelled exactly `email`, lowercase
* There 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

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://humanic.gitbook.io/humanic/getting-started-with-humanic/connecting-your-data/importing-contacts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.