Mail API reference

Mail API · Contacts

get/v1/workspaces/{workspace_id}/contacts/imports/{import_id}Auth

Get a contact import and its progress

Path parameters

workspace_id*string · uuid

Id of the workspace.

import_id*string · uuid

Id of the import.

Response · 200

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

GET https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/contacts/imports/{import_id}
Authorization: Bearer YOUR_TOKEN

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