Overview
Import hundreds or thousands of contacts at once using CSV files. Migma automatically validates emails, maps columns, handles duplicates, and provides detailed import results.Bulk Import
Upload thousands of contacts instantly
Auto-Mapping
Smart column detection and mapping
Validation
Email validation and error handling
CSV Format
Required Column
Email - Required in every CSV fileSupported Standard Columns
| Column Name | Description | Example |
|---|---|---|
email | Email address (required) | [email protected] |
firstName or first_name | First name | John |
lastName or last_name | Last name | Doe |
name | Full name | John Doe |
language | Preferred language (ISO 639-1) | en, es, fr |
country | Country (ISO 3166-1 alpha-2) | US, GB, CA |
status | Subscription status | subscribed, unsubscribed |
Custom Fields
Any column not matching standard names becomes a custom field automatically. Example CSV:company and jobTitle are stored as custom fields.
Import Process
1
Navigate to Contacts
Go to Contacts page in your project
2
Click Import CSV
Click “Import CSV” or “Bulk Import” button
3
Upload File
- Drag & drop CSV file or click to browse
- Max file size: 10MB
- Formats: .csv, .txt
4
Map Columns
Review automatic column mapping:
- Migma auto-detects standard columns
- Verify email column is correctly mapped
- Custom fields are automatically identified
- Adjust mappings if needed
5
Set Options
Configure import:
- Default Status: Subscribed, unsubscribed, or non-subscribed
- Tags: Add tags to all imported contacts (optional)
- Skip Header: Auto-detected, verify it’s correct
6
Review & Import
- Preview shows first 5 rows
- Total contacts to import displayed
- Click “Import Contacts” to start
7
View Results
Import summary shows:
- ✅ Successfully imported
- ⏭️ Skipped (duplicates)
- ❌ Failed (validation errors)
Column Mapping
Migma automatically detects column names. Common variations are supported: Email columns (required):email,Email,EMAILe-mail,e_mail
firstName,first_name,First NamelastName,last_name,Last Namename,Name,fullName
language,lang,localecountry,countryCode,country_codestatus,subscriptionStatus,subscription_status
company, phone, userId)
Validation & Handling
Email Validation
Emails are validated automatically:Valid format ([email protected])
Valid domain
No duplicates within CSV
Not already in your contact list
Duplicate Handling
- Within CSV
- Existing Contacts
If CSV contains duplicate emails:
- Only first occurrence is imported
- Subsequent duplicates are skipped
- Count shown in import results
Status Handling
Default status (set in UI):- Applied to all contacts without status column
- Options: Subscribed, Unsubscribed, Non-subscribed
- Include
statuscolumn to set per-contact - Values:
subscribed,unsubscribed,non-subscribed,bounced - Overrides UI default for that row
Tags
Add tags during import:1
UI Tag Selection
Use the tag selector to add tags to ALL imported contacts
2
Example Uses
- Source:
CSV-Import-2024 - Campaign:
Q4-Newsletter - Type:
Event-Attendees
CSV tags column is not currently supported. Use UI tag selector to apply tags to all imported contacts.
Import Results
After import completes, you’ll see a detailed summary: Example result:- Which emails were skipped (with reason)
- Which emails failed validation
- Error messages for failed rows
CSV Examples
- Minimal (Email Only)
- Standard Fields
- With Custom Fields
- With Status
Best Practices
Prepare Your CSV
Prepare Your CSV
Before uploading:
- Remove test data and internal emails
- Verify email column exists
- Check for duplicate emails
- Use consistent column names
- Remove special characters from column headers
- Use UTF-8 encoding for international characters
Tag Your Imports
Tag Your Imports
Always add tags:
- Import source:
Mailchimp-Export,EventBrite - Import date:
Import-Nov-2024 - Campaign:
Webinar-Attendees
Verify Before Sending
Verify Before Sending
After import:
- Check import results for errors
- Review a few contacts to verify data
- Filter by import tags to see the group
- Send test email before bulk campaign
Manage List Hygiene
Manage List Hygiene
Keep lists clean:
- Don’t import purchased lists (spam risk)
- Import only opted-in contacts
- Honor existing unsubscribe status
- Remove bounced emails promptly
Troubleshooting
All contacts skipped as duplicates
All contacts skipped as duplicates
Cause: Email addresses already exist in your contact listSolution:
- Check if contacts were previously imported
- Use different CSV or clean existing duplicates
- Note: Existing contacts are NOT updated during import
Email column not detected
Email column not detected
Cause: Column name not recognized as emailSolution:
- Ensure column is named
email,Email, ore-mail - Manually map column during import step
- Rename column header in CSV if needed
Many emails failed validation
Many emails failed validation
Cause: Invalid email formatsSolution:
- Review failed emails in import results
- Clean email list before importing
- Verify emails don’t have extra spaces
- Check for proper email format ([email protected])
Custom fields not showing
Custom fields not showing
Cause: Column names match standard field variationsSolution:
- Use unique names for custom fields
- Avoid names like
name,email,status - Check imported contacts to see custom field data
File upload fails
File upload fails
Cause: File too large or wrong formatSolution:
- Max size: 10MB
- Format: .csv or .txt
- Try saving as CSV UTF-8 from Excel/Sheets
- Split large files into smaller batches
Next Steps
Manage Contacts
View and organize imported contacts
Send Campaign
Send emails to your imported list
Preference Center
Set up subscription management
API Import
Import programmatically via API