---
title: "openemail.workspaces"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://openemail.uk/docs/python/reference/workspaces"
area: "Python"
category: "Reference"
---

# openemail.workspaces

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

## Methods

The workspaces the person behind the key or the app can open: list them, create one, choose the one the app opens, and delete the workspace the key or the app belongs to. An API key acts for the workspace owner, and an app for the person who connected it.

### `workspaces.list()`

List your workspaces

```python
def list(
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> WorkspaceListResource
```

Returns every workspace the person behind the client can open, the ones they own first, as the workspace switcher of the app lists them. It is about the person, not the workspace the key belongs to. An API key answers for the workspace owner, and an app for the person who connected it.

`activeWorkspaceId` is the workspace the app opens for them, `primaryWorkspaceId` the first one they made, which can never be deleted, and `personalWorkspaceId` their personal space, which holds their free address and is not in `data`. It is one response rather than a page, so there is no cursor to follow.

Scopes: `account:read`.

**Parameters**

- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`WorkspaceListResource` with `data`, a list of `WorkspaceResource`, and `activeWorkspaceId`, `primaryWorkspaceId` and `personalWorkspaceId`. Each workspace has `id`, `name`, `slug`, `email`, `ownerId`, `plan`, `markUrl`, `wordmarkUrl` and `createdAt`, and `workspace['isOwner']` is `True` for the ones the person owns rather than joined.

**Example**

```python
from openemail import openemail

workspaces = openemail.workspaces.list()

for workspace in workspaces['data']:
    opened = workspace['id'] == workspaces['activeWorkspaceId']
    print(workspace['name'], workspace['plan'], '(open in the app)' if opened else '')
```

**Notes**

- The key or the app still acts for its own workspace in every other call.

