---
title: "Imports API"
description: "Imports in the OneSend API: 6 endpoints. CSV import: upload, map columns, start, then poll for the result."
url: https://onesend.email/docs/api-reference/imports/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/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](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## 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

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### 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

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `mapping`required | `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. |
| `consentConfirmed`required | `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

`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

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### 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`)
