Mail API reference

Mail API · Contacts

post/v1/workspaces/{workspace_id}/contacts/importsAuth

Import 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 · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque 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*string

The 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_sourcestring

Recorded as `consent_source` on consented rows that have no `consent_source` column value. Defaults to `import`.

Example: "webinar-2026-10"

topic_idsarray

Opt the consented rows in to these topics (existing opt-outs win).

filenamestring

The file name, for display.

Example: "newsletter.csv"

Response · 202 Queued.

id*string · uuid

The import id.

status*object

Where the import is: `queued`, `processing`, then `completed` or `failed`.

on_conflict*object

What happens to a row whose email is already a contact: `upsert` updates it, `skip` leaves it.

filename*string

The uploaded file's name, if one was given.

size_bytes*number

Size of the uploaded CSV in bytes.

consent_source*string

Where the consent for these contacts came from, stored on every imported contact.

topic_ids*array

Topics every imported contact was subscribed to.

total_rows*number

Data rows in the file (header excluded); 0 until processing starts.

processed_rows*number

Rows processed so far.

created_count*number

Rows that created a new contact.

updated_count*number

Rows that updated an existing contact.

skipped_count*number

Existing contacts left alone (`skip`), and duplicate rows.

error_count*number

Rows that could not be imported.

consented_count*number

Rows that asserted consent.

errors*array

The first 100 problems, with line numbers.

failure_reason*string

Why a `failed` import stopped.

created_at*string · date-time

When the import was submitted.

started_at*string · date-time

When processing started; null while `queued`.

completed_at*string · date-time

When 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"
}