> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.supersend.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Upload Contacts via CSV

# Upload Contacts via CSV

## Purpose

CSV upload is the primary way to add a list of contacts to a campaign. This article covers the full import process — file format requirements, field mapping, email validation, and what to do when imports fail.

## How Contacts Work in SuperSend

Contacts in SuperSend live at two levels:
- **Team contacts** — a shared pool of contacts across all campaigns on your team.
- **Campaign contacts** — contacts assigned to a specific campaign. A contact can be in multiple campaigns.

When you upload via CSV, you're adding to both at once: the contacts get created at the team level, and assigned to the campaign you specify.

## Before You Upload

Your CSV file must include at minimum one column: `email`. Every other field is optional but strongly recommended for personalization.

**Recommended CSV columns:**

| Column name | What it maps to |
|---|---|
| `email` | Contact's email address (required) |
| `first_name` | First name |
| `last_name` | Last name |
| `title` | Job title |
| `company_name` | Company name |
| `company_url` | Company website |
| `linkedin_url` | LinkedIn profile URL |
| `phone` | Phone number |
| `city`, `state`, `country` | Location fields |

Column names don't have to be exact — you can map them manually in step 2. But matching the standard names above speeds things up.

**Custom variables:** If you have custom personalization variables (e.g., `{{pain_point}}` or `{{recent_news}}`), include them as columns in your CSV. You'll map them to custom fields during import.

## Upload from a Campaign

1. Open the campaign.
2. Click **Contacts** in the campaign navigation.
3. Click **Upload CSV** (or **Import Contacts**).
4. The upload modal opens. Follow the three sub-steps below.

## Upload from the Team Contacts Page

1. Go to **Contacts** in the left sidebar (this opens team-level contacts).
2. Click **Upload CSV**.
3. After selecting your file, you'll need to select a **Campaign** from a dropdown before you can proceed. Team-level uploads require a campaign assignment.
4. Continue with the three sub-steps below.

---

## Sub-step 1: Select Your File

Drag and drop your CSV file onto the upload area, or click to browse your files.

Once you select a file, the modal advances to field mapping. If you need to pick a different file, you can go back.

---

## Sub-step 2: Map Fields

SuperSend reads your CSV headers and shows a mapping table. Each of your CSV columns appears on the left, and you match each one to a SuperSend contact field on the right.

**How auto-mapping works:** If your column name exactly matches a SuperSend field name (e.g., `first_name`, `email`), SuperSend maps it automatically. Columns it can't recognize are left unmapped and you fill them in manually.

**Mapping custom variables:** If your campaign has custom contact variables configured, they appear in the field dropdown options. Map your custom CSV columns to the corresponding campaign variables.

**Per-contact file URLs:** If you use a custom variable with type **attachment** (dynamic attachments—e.g. a different resume or PDF per contact), put the **direct download URL** in a CSV column and map it to that variable. See [Dynamic attachments (per-contact files)](https://help.supersend.io/en/article/dynamic-attachments-per-contact-files-6udxb8/).

**Unmapped columns:** Any column you don't map is ignored — that data won't be imported. If you have a column you want but can't find a matching field, you may need to add a custom variable first (this can be done from the campaign's Contacts configuration settings).

Click **Next** when all the columns you want are mapped.

---

## Sub-step 3: Email Validation

Before the upload completes, SuperSend shows a validation summary:

- **Total contacts** in the file
- **Available validation credits** on your account
- **Cost** to validate the entire file (1 credit per email)

**What email validation does:** SuperSend checks each email address for deliverability — verifying the domain is active, the mailbox exists, and the address isn't a known catch-all or disposable address. Contacts that fail validation are flagged before your campaign sends to them, protecting your sender reputation.

**To validate:** Check the **Validate all emails** checkbox (only active if you have sufficient credits), then click **Upload**.

**To skip validation:** Leave the checkbox unchecked and click **Upload**. You can validate contacts individually or in bulk later.

**If you don't have enough credits:** Click **Buy More Credits** to purchase additional credits. This opens the billing page in a new tab. After purchasing, close the billing tab and continue the upload in the original window.

After clicking **Upload**, the modal closes and an import progress tracker appears in the corner of the screen showing the filename and status.

---

## After the Import

When the import finishes, the tracker shows: **"X contacts added, Y updated, Z failed."** For large files, you may also see row-level detail: **"X unique contacts (Y rows processed, Z duplicate rows skipped, W failed)."**

- **Added / unique contacts** — new contacts created (one per unique email address).
- **Updated / duplicate rows** — rows whose email already existed on your team; data may be refreshed.
- **Failed** — rows that couldn't be imported. Click the **View reasons** link to download a failure report explaining each row.
- **Rows processed** — total CSV data rows SuperSend read. This number can be higher than unique contacts when the same email appears on multiple rows.

### Large CSV files (25,000+ rows)

Large uploads run in the background and may take several minutes. Progress shows **rows processed** vs **total rows** so you can see the import moving even when duplicate emails mean **unique contacts added** stays lower.

Email validation for large uploads runs as a **separate batched phase** after the import completes (when you opted in to validate). You do not need to keep the upload modal open.

### Filter contacts by upload

Each CSV import is tracked as its own **upload**. After import, you can filter contacts by which file they came from:

1. Open **All Contacts** (or a campaign's **Contacts** tab).
2. Open **Filters**.
3. Add **Import / upload** → **Includes** and choose the upload (filename and date are shown).
4. To exclude another list (e.g. send to Upload A but not Upload B), add a second filter: **Import / upload** → **Does Not Include** → select Upload B.
5. Use bulk actions (e.g. **Assign to Campaign**) on the filtered set.

When an import finishes, use **Go to Contacts** in the progress tracker to open All Contacts with that upload filter applied automatically.

Common reasons for failure:
- Missing or malformed email address.
- Email address is on your team's suppression list or blacklist.
- Duplicate contacts within the same CSV file.

## Add a Single Contact

For one-off additions, you don't need a CSV:

1. Go to the campaign's **Contacts** tab.
2. Click **Add Contact** (or look for a **+ Single Contact** option in the upload modal).
3. Fill in the contact form: email, first name, last name, company, title, etc.
4. Optionally select a **Sequence Step** to start the contact at if you want to skip step 1 (e.g., add a contact directly to your follow-up step).
5. Click **Save**.

## Expected Result

Contacts appear in the campaign's Contacts tab with the status "Active" or "Queued," ready to enter the sequence when the campaign sends.

## Troubleshooting

- **Issue:** Import finishes but contacts don't appear in the campaign.  
  **Fix:** Confirm the campaign was selected during the upload (required for team-level uploads). Also check the failure report to see if contacts were rejected.

- **Issue:** Some contacts import but have blank fields.  
  **Fix:** Return to step 2 (field mapping) next time and ensure all columns are mapped. Unmapped columns are silently dropped.

- **Issue:** Upload completes but contact count is lower than expected.  
  **Fix:** Duplicate emails within the same CSV are deduplicated — you'll only get one contact per email address. Contacts matching existing team contacts count as "updated," not "added." Compare **rows processed** to **unique contacts** in the completion message.

- **Issue:** Large upload appears stuck at 0 contacts added.  
  **Fix:** Check **rows processed** in the progress tracker — duplicate rows increment the duplicate count, not the added count. Wait for the import to finish; large files can take 10+ minutes.

## Related Articles

- [Create and Manage Suppression Lists](https://help.supersend.io/en/article/create-and-use-suppression-lists-xkxzcc/)
- [Create a Campaign](https://help.supersend.io/en/article/create-a-campaign-18zo2cn/)