Workspaces

A workspace holds your domains, templates, contacts, campaigns and API keys. This page covers how many workspaces an account can have, how to move between them, and what ends a workspace or someone's access to it.

Owned and joined workspaces

An account can own several workspaces and belong to others as a member, when their owners invite it (see Team).

The plan belongs to the person, not to the workspace: the plan of your account sets how many workspaces you can own. The limit counts the active workspaces you own, suspended ones included; workspaces being deleted do not count.

GET /v1/workspace returns the limit as limits.workspaces, next to domains, emailsPerMonth, membersPerAccount, membersPerWorkspace, webhooks and testSendsPerDay (requires API 0.24.0 or later). The workspaces you join as a member do not count towards it. The value is the one of the plan of the workspace owner: a member who opens someone else's workspace reads the owner's limit, not their own.

Deleted workspaces are kept as long as their data is (see Delete a workspace): an account can own at most 10 workspaces in total, counting those being deleted. Past that point, creating a workspace returns 409 CONFLICT: write to support@tratto.email.

Switch workspace in the dashboard

The dashboard has a workspace selector listing the workspaces you own and those you belong to. The choice applies to the browser tab: two tabs can work on two different workspaces at the same time.

API keys are not affected by the selector. A key belongs to the workspace it was created in and always acts on that one: switching workspace in the dashboard changes nothing for your integrations. The dashboard tells the API which workspace it is working on with the Tratto-Workspace header (see Authentication).

Accepting an invite while you already own a workspace, or belong to one, is not an error: you become a member of the new workspace and your session moves to it right away. The selector takes you back to the others.

List your workspaces

The dashboard reads the list with GET /v1/workspaces. The route accepts a dashboard session only: an API key gets 403 FORBIDDEN.

{
  "data": [
    { "id": "ws_abc123", "name": "Acme Production", "role": "owner", "status": "active" },
    { "id": "ws_def456", "name": "Client Store", "role": "member", "status": "suspended" }
  ]
}

• role says whether the account making the request owns the workspace (owner) or belongs to it as a member (member).
• status is active or suspended. A suspended workspace is read-only.
• Workspaces being deleted are not listed.
• The list is not paginated.

Create a workspace

From the dashboard, or with POST /v1/workspaces. The route accepts a dashboard session only: an API key gets 403 FORBIDDEN, and so does an account without beta access. The body is optional:

{ "name": "Acme Staging" }

name is 1 to 100 characters (default My Workspace); an invalid name gets 422 VALIDATION_ERROR. A successful request returns 201 Created with the same object as GET /v1/workspace. The new workspace becomes the one the session works on, and the dashboard refreshes its sign-in to pick it up.

Beyond your first workspace, the request is refused in this order:

See Error Codes for the format of the error body.

Delete a workspace

Only the owner can delete a workspace, and only from the dashboard. The dashboard asks for three things before it goes ahead:

• the exact name of the workspace, typed as confirmation;
• a recent sign-in, within the last 5 minutes: if yours is older, the dashboard asks you to sign in again;
• a verified email address on the owner's account: if it is not verified, the dashboard offers to send the verification email.

What happens

The effect is immediate and cannot be undone:

• the workspace stops sending email;
• every API key of the workspace is refused with 403 TENANT_CLOSED;
• nobody can open the workspace any more, members included.

The owner receives an email confirming the deletion, and every member receives an email saying the workspace has been deleted.

Your Tratto account is not deleted: you keep it, and you can create a new workspace.

Your data

Deleting the workspace ends access to it, not its data: contacts, emails and the rest of its content stay stored. Permanent deletion of the data is not automatic yet: to request it, write to support@tratto.email.

Your domains

The domains of a deleted workspace stay reserved to that workspace. If you create a new workspace, you cannot add the same domain to it yourself: write to support@tratto.email.

The API call

The dashboard calls DELETE /v1/workspace. The route accepts a dashboard session only: an API key always gets 403, whatever its permissions. For this reason workspace.delete() in the Node.js and Python SDKs cannot delete a workspace: use the dashboard. From version 1.3.0 of either SDK the method is marked deprecated (@tratto/email 1.3.0 or later, tratto-email 1.3.0 or later) and will be removed in the next major version.

The request body carries the confirmation:

{ "confirmName": "Acme Production" }

A successful request returns 202 Accepted:

{
  "data": {
    "id": "ws_abc123",
    "status": "pending_deletion",
    "deletedAt": "2026-10-05T09:30:00.000Z"
  }
}

See Error Codes for the format of the error body.

Remove a member

When a member is removed from a workspace:

• they lose access to it immediately;
• they receive an email telling them they have been removed from the workspace;
• their Tratto account stays active.

Next: Authentication · Error Codes