Email.com docsOpen the app

Guides

Importing contacts from a CSV file

An audience is filled from a CSV file in four calls: open an import with its consent block and the column mapping, upload the file to the address the answer gives, start the import, and read its progress until it ends. The file never passes through the API: it goes straight to storage through a presigned upload, and the platform's contact store keeps every address (as a hash and an encrypted copy). Broadcasts keeps the counts, the consent facts and the failed row numbers, never a cell value.

Consent comes first

Broadcasts sends to permission-based lists only. Every import carries a consent block, and a request without one is refused before anything is stored: the request schema answers 400 with the validation problem and the path consent. The block names where the consent was collected and when:

{
  "consent": { "source": "signup form", "collected_at": "2026-09-01T00:00:00.000Z" },
  "mapping": { "email": "Email", "fields": { "first_name": "First name", "plan": "Plan" } },
  "size_bytes": 48213
}

The calls

StepRouteWhat it does
OpenPOST /v1/audiences/{audience_id}/imports (broadcasts.createAudienceImport)Stores the import as created and answers upload_url, a presigned PUT that lives 15 minutes; needs an Idempotency-Key
UploadPUT <upload_url>The file as the request body, sent from the browser or a script; no API token rides it
StartPOST /v1/audiences/{audience_id}/imports/{import_id}/start (broadcasts.startAudienceImport)409 with import.not_uploaded while no file is there, 409 with import.size_mismatch when the file is larger than size_bytes, 409 with import.finished for an import that already ended; otherwise 202 and the import is running (a second start of a running import answers it again)
ProgressGET /v1/audiences/{audience_id}/imports/{import_id} (broadcasts.getAudienceImport)state, rows_total, rows_ok, rows_failed, rows_duplicate and up to 20 failures

Opening and starting share the import rate class: 5 a minute per API key or member. At most 3 imports run at a time per tenant (a fourth start is 409 with import.concurrent_limit). The states are created, uploaded, running, completed and failed; a finished import is kept for 90 days, then the tenant's next completed import removes it.

The file

The mapping

Row results

Each data row ends as one of three counts:

CodeScopeMeaning
csv.columnsrowthe row has another number of columns than the header
csv.malformedrowthe row is not valid CSV (a stray quote)
cell.too_longrowa mapped cell is longer than 1,024 bytes
email.missingrowthe address cell is empty
email.invalidrowthe address is not valid
platform.refusedrowthe contact store refused the row
csv.quote_not_closedfilea quote is never closed, so the rest of the file cannot be read
csv.record_too_largefilea record or a line is past its bound
import.columns_maxfilemore than 32 columns
import.header_duplicatefiletwo header cells have the same name
import.header_missingfilethe header is missing or a mapped column is not in it
import.mapping_emailfilethe address column is also mapped to a field
import.rows_maxfilemore than 500,000 data rows
import.pages_maxfilethe file needs more pages than one import reads
import.too_largefilethe file is larger than declared or than 50 MiB
import.file_missingfilethe file is gone before the import read it
import.no_progressfilethe import stopped moving: a page read nothing new, or nothing moved for 6 hours (the tenant's next import start ends it)
import.not_readyfilea page waited for the page before it past its time
import.task_refusedfilethe import could not run; open a new one

A row code skips its row and the import goes on. A file code fails the whole import (failed): it is listed first in failures with row: null (the file, not a row) and the uploaded file is deleted. Rows written by earlier pages stay written, so a corrected file can simply be imported again (the contact store updates the existing contacts).

When the import ends

The last page records the totals, deletes the uploaded file and emits audience.import.completed.v1 with the audience, the import, rows_total, rows_ok, rows_failed, rows_duplicate, the consent_source and completed_at: ids, counts and the consent label, never a row. Subscribe to it through webhooks to start a campaign when an import lands.