Import Mailboxes from CSV

post

https://app.mailivery.io/api/v1/campaign-imports

Create warm-up mailboxes in bulk by uploading a CSV file.

File limits: Accepts a .csv file (or a .txt file with a CSV header row) up to 10 MB and at most 5,000 mailbox rows.
Security: The uploaded file isn't saved. Passwords are queued encrypted for processing, and no endpoint returns them.
Immediate validation: Rows with missing fields, invalid hosts/ports, in-file duplicates, emails that already exist in Mailivery, emails still queued in another of your imports, or emails-per-day / response-rate values over your account's limits are rejected immediately in the 202 Accepted response.
Asynchronous processing: Accepted rows are queued with encrypted payloads: Mailivery connects to SMTP and IMAP for each mailbox and creates it asynchronously through the same path as POST /campaigns/smtp.
Workflow:
1. Upload CSV to POST /campaign-imports (returns 202 Accepted with import ID and any immediate rejections).
2. Poll GET /campaign-imports/{import} until status is completed (see that endpoint for what to do if the counters stop moving).
3. Query GET /campaign-imports/{import}/rows to inspect individual mailbox creation results and error messages.
Emails-per-day allowance is checked top to bottom. Rows are counted against your account's total daily emails-per-day allowance in file order, and a row that would take the total past it is rejected with EPD_LIMIT_EXCEEDED. Accounts with no total limit skip this check. To retry rejected or failed rows, wait until the first import is completed (if it has stalled, see Get Import Status), then upload a new CSV with only those rows.

Google Workspace mailboxes (App Password)

Each Google account needs 2-Step Verification turned on. Put the same 16-character app password in both smtp_password and imap_password (a regular account password will not work), and use smtp.gmail.com on port 465 (port 587 also works) and imap.gmail.com on port 993.

Mailboxes added this way show provider_type: "smtp" in API responses and the campaign.created webhook. Mailivery still recognizes them as Google mailboxes from their host: they appear as Gmail in the dashboard, and warm-up, sending and replies go through the Google path.

Row error codes

Rejected and failed rows carry an error_code and a readable error_message. Common codes:

Code	When
`VALIDATION_ERROR`	A cell is missing or invalid (port, host, enum value, ramp-up speed)
`DUPLICATE_IN_FILE`	The email appears on an earlier row of the same file
`DUPLICATE_IN_PROGRESS`	The email is still queued or processing in another of your imports
`EMAIL_TAKEN`	A mailbox with this email already exists
`PER_CAMPAIGN_EPD_LIMIT_EXCEEDED`	The row's `email_per_day` is above your per-mailbox limit
`EPD_LIMIT_EXCEEDED`	Adding the row would take you past your account's total daily allowance
`CREDENTIALS_INVALID`	Mailivery could not log in to SMTP or IMAP with the row's credentials. `error_message` carries the mail server's reply.
`AUTHORIZATION_ERROR`	Your API access was turned off while the import was running
`CREATE_FAILED`	The mailbox could not be created for another reason

CSV Columns

The first row must contain column headers (case-insensitive). Column order does not matter and unknown columns are ignored.

The dashboard's CSV template uses the same column names, so you can start from it. It has every column below except imap_email.

Standard CSV quoting (RFC 4180): quote a cell that contains a comma, and write a double quote inside a quoted cell as two double quotes. A backslash has no special meaning.
Every cell is trimmed, passwords included, as on every other create endpoint.
An empty cell means "not provided" and takes the default below.

Required Columns (10)

Column	Type	Description
`email`	string	Mailbox email address (must be valid RFC email)
`first_name`	string	First name for the mailbox sender
`smtp_username`	string	Username for outgoing SMTP authentication
`smtp_password`	string	Password or app password for outgoing SMTP
`smtp_host`	string	Outgoing SMTP server hostname (e.g. `smtp.gmail.com`)
`smtp_port`	integer	Outgoing SMTP port (allowed: `465`, `587`, `25`, `2525`, `8025`)
`imap_username`	string	Username for incoming IMAP authentication
`imap_password`	string	Password or app password for incoming IMAP
`imap_host`	string	Incoming IMAP server hostname (e.g. `imap.gmail.com`)
`imap_port`	integer	Incoming IMAP port (allowed: `993`, `143`)

Optional Columns

Column	Type	Default	Description
`last_name`	string	`null`	Last name for the mailbox sender
`imap_email`	string	`email` value	IMAP account email if different from main email
`email_per_day`	integer	Mailivery default	Daily warm-up email target (`0` to `2000`, and within your account's per-mailbox limit)
`response_rate`	integer	Mailivery default	Target response rate percentage (`0` to `100`, and within your account's limit)
`with_rampup`	string	Off	Enable gradual ramp-up: `true` or `false` (case-insensitive). Any other value, e.g. `yes`, rejects the row with `VALIDATION_ERROR`. Empty means ramp-up stays off.
`rampup_speed`	string	—	`slow`, `normal` or `fast`. Required when `with_rampup` is `true`: a row with `with_rampup=true` and no speed is rejected with `VALIDATION_ERROR`. Ignored when ramp-up is off, but a value that is given must still be one of the three.
`timezone`	string	Your team's schedule timezone	Valid IANA timezone (e.g. `America/New_York`, `UTC`)
`sending_schedule_presets`	string	None (no preset applied)	One of `Weekdays - 8am to 6pm`, `Weekdays - 7am to 7pm`, `Weekdays - 6am to 10pm`, `With Weekends - 8am to 6pm`, `With Weekends - 7am to 7pm`, `With Weekends - 6am to 10pm`. Any other value rejects the row with `VALIDATION_ERROR`. Empty means the mailbox keeps its default schedule, copied from your team's schedule (Mon–Fri 09:00–18:00, America/Chicago if the team has none).
`tags`	string	`null`	Comma-separated tags. Quote the cell when it holds more than one tag: `"warmup,gws"`
`warmup_audience_type`	string	`inherit`	Warm-up audience: `inherit` (team setting), `all`, `business` or `consumer`. Empty means inherit.

Responses

`VALIDATION_ERROR`: the file is over 10 MB, isn't a `.csv` or `.txt` file, is empty, has only a header row, or is missing required columns (listed in `data.missing_columns`). For a problem with the file itself, the reason is in `data.file`, for example "The file must be a file of type: csv, txt."
`TOO_MANY_ROWS`: the file has more than 5,000 rows.

202Import queued successfully. Poll the import status for progress.

403Authorization error (user is not an account owner with active API access).

500Internal server error. Some rows may already have been queued, and no import ID is returned, so contact the Mailivery Support team before uploading the same file again.