Imports
CSV import: upload, map columns, start, then poll for the result.
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
{
"data": [{
"id": string,
"name": string,
"description": string,
"columns": [{ … }],
"statusColumn": [string],
"statusMapping": map of string
}]
}Errors: 400, 401, 403, 404, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Import history
GET /v1/contacts/imports
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
mappingrequired | map of string | CSV column name → attribute key (email, first_name, plan, …) or ignore. |
listIds | array of string | Lists every imported contact is added to. Default []. |
newListName | string | Create a list with this name and add the imported contacts to it. |
updateExisting | boolean | true: 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. |
createMissingAttributes | boolean | Create contact attributes for mapped keys that do not exist yet. Default true. |
consentConfirmedrequired | true | You confirm these people agreed to receive email from you. |
preset | string | Source preset id from GET /v1/contacts/import-presets (recorded with the import; mapping is still taken from mapping). |
statusMapping | map 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. |
consentConfirmedElsewhere | boolean | Record on each imported contact that consent was collected outside OneSend (stored as consent proof with method import). |
fixTypos | boolean | Replace addresses that have a likely domain typo (gmial.com → gmail.com) with the suggested address. |
Responses
{
"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
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 429, 500
400Invalid 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). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), 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 missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)