/v1/workspaces/{workspace_id}/contacts/importsAuthImport contacts from a CSV file
Queues the file and returns the import (`status: queued`); poll `GET .../contacts/imports/{id}` for progress. At most 10 MB and 100,000 rows, two imports running per workspace. Rows that assert consent (`consent` true or a `consented_at` date) are recorded with it and opted in to `topic_ids`; every other row starts without consent. An import emits no per-contact webhook events.
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.
Request body
csv*stringThe CSV file content, UTF-8, at most 10 MB and 100,000 rows. The first line is a header with an `email` column. Optional columns: `first_name`, `last_name`, `unsubscribed` (true/false), `consent` (true/false), `consented_at` (ISO 8601), `consent_source`, and any defined contact property key. Headers are case-insensitive (`First Name` works). Other columns are ignored and reported. A row is consented only when it says so (`consent` true, or a `consented_at` date); every other imported contact starts without consent and receives only topics it later opts in to.
Example: "email,first_name,consent,consented_at\nada@example.com,Ada,true,2026-10-01T09:00:00Z\n"
on_conflict*enum (2)`upsert` updates an existing contact (provided fields; properties merge); `skip` leaves existing contacts unchanged. Either way an import never re-subscribes a contact that unsubscribed and never overrides a topic opt-out.
consent_sourcestringRecorded as `consent_source` on consented rows that have no `consent_source` column value. Defaults to `import`.
Example: "webinar-2026-10"
topic_idsarrayOpt the consented rows in to these topics (existing opt-outs win).
filenamestringThe file name, for display.
Example: "newsletter.csv"
Response · 202 Queued.
id*string · uuidThe import id.
status*objectWhere the import is: `queued`, `processing`, then `completed` or `failed`.
on_conflict*objectWhat happens to a row whose email is already a contact: `upsert` updates it, `skip` leaves it.
filename*stringThe uploaded file's name, if one was given.
size_bytes*numberSize of the uploaded CSV in bytes.
consent_source*stringWhere the consent for these contacts came from, stored on every imported contact.
topic_ids*arrayTopics every imported contact was subscribed to.
total_rows*numberData rows in the file (header excluded); 0 until processing starts.
processed_rows*numberRows processed so far.
created_count*numberRows that created a new contact.
updated_count*numberRows that updated an existing contact.
skipped_count*numberExisting contacts left alone (`skip`), and duplicate rows.
error_count*numberRows that could not be imported.
consented_count*numberRows that asserted consent.
errors*arrayThe first 100 problems, with line numbers.
failure_reason*stringWhy a `failed` import stopped.
created_at*string · date-timeWhen the import was submitted.
started_at*string · date-timeWhen processing started; null while `queued`.
completed_at*string · date-timeWhen processing finished; null until then.
Example
Request
POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/contacts/imports
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"csv": "email,first_name,consent,consented_at\nada@example.com,Ada,true,2026-10-01T09:00:00Z\n",
"on_conflict": "upsert",
"consent_source": "webinar-2026-10",
"topic_ids": [
"00000000-0000-0000-0000-000000000000"
],
"filename": "newsletter.csv"
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"status": {},
"on_conflict": {},
"filename": "string",
"size_bytes": 0,
"consent_source": "string",
"topic_ids": [
"00000000-0000-0000-0000-000000000000"
],
"total_rows": 0,
"processed_rows": 0,
"created_count": 0,
"updated_count": 0,
"skipped_count": 0,
"error_count": 0,
"consented_count": 0,
"errors": [
{
"line": 0,
"error": "invalid or missing email"
}
],
"failure_reason": "string",
"created_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z"
}