--- title: "Imports" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://openemail.uk/docs/api/reference/imports" area: "API" category: "Reference" --- # Imports Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations Two ways to bring an existing setup across. A mailbox import reads an export file: Google Takeout archives, .mbox, .eml, .zip and .tgz. Create the import, upload each file in parts, then start it. Imported mail is quiet, so no rules, forwards, notifications, summaries or webhooks run for it. A provider import reads a Resend account with a full-access key: suppressions, segments as audiences, subscribed contacts, templates, and webhooks created switched off, plus a checklist of the domains and API keys to recreate by hand. Inspect it first to see what would come across. The key is held encrypted only while the import runs and is erased when it ends, and running it twice duplicates nothing. ### `GET /imports` List mailbox imports Every import in the workspace, newest first, one page at a time, each with its status, byte progress and running counts. Nothing is dropped from the history, so following `nextCursor` reaches the first import. A key limited to particular addresses sees only imports into those addresses. Requires the `threads:read` scope. - Scopes: `threads:read`. **Query parameters** - `addressId` (`string`): Only imports into this address. - `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100. - `cursor` (`string`): An import id. Keyset, not offset: pass the previous page's `nextCursor`. One that names nothing in this list is a 400 `invalid_cursor`. **Returns** - `200`: A page of imports, newest first, with `hasMore` and `nextCursor`. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.list()`](https://openemail.uk/docs/sdk/reference/imports#list), [`imports.listAll()`](https://openemail.uk/docs/sdk/reference/imports#listAll), [`imports.iterate()`](https://openemail.uk/docs/sdk/reference/imports#iterate); CLI [`openemail imports list`](https://openemail.uk/docs/cli/reference/imports#imports-list); MCP [`listImports`](https://openemail.uk/docs/mcp/tools/imports#listImports). ### `POST /imports` Start a mailbox import Creates an import into one address and returns it with `status: uploading`. Upload each file in parts of `chunkBytes` with the chunk operation, then call start. The import reads Google Takeout archives, .mbox, .eml, .zip and .tgz files. Imported mail is quiet: no rules, forwards, notifications, summaries or webhooks run for it. Requires the `threads:write` scope. - Scopes: `threads:write`. **Request body** - `addressId` (`string`, required): The address the mail belongs to. - `files` (`object[]`, required, 1 to 50 items): Each file as `{ name, bytes }`, 1 to 50 of them, each at most 100 GB. - `name` (`string`, required, up to 255 characters) - `bytes` (`integer`, required, at least 1, at most 107374182400) - `options` (`object`): `keepInbox`, `includeSpam` and `includeTrash`, as for `create`. - `keepInbox` (`boolean`): Default true. Mail that was in the old inbox lands in Inbox with its unread state; false files everything under Archive. - `includeSpam` (`boolean`): Default false. - `includeTrash` (`boolean`): Default false. **Returns** - `201`: The import, waiting for its files. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.create()`](https://openemail.uk/docs/sdk/reference/imports#create), [`imports.importFiles()`](https://openemail.uk/docs/sdk/reference/imports#importFiles); CLI [`openemail imports create`](https://openemail.uk/docs/cli/reference/imports#imports-create), [`openemail imports import-files`](https://openemail.uk/docs/cli/reference/imports#imports-import-files). ### `GET /imports/{id}` Get a mailbox import Status, byte progress and counts. Poll it while the import runs. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): Import id, `imp_` followed by 24 hex characters. **Returns** - `200`: The import. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.get()`](https://openemail.uk/docs/sdk/reference/imports#get); CLI [`openemail imports get`](https://openemail.uk/docs/cli/reference/imports#imports-get); MCP [`getImport`](https://openemail.uk/docs/mcp/tools/imports#getImport). ### `GET /imports/{id}/upload` Which parts have arrived For each file, the indexes of the parts already stored, so an interrupted upload sends only what is missing. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): Import id, `imp_` followed by 24 hex characters. **Returns** - `200`: Received parts per file. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.uploadState()`](https://openemail.uk/docs/sdk/reference/imports#uploadState); CLI [`openemail imports upload-state`](https://openemail.uk/docs/cli/reference/imports#imports-upload-state). ### `DELETE /imports/{id}/upload` Delete the uploaded files Removes the uploaded archive. Mail already imported stays in the mailbox. Refused with 409 while the import is queued or running. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): Import id, `imp_` followed by 24 hex characters. **Returns** - `200`: The import, with `uploadDeleted: true`. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.deleteUpload()`](https://openemail.uk/docs/sdk/reference/imports#deleteUpload); CLI [`openemail imports delete-upload`](https://openemail.uk/docs/cli/reference/imports#imports-delete-upload). ### `PUT /imports/{id}/files/{file}/chunks/{chunk}` Upload one part of a file Stores bytes `chunk * chunkBytes` up to the next part of file `file`. Every part is exactly `chunkBytes` long except the last. Sending a part again replaces it, so a failed part can simply be retried. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): Import id, `imp_` followed by 24 hex characters. - `file` (`integer`, required, at least 0): The file index, in the order given to `create`. - `chunk` (`integer`, required, at least 0): The part index, from 0. **Request body** Content type: `application/octet-stream`. `binary` **Returns** - `200`: The part was stored. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.uploadChunk()`](https://openemail.uk/docs/sdk/reference/imports#uploadChunk); CLI [`openemail imports upload-chunk`](https://openemail.uk/docs/cli/reference/imports#imports-upload-chunk). ### `POST /imports/{id}/start` Start reading the uploaded files Checks that every part of every file has arrived and queues the import. 412 `missing_chunks` names the files still incomplete. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): Import id, `imp_` followed by 24 hex characters. **Returns** - `200`: The import, queued. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.start()`](https://openemail.uk/docs/sdk/reference/imports#start); CLI [`openemail imports start`](https://openemail.uk/docs/cli/reference/imports#imports-start). ### `POST /imports/{id}/cancel` Cancel a mailbox import Stops the import at its next checkpoint. Mail already imported stays. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): Import id, `imp_` followed by 24 hex characters. **Returns** - `200`: The import, cancelled. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.cancel()`](https://openemail.uk/docs/sdk/reference/imports#cancel); CLI [`openemail imports cancel`](https://openemail.uk/docs/cli/reference/imports#imports-cancel); MCP [`cancelImport`](https://openemail.uk/docs/mcp/tools/imports#cancelImport). ### `GET /imports/{id}/failures` What an import could not bring across Each message or archive entry that did not come across, with the reason. Page with `after`, the `nextCursor` of the previous page. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): Import id, `imp_` followed by 24 hex characters. **Query parameters** - `after` (`integer`): The `nextCursor` of the previous page. - `limit` (`integer`, at least 1, at most 100): At most 100, the default. **Returns** - `200`: Failures. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`imports.listFailures()`](https://openemail.uk/docs/sdk/reference/imports#listFailures); CLI [`openemail imports list-failures`](https://openemail.uk/docs/cli/reference/imports#imports-list-failures); MCP [`listImportFailures`](https://openemail.uk/docs/mcp/tools/imports#listImportFailures). ### `POST /provider-imports/inspect` Look inside a Resend account before importing Reads the first page of each resource with a full-access Resend key and returns what an import would bring. Nothing is stored and the key is not kept. A sending-only key is 400 `restricted_key`. Requires the `settings:write` scope. - Scopes: `settings:write`. **Request body** - `apiKey` (`string`, required, 8 to 200 characters) **Returns** - `200`: Counts per resource. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`providerImports.inspect()`](https://openemail.uk/docs/sdk/reference/provider-imports#inspect); CLI [`openemail provider-imports inspect`](https://openemail.uk/docs/cli/reference/provider-imports#provider-imports-inspect). ### `GET /provider-imports` List imports from sending providers Every provider import in the workspace, newest first, one page at a time, each with its report. Follow `nextCursor` to reach the first one. Requires the `settings:read` scope. - Scopes: `settings:read`. **Query parameters** - `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100. - `cursor` (`string`): A provider import id. Keyset, not offset: pass the previous page's `nextCursor`. One that names nothing in this list is a 400 `invalid_cursor`. **Returns** - `200`: A page of provider imports, newest first, with `hasMore` and `nextCursor`. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`providerImports.list()`](https://openemail.uk/docs/sdk/reference/provider-imports#list), [`providerImports.listAll()`](https://openemail.uk/docs/sdk/reference/provider-imports#listAll), [`providerImports.iterate()`](https://openemail.uk/docs/sdk/reference/provider-imports#iterate); CLI [`openemail provider-imports list`](https://openemail.uk/docs/cli/reference/provider-imports#provider-imports-list); MCP [`getProviderImport`](https://openemail.uk/docs/mcp/tools/imports#getProviderImport), [`listProviderImports`](https://openemail.uk/docs/mcp/tools/imports#listProviderImports). ### `POST /provider-imports` Import from Resend Starts an import from a Resend account: suppressions, segments as audiences, subscribed contacts, templates, and webhooks created switched off, plus a checklist of domains and API keys. The key is held encrypted only while the import runs and is erased when it ends. Running it twice duplicates nothing. Requires the `settings:write` scope. - Scopes: `settings:write`. **Request body** - `apiKey` (`string`, required, 8 to 200 characters): A full-access Resend API key. - `resources` (`string[]`, required, at least one item, one of `"suppressions"`, `"audiences"`, `"contacts"`, `"templates"`, `"webhooks"`, `"domains"`, `"api-keys"`): Any of `suppressions`, `audiences`, `contacts`, `templates`, `webhooks`, `domains` and `api-keys`. **Returns** - `201`: The import, queued. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`providerImports.create()`](https://openemail.uk/docs/sdk/reference/provider-imports#create); CLI [`openemail provider-imports create`](https://openemail.uk/docs/cli/reference/provider-imports#provider-imports-create). ### `GET /provider-imports/{id}` Get an import from a sending provider Status, current step and the report so far. Requires the `settings:read` scope. - Scopes: `settings:read`. **Path parameters** - `id` (`string`, required): Provider import id, `pimp_` followed by 24 hex characters. **Returns** - `200`: The provider import. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`providerImports.get()`](https://openemail.uk/docs/sdk/reference/provider-imports#get); CLI [`openemail provider-imports get`](https://openemail.uk/docs/cli/reference/provider-imports#provider-imports-get); MCP [`getProviderImport`](https://openemail.uk/docs/mcp/tools/imports#getProviderImport), [`listProviderImports`](https://openemail.uk/docs/mcp/tools/imports#listProviderImports). ### `POST /provider-imports/{id}/cancel` Cancel an import from a sending provider Stops it and erases the key. What already came across stays. Requires the `settings:write` scope. - Scopes: `settings:write`. **Path parameters** - `id` (`string`, required): Provider import id, `pimp_` followed by 24 hex characters. **Returns** - `200`: The provider import, cancelled. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`providerImports.cancel()`](https://openemail.uk/docs/sdk/reference/provider-imports#cancel); CLI [`openemail provider-imports cancel`](https://openemail.uk/docs/cli/reference/provider-imports#provider-imports-cancel); MCP [`cancelProviderImport`](https://openemail.uk/docs/mcp/tools/imports#cancelProviderImport).