Also available in: API [`GET /workspaces`](https://openemail.uk/docs/api/reference/workspaces#get-workspaces); TypeScript [`workspaces.list()`](https://openemail.uk/docs/sdk/reference/workspaces#list); Ruby [`workspaces.list`](https://openemail.uk/docs/ruby/reference/workspaces#list); CLI [`openemail workspaces list`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-list).

### `workspaces.create()`

Create a workspace

```python
def create(
    body: WorkspaceCreate,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> CreatedWorkspaceResource
```

Makes a new workspace owned by the person, on the Free plan, and makes it the workspace the app opens for them, as creating one in the app does. The key or the app making the call keeps acting for its own workspace.

An account can own one workspace on the Free plan. While it owns one, the call is refused with 403 `workspace_allowance_reached` and the message names that workspace: upgrade it first.

Scopes: `account:write`.

**Parameters**

- `body['name']` (`str`, required): Up to 64 characters. Leading and trailing spaces are trimmed.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`CreatedWorkspaceResource` with `id`, `name`, `slug` and `active`, which is always `True`.

**Example**

```python
from openemail import openemail

workspace = openemail.workspaces.create({'name': 'Acme Support'})

print(workspace['id'], workspace['slug'])
```

**Notes**

- Not retried automatically. The same name sent twice within ten seconds returns the workspace the first call made, so a retry right after a lost response is safe.

Also available in: API [`POST /workspaces`](https://openemail.uk/docs/api/reference/workspaces#post-workspaces); TypeScript [`workspaces.create()`](https://openemail.uk/docs/sdk/reference/workspaces#create); Ruby [`workspaces.create`](https://openemail.uk/docs/ruby/reference/workspaces#create); CLI [`openemail workspaces create`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-create).

### `workspaces.get_active()`

Read the workspace the app opens

```python
def get_active(
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> ActiveWorkspaceResource
```

Returns 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.

Scopes: `account:read`.

**Parameters**

- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`ActiveWorkspaceResource` with `id`, `name`, `slug`, `email`, `kind` and `createdAt`. `workspace['isOwner']` is `True` when the person owns it.

**Example**

```python
from openemail import openemail

opened = openemail.workspaces.get_active()

print(opened['name'], opened['kind'])
```

**Notes**

- `kind` is `personal` when the app opens the personal space, and `business` otherwise.

Also available in: API [`GET /workspaces/active`](https://openemail.uk/docs/api/reference/workspaces#get-workspaces-active); TypeScript [`workspaces.getActive()`](https://openemail.uk/docs/sdk/reference/workspaces#getActive); Ruby [`workspaces.get_active`](https://openemail.uk/docs/ruby/reference/workspaces#getActive); CLI [`openemail workspaces get-active`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-get-active).

### `workspaces.set_active()`

Choose the workspace the app opens

```python
def set_active(
    workspace_id: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> ActiveWorkspaceResource
```

Switches the workspace the app opens for the person, as the workspace switcher does, to any workspace they can open. It changes nothing for the key or the app making the call, which keeps acting for its own workspace.

Scopes: `account:write`.

**Parameters**

- `workspace_id` (`str`, required): A workspace id from `list`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`ActiveWorkspaceResource` for the workspace the app opens now.

**Example**

```python
from openemail import openemail

opened = openemail.workspaces.set_active('10417196-e324-4283-af98-66ec62167c47')

print('The app now opens', opened['name'])
```

**Notes**

- A workspace the person cannot open is a 404 `resource_not_found`.
- Retried automatically on network failure, since choosing the same workspace twice changes nothing.

Also available in: API [`PUT /workspaces/active`](https://openemail.uk/docs/api/reference/workspaces#put-workspaces-active); TypeScript [`workspaces.setActive()`](https://openemail.uk/docs/sdk/reference/workspaces#setActive); Ruby [`workspaces.set_active`](https://openemail.uk/docs/ruby/reference/workspaces#setActive); CLI [`openemail workspaces set-active`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-set-active).

### `workspaces.delete()`

Delete the workspace

```python
def delete(
    id: str,
    *,
    confirm: str,
    api_key: str | None = None,
    timeout: float | None = None,
) -> DeletedWorkspaceResource
```

Deletes the workspace the key or the app belongs to, with its domains, addresses, mail and members, and cancels its plan. It cannot be undone. `confirm=` has to be the name of the workspace, as `list` shows it, the same way the app asks the person to type it.

Only the owner may do it. An access token acting for a member is refused with 403 `owner_only`, and a key or an app limited to particular addresses or domains with 422 `capability_unsupported`. Any other workspace id is a 404, the first workspace an account made is refused with 409 `first_workspace`, and one with a domain being moved in or out with 409 `domain_moving`.

Scopes: `account:write`.

**Parameters**

- `id` (`str`, required): The id of the workspace the key or the app belongs to, which `me.get` reports as `workspaceId`.
- `confirm` (`str`, required): The name of the workspace. Letter case and the spaces around it do not matter. Sent as a query parameter.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`DeletedWorkspaceResource` with `id`, `deleted`, which is always `True`, and `activeWorkspaceId`, the workspace the app opens from now on.

**Example**

```python
from openemail import openemail

deleted = openemail.workspaces.delete(
    '10417196-e324-4283-af98-66ec62167c47', confirm='Acme Support'
)

print(deleted['id'], deleted['deleted'], 'The app now opens', deleted['activeWorkspaceId'])
```

**Notes**

- An OAuth access token needs a verification code for this call, and is refused with 403 `step_up_required` until the app has verified one in the last 60 minutes. `is_step_up_required` on the error says so. An API key is never asked for a code.
- The key or the app loses its workspace with it, so every later call with it is refused.
- Not retried automatically. A retry after a lost response is a 404, since the workspace is already gone.

Also available in: API [`DELETE /workspaces/{id}`](https://openemail.uk/docs/api/reference/workspaces#delete-workspaces-id); TypeScript [`workspaces.delete()`](https://openemail.uk/docs/sdk/reference/workspaces#delete); Ruby [`workspaces.delete`](https://openemail.uk/docs/ruby/reference/workspaces#delete); CLI [`openemail workspaces delete`](https://openemail.uk/docs/cli/reference/workspaces#workspaces-delete).