Docs / API reference

Imports

CSV import: upload, map columns, start, then poll for the result.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

CSV import presets

GET /v1/contacts/import-presets

Common export layouts: column-name patterns (compared lowercase, letters and digits only) → attribute keys, and source status values → contact status (skip leaves the row out). A column mapped to status sets the contact status.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "data": [{
    "id": string,
    "name": string,
    "description": string,
    "columns": [{ … }],
    "statusColumn": [string],
    "statusMapping": map of string
  }]
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Import history

GET /v1/contacts/imports

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "data": [{
    "id": string,
    "object": "import",
    "status": "uploaded" | "processing" | "completed" | "failed",
    "fileName": string,
    "totalRows": number,
    "columns": [{ … }],
    "mapping": map of string or null,
    "listIds": [string],
    "updateExisting": boolean,
    "result": {
      "created": number,
      "updated": number,
      "skipped": number,
      "invalid": number,
      "errors": [{ … }],
      "statuses": map of number,
      "quality": { … }
    },
    "options": {
      "preset": string or null,
      "statusMapping": map of string,
      "consentConfirmedElsewhere": boolean,
      "fixTypos": boolean
    },
    "detectedPreset": string or null,
    "statusValues": [{ … }],
    "createdAt": string,
    "completedAt": string or null
  }],
  "nextCursor": string or null
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Upload a CSV file (step 1)

POST /v1/contacts/imports

Send JSON { "fileName": "contacts.csv", "csv": "<file text>" } or multipart/form-data with a file field. UTF-8, up to 50 MB and 500,000 rows; , ; and tab delimiters are detected. The response lists the columns with sample values and a suggested attribute for each. Nothing is imported until you call /start.

Authentication: Authorization: Bearer with an API key or a session token.

Responses

201 Success

{
  "id": string,
  "object": "import",
  "status": "uploaded" | "processing" | "completed" | "failed",
  "fileName": string,
  "totalRows": number,
  "columns": [{
    "name": string,
    "samples": [string],
    "suggested": string or null,
    "values": [{ … }]
  }],
  "mapping": map of string or null,
  "listIds": [string],
  "updateExisting": boolean,
  "result": {
    "created": number,
    "updated": number,
    "skipped": number,
    "invalid": number,
    "errors": [{
      "row": number,
      "message": string
    }],
    "statuses": map of number,
    "quality": {
      "checked": number,
      "typos": number,
      "typosFixed": number,
      "noMx": number,
      "disposable": number,
      "samples": [{ … }],
      "available": boolean
    }
  },
  "options": {
    "preset": string or null,
    "statusMapping": map of string,
    "consentConfirmedElsewhere": boolean,
    "fixTypos": boolean
  },
  "detectedPreset": string or null,
  "statusValues": [{
    "value": string,
    "count": number,
    "suggested": string
  }],
  "createdAt": string,
  "completedAt": string or null
}
Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Get an import (poll while processing)

GET /v1/contacts/imports/{id}

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "id": string,
  "object": "import",
  "status": "uploaded" | "processing" | "completed" | "failed",
  "fileName": string,
  "totalRows": number,
  "columns": [{
    "name": string,
    "samples": [string],
    "suggested": string or null,
    "values": [{ … }]
  }],
  "mapping": map of string or null,
  "listIds": [string],
  "updateExisting": boolean,
  "result": {
    "created": number,
    "updated": number,
    "skipped": number,
    "invalid": number,
    "errors": [{
      "row": number,
      "message": string
    }],
    "statuses": map of number,
    "quality": {
      "checked": number,
      "typos": number,
      "typosFixed": number,
      "noMx": number,
      "disposable": number,
      "samples": [{ … }],
      "available": boolean
    }
  },
  "options": {
    "preset": string or null,
    "statusMapping": map of string,
    "consentConfirmedElsewhere": boolean,
    "fixTypos": boolean
  },
  "detectedPreset": string or null,
  "statusValues": [{
    "value": string,
    "count": number,
    "suggested": string
  }],
  "createdAt": string,
  "completedAt": string or null,
  "processedRows": number
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Map columns and start the import (step 2)

POST /v1/contacts/imports/{id}/start

mapping maps each CSV column name to an attribute key or ignore; exactly one column must map to email. consentConfirmed must be true. Contacts already suppressed (bounced, complained, unsubscribed) are imported with that status and are never mailed.

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
mappingrequiredmap of stringCSV column name → attribute key (email, first_name, plan, …) or ignore.
listIdsarray of stringLists every imported contact is added to. Default [].
newListNamestringCreate a list with this name and add the imported contacts to it.
updateExistingbooleantrue: existing contacts are updated and added to the lists. false: rows for existing contacts are skipped entirely (not updated, not added to lists). Default true.
createMissingAttributesbooleanCreate contact attributes for mapped keys that do not exist yet. Default true.
consentConfirmedrequiredtrueYou confirm these people agreed to receive email from you.
presetstringSource preset id from GET /v1/contacts/import-presets (recorded with the import; mapping is still taken from mapping).
statusMappingmap of "subscribed" | "unsubscribed" | "bounced" | "complained" | "skip"With a column mapped to status: source value (case-insensitive) → contact status, or skip to leave those rows out. Values not listed use the preset mapping, then subscribed.
consentConfirmedElsewherebooleanRecord on each imported contact that consent was collected outside OneSend (stored as consent proof with method import).
fixTyposbooleanReplace addresses that have a likely domain typo (gmial.com → gmail.com) with the suggested address.

Responses

202 Success

{
  "id": string,
  "object": "import",
  "status": "uploaded" | "processing" | "completed" | "failed",
  "fileName": string,
  "totalRows": number,
  "columns": [{
    "name": string,
    "samples": [string],
    "suggested": string or null,
    "values": [{ … }]
  }],
  "mapping": map of string or null,
  "listIds": [string],
  "updateExisting": boolean,
  "result": {
    "created": number,
    "updated": number,
    "skipped": number,
    "invalid": number,
    "errors": [{
      "row": number,
      "message": string
    }],
    "statuses": map of number,
    "quality": {
      "checked": number,
      "typos": number,
      "typosFixed": number,
      "noMx": number,
      "disposable": number,
      "samples": [{ … }],
      "available": boolean
    }
  },
  "options": {
    "preset": string or null,
    "statusMapping": map of string,
    "consentConfirmedElsewhere": boolean,
    "fixTypos": boolean
  },
  "detectedPreset": string or null,
  "statusValues": [{
    "value": string,
    "count": number,
    "suggested": string
  }],
  "createdAt": string,
  "completedAt": string or null
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Download rows that were not imported (CSV)

GET /v1/contacts/imports/{id}/errors.csv

Authentication: Authorization: Bearer with an API key or a session token.

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success (text/csv)

Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)