Import Contacts

Import your contacts into Mailtrap using CSV files, API integration, or third-party tools. This guide walks you through each method step by step.

Before You Begin

Preparation Checklist Before uploading contacts, ensure you have:

1. Created all necessary custom fields

2. Cleaned your contact list (removed duplicates, invalid emails)

3. Obtained explicit consent from all recipients

4. Prepared your data in the correct format

Import Methods Overview

CSV Upload

Best for:

• One-time migrations

• Periodic bulk updates

• Offline contact management

Pros:

• Simple and straightforward

• No technical knowledge required

• Visual field mapping

File requirements:

• UTF-8 encoding

• Comma-separated values

• Header row with field names

API Integration

Third-party Tools

CSV Upload Process

1

Prepare Your CSV File

Download the Template

Navigate to Contacts and click Import Contacts.

Import Contacts button in the contacts interface

Download our CSV template by clicking Download CSV Template.

Download CSV Template button for importing contacts

Format Your Data

Structure your CSV with:

• Email column (required)

• Custom field columns matching your created fields

• One contact per row

contacts.csv

email,first_name,last_name,company,signup_date
[email protected],John,Doe,Acme Corp,2024-01-15
[email protected],Jane,Smith,Tech Inc,2024-01-20

2

Upload Your File

Click Browse files or drag and drop your CSV file into the upload area.

File upload area to import contacts CSV file

Click Import File to proceed.

Import File button to proceed with contact upload

3

Map Your Fields

Assign CSV columns to your Mailtrap fields:

• Match column headers to custom fields

• Preview data mapping

• Verify field assignments

Field mapping interface to assign CSV columns to contact fields

Click Confirm Mapping when ready.

Mapping Tips

• Field names are case-insensitive

• Unmapped columns will be ignored

• Email field is automatically mapped if column is named "email"

4

Assign to Lists

Choose which lists should include these contacts:

Add to Existing Lists

Select one or more lists from the dropdown and click Continue.

Interface to add contacts to existing lists

Create New List

Click Create New List, enter a name, and click Create.

Form to create a new contact list

Multiple Lists You can add contacts to multiple lists simultaneously for better segmentation.

Interface showing contacts being added to multiple lists

5

Confirm Consent

Check the consent verification box to confirm you have permission to email these contacts.

Consent confirmation checkbox before importing contacts

Legal Requirement You cannot proceed without confirming consent. Ensure you have explicit permission from all contacts before importing.

Click Confirm Import to complete the process.

6

Import Confirmation

You'll receive a success notification once the import is complete.

Success notification after contacts are imported

Your contacts are now available under Contacts and in their assigned Lists.

API Import

Quick Start

cURL

Add single contact

curl -X POST https://api.mailtrap.io/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "lists": ["list_id_1", "list_id_2"]
  }'

Node.js

Python

For complete API documentation, see Contacts API Reference.

Third-party Integrations

Zapier Integration

1

Connect Mailtrap

Add Mailtrap as an action in your Zap.

2

Configure Trigger

Set up your trigger app (CRM, form, spreadsheet).

3

Map Fields

Match trigger data to Mailtrap contact fields.

4

Test & Activate

Run a test and activate your Zap.

Make.com Scenario

Create automated workflows that sync contacts from multiple sources:

Example Scenario

{
  "trigger": "New form submission",
  "actions": [
    {
      "app": "Mailtrap",
      "action": "Create/Update Contact",
      "fields": {
        "email": "{{form.email}}",
        "first_name": "{{form.name}}",
        "source": "Website Form"
      }
    }
  ]
}

Import Best Practices

Data Quality Guidelines

1. Validate emails: Remove invalid or malformed addresses

2. Remove duplicates: Clean your list before importing

3. Standardize formats: Use consistent date and text formats

4. Test small batches: Import a test batch first

5. Monitor bounces: Track delivery after first campaign

Handling Import Errors

Import Limits

Upload Specifications

• File size: Up to 10MB per CSV

• Contacts per import: Up to 50,000

• Import frequency: No limit

• Processing time: 1-5 minutes for large files