---
title: "nextmail.exports"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/sdk/reference/exports"
area: "TypeScript"
category: "Reference"
---

# nextmail.exports

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

A zip of the whole workspace, as the Export page makes it: see what it would hold, start one, follow it while it is made and download it once it is ready.

### `nextmail.exports.preview()`

See what an export would hold

```ts
preview(options?: RequestScope): Promise<ExportPreviewResource>
```

Resolves whether the 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: conversations, attachments and their size, contacts, audiences, calendar events, templates, rules, labels, notes and addresses. 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 access token connected with every address. An export holds all of it, so the key or the token needs the read scope of everything inside: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read` and `rules:read`. A key or token limited to particular addresses or domains is 422 `capability_unsupported`, and an account the workspace cannot export for is 403 `export_not_permitted`.

Scopes: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read`, `rules:read`.

**Parameters**

- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`ExportPreviewResource` with `allowed`, `reason`, `nextAvailableAt`, `activeExportId` and `counts`.

**Example**

```ts
const preview = await nextmail.exports.preview()

if (preview.allowed && !preview.nextAvailableAt) console.log('an export can start now', preview.counts)
```

**Notes**

- `reason` is `not-permitted`, `mailbox-login` or `two-factor-required`.

Also available in: API [`GET /exports/preview`](https://nextmail.sh/docs/api/reference/exports#get-exports-preview); Python [`exports.preview()`](https://nextmail.sh/docs/python/reference/exports#preview); Ruby [`exports.preview`](https://nextmail.sh/docs/ruby/reference/exports#preview); PHP [`exports->preview`](https://nextmail.sh/docs/php/reference/exports#preview); Go [`Exports.Preview`](https://nextmail.sh/docs/go/reference/exports#preview); Java [`exports().preview`](https://nextmail.sh/docs/java/reference/exports#preview); C# [`Exports.PreviewAsync`](https://nextmail.sh/docs/csharp/reference/exports#preview); CLI [`nextmail exports preview`](https://nextmail.sh/docs/cli/reference/exports#exports-preview).

### `nextmail.exports.list()`

List the exports

```ts
list(options?: ExportListOptions): Promise<ExportListResource>
```

Resolves every export of the workspace, newest first, a page at a time, 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 access token connected with every address. An export holds all of it, so the key or the token needs the read scope of everything inside: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read` and `rules:read`. A key or token limited to particular addresses or domains is 422 `capability_unsupported`, and an account the workspace cannot export for is 403 `export_not_permitted`.

Scopes: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read`, `rules:read`.

**Parameters**

- `options.limit` (`number`): Exports per page, from 1 to 100. The server defaults to 25.
- `options.offset` (`number`): How many exports to skip.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`ExportListResource` with `data`, `total` and `hasMore`.

**Example**

```ts
const { data } = await nextmail.exports.list()

const ready = data.find((item) => item.status === 'ready')
```

**Notes**

- A workspace can be exported once a day, and each export is kept for a year, so the list stays short.

Also available in: API [`GET /exports`](https://nextmail.sh/docs/api/reference/exports#get-exports); Python [`exports.list()`](https://nextmail.sh/docs/python/reference/exports#list); Ruby [`exports.list`](https://nextmail.sh/docs/ruby/reference/exports#list); PHP [`exports->list`](https://nextmail.sh/docs/php/reference/exports#list); Go [`Exports.List`](https://nextmail.sh/docs/go/reference/exports#list); Java [`exports().list`](https://nextmail.sh/docs/java/reference/exports#list); C# [`Exports.ListAsync`](https://nextmail.sh/docs/csharp/reference/exports#list); CLI [`nextmail exports list`](https://nextmail.sh/docs/cli/reference/exports#exports-list).

### `nextmail.exports.get()`

Retrieve an export

```ts
get(id: string, options?: RequestScope): Promise<ExportResource>
```

Resolves one export: its `status`, `phase` and progress while it is made, 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 access token connected with every address. An export holds all of it, so the key or the token needs the read scope of everything inside: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read` and `rules:read`. A key or token limited to particular addresses or domains is 422 `capability_unsupported`, and an account the workspace cannot export for is 403 `export_not_permitted`.

Scopes: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read`, `rules:read`.

**Parameters**

- `id` (`string`, required): The export id from `start` or `list`.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`ExportResource`.

**Example**

```ts
const item = await nextmail.exports.get('exp_8c1e4a7f2b9d3e6a0c5f1b28')

console.log(item.status, item.threadsDone, item.threadsTotal)
```

**Notes**

- An unknown id is a 404.

Also available in: API [`GET /exports/{id}`](https://nextmail.sh/docs/api/reference/exports#get-exports-id); Python [`exports.get()`](https://nextmail.sh/docs/python/reference/exports#get); Ruby [`exports.get`](https://nextmail.sh/docs/ruby/reference/exports#get); PHP [`exports->get`](https://nextmail.sh/docs/php/reference/exports#get); Go [`Exports.Get`](https://nextmail.sh/docs/go/reference/exports#get); Java [`exports().get`](https://nextmail.sh/docs/java/reference/exports#get); C# [`Exports.GetAsync`](https://nextmail.sh/docs/csharp/reference/exports#get); CLI [`nextmail exports get`](https://nextmail.sh/docs/cli/reference/exports#exports-get).

### `nextmail.exports.start()`

Start an export

```ts
start(options?: RequestScope): Promise<ExportResource>
```

Starts making a zip of the whole workspace, as Export now on the Export page does, and resolves with the export, `queued`. It is made in the background: poll `get` until `status` is `ready`, then `download` it. One export runs 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 access token connected with every address. An export holds all of it, so the key or the token needs the read scope of everything inside: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read` and `rules:read`. A key or token limited to particular addresses or domains is 422 `capability_unsupported`, and an account the workspace cannot export for is 403 `export_not_permitted`.

Scopes: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read`, `rules:read`.

**Parameters**

- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`ExportResource` for the new export.

**Example**

```ts
const started = await nextmail.exports.start()

console.log(started.id, started.status)
```

**Notes**

- With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 `step_up_required`. An API key is never asked.
- An export already being made is 409 `already_running`, and a workspace exported in the last day is 429 `export_limit_reached`.
- The SDK does not retry it.

Also available in: API [`POST /exports`](https://nextmail.sh/docs/api/reference/exports#post-exports); Python [`exports.start()`](https://nextmail.sh/docs/python/reference/exports#start); Ruby [`exports.start`](https://nextmail.sh/docs/ruby/reference/exports#start); PHP [`exports->start`](https://nextmail.sh/docs/php/reference/exports#start); Go [`Exports.Start`](https://nextmail.sh/docs/go/reference/exports#start); Java [`exports().start`](https://nextmail.sh/docs/java/reference/exports#start); C# [`Exports.StartAsync`](https://nextmail.sh/docs/csharp/reference/exports#start); CLI [`nextmail exports start`](https://nextmail.sh/docs/cli/reference/exports#exports-start).

### `nextmail.exports.download()`

Download an export

```ts
download(id: string, options?: RequestScope): Promise<Uint8Array>
```

Resolves with the zip of a `ready` export, the same file the Download action on the Export page saves.

Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an access token connected with every address. An export holds all of it, so the key or the token needs the read scope of everything inside: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read` and `rules:read`. A key or token limited to particular addresses or domains is 422 `capability_unsupported`, and an account the workspace cannot export for is 403 `export_not_permitted`.

Scopes: `threads:read`, `emails:read`, `drafts:read`, `files:read`, `labels:read`, `contacts:read`, `audiences:read`, `calendar:read`, `templates:read`, `rules:read`.

**Parameters**

- `id` (`string`, required): The export id from `start` or `list`.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`Uint8Array` holding the zip.

**Example**

```ts
import { writeFile } from 'node:fs/promises'

const item = await nextmail.exports.get('exp_8c1e4a7f2b9d3e6a0c5f1b28')
const zip = await nextmail.exports.download(item.id)

await writeFile(item.fileName ?? 'export.zip', zip)
```

**Notes**

- With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 `step_up_required`. An API key is never asked.
- Before the export is `ready` the call is 409 `export_not_ready`, and an export older than a year is 409 `expired`.
- The whole zip is held in memory, and a large workspace makes a large zip.

Also available in: API [`GET /exports/{id}/content`](https://nextmail.sh/docs/api/reference/exports#get-exports-id-content); Python [`exports.download()`](https://nextmail.sh/docs/python/reference/exports#download); Ruby [`exports.download`](https://nextmail.sh/docs/ruby/reference/exports#download); PHP [`exports->download`](https://nextmail.sh/docs/php/reference/exports#download); Go [`Exports.Download`](https://nextmail.sh/docs/go/reference/exports#download); Java [`exports().download`](https://nextmail.sh/docs/java/reference/exports#download); C# [`Exports.DownloadAsync`](https://nextmail.sh/docs/csharp/reference/exports#download); CLI [`nextmail exports download`](https://nextmail.sh/docs/cli/reference/exports#exports-download).