--- title: "Exports" 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/exports" area: "API" category: "Reference" --- # Exports Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations A zip of the whole workspace, as the Export page of the app makes it: every conversation as mbox files with its attachments, contacts as vCard, audiences, calendar events as .ics, templates with every version, rules, labels, notes and addresses. An export is made in the background, can be started once a day and is kept for 365 days. Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an app connected with every address. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`, and an account the workspace cannot export for is a 403 `export_not_permitted`. ### `GET /exports/preview` See what an export would hold Whether this workspace can be exported by the caller now, when the next export can start, the export still being made, if there is one, and how much an export would hold. When `allowed` is false, `reason` says why and `counts` is null. Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an app connected with every address. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`, and an account the workspace cannot export for is a 403 `export_not_permitted`. Requires the `threads:read` scope. - Scopes: `threads:read`. **Returns** - `200` `ExportPreview`: What an export would hold, and whether one can start. **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 [`exports.preview()`](https://openemail.uk/docs/sdk/reference/exports#preview); CLI [`openemail exports preview`](https://openemail.uk/docs/cli/reference/exports#exports-preview); MCP [`getExportPreview`](https://openemail.uk/docs/mcp/tools/exports#getExportPreview). ### `GET /exports` List the exports Every export of the workspace, newest first, with its status and progress. `limit` and `offset` page through them, and `total` counts them all. Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an app connected with every address. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`, and an account the workspace cannot export for is a 403 `export_not_permitted`. Requires the `threads:read` scope. - Scopes: `threads:read`. **Query parameters** - `limit` (`integer`, at least 1, at most 100, default `25`): Exports per page, 1 to 100. - `offset` (`integer`, at least 0, default `0`): How many exports to skip. **Returns** - `200` `ExportList`: A page of exports, newest first. **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 [`exports.list()`](https://openemail.uk/docs/sdk/reference/exports#list); CLI [`openemail exports list`](https://openemail.uk/docs/cli/reference/exports#exports-list); MCP [`getExport`](https://openemail.uk/docs/mcp/tools/exports#getExport), [`listExports`](https://openemail.uk/docs/mcp/tools/exports#listExports). ### `POST /exports` Start an export Starts making a zip of the whole workspace, as Export now on the Export page does. It is made in the background: read it with `GET /exports/{id}` until `status` is `ready`, then download it. One export can run at a time, and a workspace can be exported once a day. Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an app connected with every address. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`, and an account the workspace cannot export for is a 403 `export_not_permitted`. Requires the `threads:read` scope. - Scopes: `threads:read`. - Asks an OAuth access token for a verification code. **Returns** - `201` `Export`: The export, queued. **Errors** - `403`: The key lacks the scope, or may not send as that address. `step_up_required`: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code with `POST /security/step-up`, send it to `POST /security/step-up/verify`, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code. - `409`: `already_running`: an export of this workspace is already being made. - `429`: `export_limit_reached`: the workspace was exported in the last day. - The errors every operation can return: `400`, `401`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`exports.start()`](https://openemail.uk/docs/sdk/reference/exports#start); CLI [`openemail exports start`](https://openemail.uk/docs/cli/reference/exports#exports-start); MCP [`startExport`](https://openemail.uk/docs/mcp/tools/exports#startExport). ### `GET /exports/{id}` Retrieve an export One export, with its status, its progress through the conversations and, once it is `ready`, its size, file name and when it is deleted. Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an app connected with every address. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`, and an account the workspace cannot export for is a 403 `export_not_permitted`. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): The export id from `GET /exports` or `POST /exports`. **Returns** - `200` `Export`: The export. **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 [`exports.get()`](https://openemail.uk/docs/sdk/reference/exports#get); CLI [`openemail exports get`](https://openemail.uk/docs/cli/reference/exports#exports-get); MCP [`getExport`](https://openemail.uk/docs/mcp/tools/exports#getExport), [`listExports`](https://openemail.uk/docs/mcp/tools/exports#listExports). ### `GET /exports/{id}/content` Download an export The zip itself, as `application/zip` with its file name in `Content-Disposition`. It is only there once the export is `ready`: before that the call is a 409 `export_not_ready`, and an export older than 365 days is a 409 `expired`. Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an app connected with every address. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`, and an account the workspace cannot export for is a 403 `export_not_permitted`. Requires the `threads:read` scope. - Scopes: `threads:read`. - Asks an OAuth access token for a verification code. **Path parameters** - `id` (`string`, required): The export id from `GET /exports` or `POST /exports`. **Returns** - `200` `binary` (`application/zip`): The zip. **Errors** - `403`: The key lacks the scope, or may not send as that address. `step_up_required`: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code with `POST /security/step-up`, send it to `POST /security/step-up/verify`, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the OpenEmail website. An API key is never asked for a code. - `409`: `export_not_ready`: the export is still being made or failed. `expired`: it was deleted a year after it was made. - The errors every operation can return: `400`, `401`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`exports.download()`](https://openemail.uk/docs/sdk/reference/exports#download); CLI [`openemail exports download`](https://openemail.uk/docs/cli/reference/exports#exports-download). ### Objects #### `Export` `object` - `object` (`string`, required, one of `"export"`) - `id` (`string`, required) - `status` (`string`, required, one of `"queued"`, `"running"`, `"ready"`, `"failed"`, `"expired"`) - `phase` (`string`, nullable, one of `"planning"`, `"mail"`, `"records"`, `"finishing"`): What it is doing while `status` is `running`. - `createdAt` (`string`, required, format `date-time`) - `createdBy` (`object`, nullable): Who started it, or null when that account is gone. - `name` (`string`, nullable) - `email` (`string`) - `startedAt` (`string`, nullable, format `date-time`) - `finishedAt` (`string`, nullable, format `date-time`) - `expiresAt` (`string`, nullable, format `date-time`): When the zip is deleted, a year after it was made. - `sizeBytes` (`integer`, nullable) - `fileName` (`string`, nullable) - `threadsDone` (`integer`, at least 0) - `threadsTotal` (`integer`, nullable) - `error` (`string`, nullable): Why it failed, when `status` is `failed`. #### `ExportList` `object` - `object` (`string`, one of `"list"`) - `data` (`Export[]`) - `total` (`integer`, at least 0): How many exports there are in all. - `hasMore` (`boolean`): Whether more exports follow this page. #### `ExportPreview` `object` - `object` (`string`, required, one of `"export_preview"`) - `allowed` (`boolean`, required): Whether the caller may export this workspace. - `reason` (`string`, required, nullable, one of `"not-permitted"`, `"mailbox-login"`, `"two-factor-required"`): Why not, when `allowed` is false: `not-permitted` for an account that is neither the owner nor holds every permission, `mailbox-login` for a sign-in for one address, and `two-factor-required` when the workspace requires two-factor sign-in and the account has none. - `nextAvailableAt` (`string`, required, nullable, format `date-time`): When the next export can start, or null when one can start now. - `activeExportId` (`string`, required, nullable): The export still being made, if there is one. - `counts` (`object`, required, nullable): How much an export would hold now. Null when `allowed` is false. - `threads` (`integer`, at least 0): Conversations. - `attachments` (`integer`, at least 0): Attachments inside them. - `attachmentBytes` (`integer`, at least 0): The size of those attachments, in bytes. - `deletedFiles` (`integer`, at least 0): Deleted files, listed by name and date but not included. - `contacts` (`integer`, at least 0): Contacts. - `audiences` (`integer`, at least 0): Audiences. - `calendarEvents` (`integer`, at least 0): Calendar events. - `templates` (`integer`, at least 0): Templates. - `rules` (`integer`, at least 0): Rules. - `labels` (`integer`, at least 0): Labels. - `notes` (`integer`, at least 0): Notes of the caller. - `addresses` (`integer`, at least 0): Addresses.