--- title: "Workspaces" 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/workspaces" area: "API" category: "Reference" --- # Workspaces Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations The workspaces the person behind the key or the app can open: the ones they own and the ones they joined, and which one the app opens for them. These calls act on a person, never on a workspace: an API key acts for the workspace owner, and an app for the person who connected it. Reading needs `account:read` and every change needs `account:write`. The key or the app itself still acts for exactly one workspace in every other call. ### `GET /workspaces` List your workspaces Every workspace the person can open, the ones they own first, as the workspace switcher of the app lists them. `activeWorkspaceId` is the one the app opens for them, `primaryWorkspaceId` the first one they made, which cannot be deleted, and `personalWorkspaceId` their personal space, which holds their free address and is not listed. Requires the `account:read` scope. - Scopes: `account:read`. **Returns** - `200` `WorkspaceList`: The workspaces. **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 [`workspaces.list()`](https://openemail.uk/docs/sdk/reference/workspaces#list); CLI [`openemail workspaces list`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-list); MCP [`listAccountWorkspaces`](https://openemail.uk/docs/mcp/tools/account#listAccountWorkspaces). ### `POST /workspaces` Create a workspace Makes a new workspace owned by the person, on the Free plan, and makes it the one the app opens for them, as creating one in the app does. An account can own one Free workspace, so while it owns one the call is a 403 `workspace_allowance_reached` that names it: upgrade that workspace first. Sending the same name twice within ten seconds returns the workspace the first call made. Requires the `account:write` scope. - Scopes: `account:write`. **Request body** - `name` (`string`, required, 1 to 64 characters): Up to 64 characters. Leading and trailing spaces are trimmed. **Returns** - `201` `CreatedWorkspace`: The new workspace. **Errors** - `403`: `workspace_allowance_reached`: the account already owns a workspace on the Free plan. Upgrade it before creating another. `insufficient_scope` when the key or the app lacks `account:write`. - 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 [`workspaces.create()`](https://openemail.uk/docs/sdk/reference/workspaces#create); CLI [`openemail workspaces create`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-create); MCP [`createWorkspace`](https://openemail.uk/docs/mcp/tools/account#createWorkspace). ### `GET /workspaces/active` Read the workspace the app opens The workspace the app opens for the person when they sign in, or the one it falls back to when they never chose one. It is not the workspace the key or the app acts on, which never changes. Requires the `account:read` scope. - Scopes: `account:read`. **Returns** - `200` `ActiveWorkspace`: The workspace the app opens. **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 [`workspaces.getActive()`](https://openemail.uk/docs/sdk/reference/workspaces#getActive); CLI [`openemail workspaces get-active`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-get-active); MCP [`listAccountWorkspaces`](https://openemail.uk/docs/mcp/tools/account#listAccountWorkspaces). ### `PUT /workspaces/active` Choose the workspace the app opens Switches the workspace the app opens for the person, as the workspace switcher does, to any workspace they can open. A workspace they cannot open is a 404. It changes nothing for the key or the app making the call. Requires the `account:write` scope. - Scopes: `account:write`. **Request body** - `workspaceId` (`string`, required, 1 to 128 characters) **Returns** - `200` `ActiveWorkspace`: The workspace the app opens now. **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 [`workspaces.setActive()`](https://openemail.uk/docs/sdk/reference/workspaces#setActive); CLI [`openemail workspaces set-active`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-set-active); MCP [`switchAppWorkspace`](https://openemail.uk/docs/mcp/tools/account#switchAppWorkspace). ### `DELETE /workspaces/{id}` Delete the workspace Deletes the workspace the key or the app belongs to, with its domains, addresses, mail and members, and cancels its plan. It is for good. `confirm` has to be the name of the workspace, as the app asks the person to type it. Only the owner may do it: a member's access token is refused with 403 `owner_only`, and a key or an app limited to particular addresses or domains with 422 `capability_unsupported`. The first workspace an account made cannot be deleted (409 `first_workspace`), and neither can one with a domain being moved in or out (409 `domain_moving`). The key that deleted its own workspace stops working with it. Requires the `account:write` scope. - Scopes: `account:write`. - Asks an OAuth access token for a verification code. **Path parameters** - `id` (`string`, required): The id of the workspace the key or the app belongs to. Any other id is a 404. **Query parameters** - `confirm` (`string`, required, up to 256 characters): The name of the workspace, as `GET /workspaces` lists it. Letter case and the spaces around it do not matter. **Returns** - `200` `DeletedWorkspace`: Deleted. **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`: `first_workspace`: the first workspace an account made cannot be deleted. `domain_moving`: a domain is being moved into or out of it, so try again when the move has finished. - `502`: `plan_not_cancelled`: the plan on the workspace could not be cancelled, so the workspace was kept. Try again in a moment. - 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 [`workspaces.delete()`](https://openemail.uk/docs/sdk/reference/workspaces#delete); CLI [`openemail workspaces delete`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-delete); MCP [`deleteWorkspace`](https://openemail.uk/docs/mcp/tools/account#deleteWorkspace). ### Objects #### `ActiveWorkspace` `object` - `object` (`string`, required, one of `"workspace"`) - `id` (`string`, required) - `name` (`string`, required, nullable) - `slug` (`string`, required, nullable) - `email` (`string`, required, nullable) - `kind` (`string`, required, one of `"business"`, `"personal"`): `personal` for the personal space, `business` for every other workspace. - `isOwner` (`boolean`, required) - `createdAt` (`string`, required, format `date-time`) #### `CreatedWorkspace` `object` - `object` (`string`, required, one of `"workspace"`) - `id` (`string`, required) - `name` (`string`, required) - `slug` (`string`, required) - `active` (`boolean`, required, one of `true`): The app opens the new workspace for the person from now on. #### `DeletedWorkspace` `object` - `object` (`string`, required, one of `"workspace"`) - `id` (`string`, required) - `deleted` (`boolean`, required, one of `true`) - `activeWorkspaceId` (`string`, required, nullable): The first workspace of the account, which the app opens when the deleted one was open. #### `Workspace` `object` - `object` (`string`, required, one of `"workspace"`) - `id` (`string`, required) - `name` (`string`, required): The name the app shows for it. - `slug` (`string`, required, nullable) - `email` (`string`, required, nullable): The address the workspace was made for, or null while it has none. - `isOwner` (`boolean`, required): Whether the person owns it rather than joined it. - `ownerId` (`string`, required): The account id of its owner. - `plan` (`string`, required, one of `"free"`, `"starter"`, `"business"`, `"enterprise"`) - `markUrl` (`string`, nullable): Its square logo, when it has one. - `wordmarkUrl` (`string`, nullable): Its wide logo, when it has one. - `createdAt` (`string`, required, format `date-time`) #### `WorkspaceList` `object` - `object` (`string`, required, one of `"list"`) - `data` (`Workspace[]`, required) - `activeWorkspaceId` (`string`, required, nullable): The workspace the app opens for the person. - `primaryWorkspaceId` (`string`, required, nullable): The first workspace they made, which cannot be deleted. - `personalWorkspaceId` (`string`, required, nullable): Their personal space, which is not in `data`.