---
title: "Workspace API"
description: "Workspace in the OneSend API: 9 endpoints. Workspace name and settings, such as tracking defaults and the attribution window."
url: https://onesend.email/docs/api-reference/workspace/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Workspace

Workspace name and settings, such as tracking defaults and the attribution window.

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/).

## Workspace settings (tracking, sandbox, brand) and SMTP details

GET `/v1/workspace`

While Sandbox mode is on, `sandboxPending` counts the scheduled campaigns and automation runs in progress that will send for real once it is off.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "id": string,
  "name": string,
  "slug": string,
  "plan": string,
  "settings": object,
  "smtp": {
    "host": string,
    "port": number or null,
    "username": string
  },
  "inbound": {
    "smtpPort": number or null,
    "cloudflareIngestUrl": string
  },
  "sandboxPending": {
    "scheduledCampaigns": integer,
    "activeAutomationRuns": integer
  }
}
```

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

## Update workspace settings

PATCH `/v1/workspace`

Turning Sandbox mode off (`settings.sandbox: false`) needs a signed-in admin. The response that turns it off has `sandboxPending`: the scheduled campaigns and automation runs in progress, started while it was on, that now send for real.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` |  |
| `settings` | `object` |  |
| `settings.trackOpens` | `boolean` |  |
| `settings.trackClicks` | `boolean` |  |
| `settings.trackingDomain` | `string or null` |  |
| `settings.defaultPolicyId` | `string or null` | Routing policy for sends without `policy`. null or "" clears it. |
| `settings.sandbox` | `boolean` |  |
| `settings.campaignDailyCap` | `integer or null` | Most campaign emails per day for one campaign, on top of provider limits. null: only provider limits. 1 to 100000000. |
| `settings.timezone` | `string` |  |
| `settings.attributionWindowDays` | `integer` | 1 to 90. |
| `settings.companyAddress` | `string or null` |  |
| `settings.brand` | `object` |  |
| `settings.brand.logoUrl` | `string` |  |
| `settings.brand.primary` | `string` |  |
| `settings.brand.accent` | `string` |  |
| `settings.brand.font` | `string` |  |
| `settings.themes` | `array of object` | Saved designer themes. Sending the list replaces it. At most 50 items. |
| `settings.themes[].id`required | `string` |  |
| `settings.themes[].name`required | `string` |  |
| `settings.themes[].theme`required | `object` |  |

### Responses

`200` Success

```
{
  "id": string,
  "name": string,
  "slug": string,
  "plan": string,
  "settings": object,
  "smtp": {
    "host": string,
    "port": number or null,
    "username": string
  },
  "inbound": {
    "smtpPort": number or null,
    "cloudflareIngestUrl": string
  },
  "sandboxPending": {
    "scheduledCampaigns": integer,
    "activeAutomationRuns": integer
  }
}
```

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

## Delete the workspace

DELETE `/v1/workspace`

Owner only, in a dashboard session. Confirm with your password (and a two-factor code if it is on) and type the workspace name in `confirm`. Starts a 7-day grace period: the workspace becomes read-only, sending stops, and members are notified. The owner can cancel with POST /v1/workspace/deletion/cancel. After the grace period every row of the workspace is deleted permanently. People keep their accounts.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `password`required | `string` | Your current password |
| `code` | `string` | Two-factor code or recovery code, when two-factor authentication is on for your account |
| `confirm`required | `string` | The workspace name, typed exactly |

### Responses

`202` Success

```
{
  "status": "active" | "pending_deletion",
  "requestedAt": string or null,
  "purgeAt": string or null,
  "requestedBy": {
    "id": string,
    "email": 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`)

## Export all workspace data

POST `/v1/workspace/export`

Owners and admins (or an admin-scoped live API key). Builds a ZIP in the background: one JSON file per table, CSV files for contacts, messages and events, and a README. Secrets are never included (provider credentials, API key hashes, webhook signing secrets, app password hashes). When it is ready, the person who asked gets an email with a signed download link; the file is kept for 7 days. Only one export runs at a time: while one is running, this returns it.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`202` Success

```
{
  "id": string,
  "object": "workspace_export",
  "status": "queued" | "running" | "ready" | "failed" | "expired",
  "size": number or null,
  "tables": number,
  "rows": number,
  "error": string or null,
  "createdAt": string,
  "completedAt": string or null,
  "expiresAt": string or null,
  "downloadUrl": 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`)

## List data exports

GET `/v1/workspace/exports`

Owners and admins. Newest first, the last 20.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "object": "workspace_export",
    "status": "queued" | "running" | "ready" | "failed" | "expired",
    "size": number or null,
    "tables": number,
    "rows": number,
    "error": string or null,
    "createdAt": string,
    "completedAt": string or null,
    "expiresAt": string or null,
    "downloadUrl": 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`)

## Get a data export

GET `/v1/workspace/exports/{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": "workspace_export",
  "status": "queued" | "running" | "ready" | "failed" | "expired",
  "size": number or null,
  "tables": number,
  "rows": number,
  "error": string or null,
  "createdAt": string,
  "completedAt": string or null,
  "expiresAt": string or null,
  "downloadUrl": 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`)

## Download a data export

GET `/v1/workspace/exports/{id}/download`

With the signed `token` from the email (or from `downloadUrl`), or with an owner or admin session of the workspace. Answers 410 `export_expired` after the file was removed.

**Authentication:** None.

### Parameters

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

### Responses

`200` Success (application/zip)

**Errors: 400, 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`.
- `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`)

## Workspace deletion status

GET `/v1/workspace/deletion`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "status": "active" | "pending_deletion",
  "requestedAt": string or null,
  "purgeAt": string or null,
  "requestedBy": {
    "id": string,
    "email": 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`)

## Cancel the workspace deletion

POST `/v1/workspace/deletion/cancel`

Owner only, before the grace period ends. Sending resumes and members are notified.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "status": "active" | "pending_deletion",
  "requestedAt": string or null,
  "purgeAt": string or null,
  "requestedBy": {
    "id": string,
    "email": 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`)
