By the end of this guide, you'll know how to format CSV files correctly, map columns to lemlist variables, handle import preferences, and troubleshoot common upload errors.

CSV import is how most teams add leads at scale. A properly formatted CSV with correct variable mapping ensures your personalization works ({{firstName}} actually shows names), your emails reach the right addresses, and enrichment adds valuable data. Poor formatting means broken personalization, failed imports, and wasted time fixing errors lead-by-lead.

Before you start:

What lemlist needs:

💡 Critical rule: First row = column names, not data. If your first row contains an actual email address, lemlist treats it as a column name and skips that lead.

Step 1: Structure your data

Open your spreadsheet (Google Sheets, Excel, etc.)

Ensure:

Step 2: Use standard lemlist variables

Lemlist auto-maps these standard variables:

💡 Match these names exactly for automatic mapping. Use the CSV template as a formatting guide.

Step 3: Add custom variables (optional)

For data beyond standard fields, add custom columns with any names you want (e.g., City, Blog, etc.)

💡 No spaces in column names: Especially critical for URLs.

Step 4: Export as CSV

In Google Sheets: File → Download → Comma-separated values (.csv)

In Excel: File → Save As → CSV (Comma delimited)

⚠️ Important: Use pure CSV format, not "Excel CSV" or other variations.

Step 1: Open the import interface

Go to Campaigns, then open the campaign you want to import leads into.

In your campaign, click Lead list, then click Import new leads.

Step 2: Upload your file

Option A: Click in the upload area and select your CSV file

Option B: Drag and drop your CSV file into the upload area

Then click Continue.

✅ Success indicator: File name appears with lead count detected

Step 3: Map variables

Lemlist displays your columns and suggests mappings:

Auto-mapped columns: Standard variables like email, firstname, lastname are automatically recognized

Unmapped columns: Custom columns or misspelled standard variables need manual mapping

For each unmapped column:

To adjust a mapping, open the variable type dropdown and select the correct lemlist variable.

Select the appropriate variable (for example, lastName for a surname column).

When everything is mapped correctly, click Continue.

💡 Best practice: Use lemlist's default variables when possible: email, firstname, lastname, companyName, companyDomain, linkedinUrl, phone, picture, icebreaker.

Step 4 (optional): Select AI column use cases

If prompted, choose which AI actions you want to apply to your imported columns (for example, cleaning first names), then click Continue.

Step 5: Configure enrichment & duplicate preferences, then import

Select any enrichment options you want to run (these may use credits).

In Manage duplicates, choose whether to skip leads that are already in your campaign (or across your team).

Then click Import leads.

Step 6: Verify import success

After import completes:

✅ Success checklist:

Issue: CSV file won't upload

Root cause: Wrong file format, browser compatibility, or file encoding issues

Fix:

Issue: "Emails are required" error

Root cause: No column mapped to the email field, or the email column is empty for some leads

Fix:

Issue: Personalization shows {{firstname}} instead of actual names

Root cause: firstname column not mapped correctly, or firstname data is empty

Fix:

Issue: Custom variables not appearing in email editor

Root cause: Custom variables created during import but not yet available in the template editor

Fix:

Issue: Only partial leads imported

Root cause: Some leads were duplicates or had missing/invalid emails

Fix:

Use the CSV template - Download lemlist's CSV template to start with the correct structure.

Test with small batch first - Import a small number of leads as a test before your full list. Verify mapping works correctly.

Clean data before import - Remove empty rows, fix email typos, standardize formatting. Cleaning in spreadsheet is faster than fixing in lemlist.

Match standard variable names - Use lemlist's default variables exactly as listed to enable auto-mapping.

Keep files organized - Use meaningful names for custom variables to simplify mapping.

Use enrichment strategically - Enable enrichment options only when you need additional data insights, as they may use credits.

Can I use custom variables?

Yes! Add unique data for personalization (e.g., blog URLs or company info). Lemlist supports unlimited custom variables.

What's the best way to avoid import errors?

Why isn't my CSV importing?