CSV Upload Guide

Learn the ins and outs of uploading contacts via CSV. This guide covers file formatting, column mapping, troubleshooting, and best practices for bulk imports.

CSV File Requirements

Required Columns

Your CSV must have these three columns:

• email - Valid email address (unique identifier)
• first_name - Contact's first name
• last_name - Contact's last name

Optional Columns (Recommended)

Add these columns for better personalization:

• company - Company name
• job_title - Job title or role
• industry - Industry vertical
• website - Company website (for AI enrichment)
• recent_news - Recent company news or triggers
• pain_point - Known challenges

Custom Columns

Add any additional columns you need! Examples:

• company_size
• location
• lead_source
• linkedin_url
• phone

Example CSV Format

email,first_name,last_name,company,job_title,website,industry
john@acme.com,John,Smith,Acme Corp,VP Sales,acme.com,SaaS
sarah@techco.com,Sarah,Chen,TechCo,Head of Growth,techco.com,Technology
mike@startup.io,Mike,Johnson,Startup Inc,Founder,startup.io,E-commerce

Upload Process

1. Prepare CSV File - Ensure all required columns are present with correct headers
2. Navigate to Contacts Page - Click "Contacts" in sidebar, then "Upload CSV"
3. Select File - Click "Select CSV file" and choose your file (max 10MB)
4. Map Columns - System auto-detects standard fields, verify mappings are correct
5. Assign to List (Optional) - Select a contact list to add contacts to
6. Preview - Review first 5 contacts to ensure data looks correct
7. Import - Click "Import X Contacts" to complete upload

Column Mapping

WarmOpener automatically detects and maps common column names:

• Email: Recognizes "email", "Email", "email_address", "Email Address"
• First Name: Recognizes "first_name", "First Name", "firstname", "FirstName"
• Last Name: Recognizes "last_name", "Last Name", "lastname", "LastName", "surname"
• Company: Recognizes "company", "Company", "company_name", "organization"

For unrecognized columns, manually select the appropriate field from the dropdown or map to a custom field.

Common Issues & Solutions

Issue: "Missing required columns"

• Cause: CSV doesn't have email, first_name, or last_name columns
• Solution: Add these columns to your CSV before uploading

Issue: "Duplicate email addresses"

• Cause: Some contacts already exist in database
• Solution: Duplicates are skipped automatically. Only new contacts are imported.

Issue: "File size too large"

• Cause: CSV exceeds 10MB limit
• Solution: Split CSV into smaller files and upload separately

Issue: "Invalid email format"

• Cause: Some rows have malformed email addresses
• Solution: Clean your data, ensure all emails match format: name@domain.com

Issue: "Contact limit reached"

• Cause: Importing would exceed your plan's contact limit
• Solution: Upgrade your plan or wait until next billing cycle (limits reset monthly)

File Size & Performance

• Max file size: 10MB
• Import speed: ~1000 contacts per minute
• Large files: Split into multiple CSVs for faster uploads

⚠️ Data Privacy

Ensure you have permission to email all contacts in your CSV. Uploading contacts without consent violates anti-spam laws (CAN-SPAM, GDPR, etc.) and can result in account suspension.

💡 Pro Tip

Before uploading 10,000 contacts, test with a small sample (10-20 rows) to ensure your column mapping is correct. This saves time if you need to fix formatting issues in your source data.