Skip to main content

How to import leads from a CSV file

How to Import CSV Files to lemlist Like a Pro 📄

Learning Objective

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.

Why This Matters

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.

Without correct column mapping:

  • ❌ LinkedIn steps skip because {{linkedinUrl}} isn't recognized

  • ❌ Emails fail because {{email}} isn't mapped

  • ❌ Personalization breaks (wrong names, missing company data)

With correct column mapping:

  • ✅ LinkedIn steps run

  • ✅ Emails send to the right addresses

  • ✅ Personalization works correctly

Prerequisites

Before you start:

  • A CSV file with your lead data (email addresses required)

  • Basic understanding of spreadsheet structure (rows = leads, columns = data fields)

  • A campaign created where you'll import the leads

Understanding CSV Structure

What lemlist needs:

  • Row 1: Column names (email, firstName, companyName, etc.)

  • Row 2+: Lead data, one lead per row

  • Required column: email (every lead must have one)

  • Optional columns: Any additional data for personalization

💡 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-by-Step Guide

Phase 1: Format Your CSV File

Step 1: Structure your data

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

Ensure:

  • Row 1 contains column names only

  • No spaces in column names (especially for URLs)

  • Each row has an email address (required)

  • No empty rows between leads

Step 2: Use standard lemlist variables

Lemlist auto-maps these standard variables:

  • email (required)

  • firstname

  • lastname

  • companyName

  • companyDomain

  • linkedinUrl

  • phone

  • picture

  • icebreaker

💡 Match these names exactly for automatic mapping. Use the CSV template as a formatting. If you are importing data from a CRM such as HubSpot, ensure all custom variables are included within the 'Contact' section for proper mapping 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.

Phase 2: Import into Lemlist

Step 1: Open the import interface

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

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

Step 2: Upload your file

Select CSV import, then click in the upload area or drag and drop your CSV file.

Step 3: Review and map your fields

Lemlist displays your CSV columns and suggests mappings for each one. Review them carefully before continuing.

If a column is not mapped the way you want, open the dropdown and select the correct field or create a custom field.

💡 If your CSV has multiple email or LinkedIn columns, make sure you assign the exact column you want lemlist to use as the default ({{email}} and/or {{linkedinUrl}}).

When all fields are mapped correctly, click Continue.

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

Step 4: Select AI column use cases (optional)

If prompted, choose any AI actions you want to apply to your imported data, then click Continue.

Step 5: Configure enrichment options

Choose any enrichment options you want to run. Keep in mind these options may use credits.

Step 6: Manage duplicates and import

In Manage duplicates, choose how lemlist should handle leads that are already in the campaign or already exist in your team workspace. Then click Import leads.

Step 7: Verify import success

After import completes:

  • Check the lead count increased in the Leads list

  • Review a few leads to confirm data is mapped correctly

  • Test personalization variables in email preview

✅ Success checklist:

  • Lead count matches the expected number

  • Personalization variables display correctly

  • No error messages about failed imports

Troubleshooting

Issue: CSV file won't upload

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

Fix:

  • Browser Compatibility: Use Chrome or another updated browser instead of Safari

  • File Format: Ensure your file is a pure .CSV and not an Excel CSV. Convert if necessary

  • Re-export as pure CSV from your spreadsheet app

  • Check file extension is .csv not .xlsx or .xls

Issue: "Emails are required" error

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

Fix:

  • Emails Are Required: Every row must have an email address, as it serves as the unique ID in lemlist

  • Ensure you have a column with email addresses

  • Map that column to the "email" variable

  • Remove rows without email addresses

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

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

Fix:

  • Return to Lead list, check a few leads, does the firstname field have data?

  • If empty: firstname wasn't mapped during import. Re-import CSV and map correctly

  • Field Matching: Map your CSV fields to the appropriate lemlist variables

Issue: Custom variables not appearing in email editor

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

Fix:

  • Refresh the campaign page

  • Custom variables should now appear in the variable dropdown

  • Check spelling matches exactly

Issue: Only partial leads imported

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

Fix:

  • Check import summary message, explains why some were skipped

  • Review skipped leads, fix issues, re-import if needed

    Issue: Accented characters appear as ◆ symbols

    Root cause: CSV file is not encoded in UTF-8

    Fix: Convert your CSV to UTF-8 encoding before importing. See Fix diamond question marks in CSV imports for steps.

Optimization Tips

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.

FAQs

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?

  • Use the CSV template as a guide

  • Test your import with a small file first

  • Ensure the first row contains column names

  • Avoid spaces in column names

Why isn't my CSV importing?

  • Double-check the format: pure .CSV only

  • Ensure column names match lemlist variables

  • Verify your browser and file compatibility

Related Articles
Did this answer your question?