Importing Contacts from CSV
Bulk import contacts from a CSV file with column mapping.
The CSV import feature lets you upload many contacts at once. You map columns from your file to Mailnaptic fields, assign contacts to lists, and apply tags in bulk. CSV import and export are available on the Starter plan and above; on the Free plan the Import button takes you to the Billing page.
Preparing Your File
- Save your file in CSV format (comma-separated values).
- Include a header row with descriptive column names (e.g., email, first_name, last_name).
- The email column is required. All other fields are optional.
- Limits: up to 100,000 rows and 10 MB per file. The first step of the import dialog always shows the current limits.
Import Steps
- Go to Contacts and click Import (you can also use Import contacts on a list’s page).
- 1. Upload — Choose your CSV file, or paste CSV text into the box, then click Next.
- 2. Map columns — For each column in your file, choose what it maps to: Email, First name, Last name, Tags (comma-separated), Lead score, Country, City, Timezone, an existing custom field, or + New custom field. Columns set to -- Skip -- are ignored. Click Next.
- 3. Validate — Mailnaptic checks every email address and reports how many are valid, have invalid syntax, have no MX record, or are disposable. Click Continue with the valid contacts, or Import all to include everything. You can also tick individual flagged addresses to include them anyway.
- 4. Options — Choose the Lists to add contacts to and optionally Tags to apply to all contacts. Choose how to handle Duplicate contacts (Update existing contacts or Skip existing contacts). Optionally turn on Send double opt-in confirmation emails and Trigger automations for imported contacts. You must tick the box confirming you have a legal basis to email the contacts. The confirmation is saved in the audit log.
- Click the Import button, which shows the number of contacts to be imported.
Import Processing
The import runs in the background. You can close the dialog and continue working; you will receive a notification when it is done.
Duplicate Handling
If a contact with the same email already exists, the Duplicate contacts option decides what happens: Update existing contacts overwrites their name and other fields, while Skip existing contacts leaves them unchanged. Either way, no duplicates are created.
Unsubscribed and bounced contacts stay that way
An import never brings back someone who has unsubscribed, complained or bounced. Those contacts stay suppressed until they sign up again themselves, for example through a signup form or the preference center. The same applies to contacts added through the API.
Double opt-in on large imports
Importing with Send double opt-in confirmation emails sends one email per contact and list, so it is limited to 5,000 rows per import. Split larger files, or import without confirmation emails if the contacts have already confirmed. An address receives at most three confirmation emails a day from Mailnaptic, whoever asked for them.
Importing through the API
The import endpoint POST /contacts/import needs "consent_attested": true in the request, the same statement you tick in the app. Without it the request is refused with the code CONSENT_ATTESTATION_REQUIRED.
Important:
Only import contacts who have given you explicit permission to email them. Importing purchased or scraped lists violates Mailnaptic’s Terms of Service and will damage your deliverability.