Cllavio.
LoginGet Started
OverviewFeaturesPricingContact

CSV Import

Upload .csv files with a header row to add contacts to a Group. Invalid rows are skipped. If your plan’s contact cap is reached, the job stops and shows LIMIT_REACHED.

Overview

Cllavio accepts CSV files with a single header row. We parse using CSVFormat.DEFAULT.withFirstRecordAsHeader(); unknown columns are ignored. Each valid row becomes a contact in the selected Group.

File format

  • File type: .csv
  • Encoding: UTF‑8
  • Delimiter: auto‑detected by Apache Commons CSV ("," recommended)
  • Header row: required (first line)
  • Whitespace: leading/trailing trimmed; internal multiple spaces collapsed

Accepted headers

Required

  • email — must be a valid email (simple RFC‑like check).

Optional (aliases supported)

  • first_name or firstName
  • last_name or lastName
  • is_subscribed or isSubscribed — defaults to true when omitted.

Any other columns are ignored.

Boolean values

Accepted truthy tokens for is_subscribed / isSubscribed are: 1, true, yes (case‑insensitive). Any other value is treated as false.

Sample CSV (v1)

email,first_name,last_name,is_subscribed
jane@example.com,Jane,Doe,true
john@example.org,John,Doe,0
bad-email@,Foo,Bar,yes
Download sample CSV

Upload flow & status

  1. Browser uploads your file to server, then streams to S3.
  2. Status updates during upload: UPLOADING → FINALIZING → VERIFYING.
  3. Worker parses and saves contacts: PROCESSING → COMPLETED (or LIMIT_REACHED/FAILED).

Large files are handled in batches. Progress is sent live to the UI.

Validation & skipping

  • Rows with invalid email are skipped.
  • Missing email → skipped.
  • One contact per row. Avoid duplicate emails within the same file.
  • If an address is on your global unsubscribe list, it is imported as unsubscribed.

Limits & quotas

  • Imports stop automatically when your remaining contact quota is reached (LIMIT_REACHED).
  • Very large files may take several minutes to process after upload completes.

Errors

400 Bad Request

  • Missing header row or required email column
  • File type not supported
{ "status": 400, "message": "Missing required column: email" }

409 Limit Reached

  • Organization contact quota exhausted
{ "status": 409, "message": "Contact quota reached" }

500 Import Failed

  • Unexpected server/S3 error during upload or parsing
{ "status": 500, "message": "CSV import failed" }
Back to top