Docs
Migrating from v1Workspaces, members & budgets

Workspaces, members & budgets

New in /v2: TrulyInbox workspaces, team members and daily warmup budgets.

These endpoints let you create and manage TrulyInbox workspaces, their members, and each workspace's share of your daily warmup budget; all of them are new in v2.

Note: the old /v1/workspaces endpoints meant Google Workspace or Microsoft tenants (for bulk-connecting mailboxes). They are now called "provider workspaces" and live under /v2/workspaces/{workspaceId}/provider-workspaces - see the Bulk connect page. Do not send a tenant registration to POST /v2/workspaces: that call creates a new TrulyInbox workspace.

A TrulyInbox workspace is the container your email accounts, tags and warmup settings live in. Its numeric id is the {workspaceId} in every other v2 path.

Which key can call what

There are two kinds of key:

  • Personal key (ti_pk_...): belongs to a user. For the organization-level routes below (no {workspaceId} in the path), the user who created the key must be an organization owner right now. If they stop being an owner or leave, the key stops working on those routes - create it from a service account, not a person.
  • Workspace key (ti_ws_...): bound to one workspace. It can never act for the whole organization.

A key also needs the right scope (permission), and for workspace:manage the key must act at the admin role (or higher) in the workspace.

RoutePersonal key (ti_pk_) of an org ownerWorkspace key (ti_ws_)Scope
GET /v2/workspacesyes - every workspace in the organizationyes - only its own workspace, as a one-item listpersonal: workspace:provision; workspace key: workspace:read
POST /v2/workspacesyesno (403 workspace_forbidden)workspace:provision (+ workspace:quota if you send dailyWarmupBudget)
GET /v2/workspaces/quotasyesno (403 workspace_forbidden)workspace:quota
PATCH /v2/workspaces/quotasyesno (403 workspace_forbidden)workspace:quota
GET /v2/workspaces/{workspaceId}yes (key's user must belong to the workspace)yes, own workspaceworkspace:read
PATCH /v2/workspaces/{workspaceId}yes, as workspace adminyes, if the key acts as adminworkspace:manage
GET /v2/workspaces/{workspaceId}/membersyesyes, own workspaceworkspace:read
POST /v2/workspaces/{workspaceId}/members/inviteyes, as workspace adminyes, but cannot invite an adminworkspace:manage
PATCH /v2/workspaces/{workspaceId}/members/{userId}yes, as workspace adminyes, but cannot assign or change adminworkspace:manage
DELETE /v2/workspaces/{workspaceId}/members/{userId}yes, as workspace adminyes, but cannot remove an adminworkspace:manage

Two more rules apply to every route here:

  • Member routes (invite, change role, remove) with a workspace key check the role of the user who created the key. If that user is no longer an admin of the workspace, these routes return 403. Use a personal key of a current admin for automation that must keep working.
  • Granting or removing the admin role needs a caller who is an organization owner or admin. A workspace key never counts as one.

List workspaces

Returns the workspaces your key can reach. Call it to find the workspaceId values you need for every other v2 path.

Old APINew API
Method + routenone - newGET /v2/workspaces
Key permission (scope)none - newworkspace:provision (personal key of an org owner) or workspace:read (workspace key)
Rate bucketnone - newread
Plan needednone - new-

What changed

  • New endpoint. The old API had no TrulyInbox workspace list.
  • The old GET-style calls under /v1/workspaces/... were about Google/Microsoft tenants. Their replacement is GET /v2/workspaces/{workspaceId}/provider-workspaces.
  • With a personal key you get every workspace in the organization. With a workspace key you get a list with exactly one item. The item shape is the same either way.
  • The response is a plain array in data. There is no pagination block.

Path and query parameters

None.

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces" \
  -H "Authorization: Bearer ti_pk_your_key"

Response (new)

200 OK.

New field (inside data)TypeWhat it meansOld field
[].idnumberWorkspace id. Use it as {workspaceId} in other paths.-
[].namestringWorkspace name.-
[].quota.dailyWarmupBudgetnumberDaily warmup emails this workspace may send, taken from the organization's total. quota can be missing on old workspaces that never got a budget.-
{
  "data": [
    {
      "id": 412,
      "name": "Acme Corp",
      "quota": { "dailyWarmupBudget": 1500 }
    },
    {
      "id": 418,
      "name": "Globex Outreach",
      "quota": { "dailyWarmupBudget": 500 }
    }
  ],
  "meta": {
    "request_id": "req_7c21a9e04b",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the Authorization: Bearer header and the key.
403insufficient_scopePersonal key without workspace:provision, or workspace key without workspace:read.Create a key with the right scope.
403workspace_forbiddenPersonal key whose creator is not an organization owner.Use a key created by an organization owner.
403api_access_not_in_planYour plan does not include API access.Upgrade the plan.
403subscription_pausedThe subscription is paused. Every v2 call is blocked, reads too.Resume the subscription.
429rate_limit_exceededRead bucket is empty.Wait error.retry_after seconds, then retry.

Create a workspace

Creates a new TrulyInbox workspace in your organization. Partners usually create one workspace per end customer. You can give it a daily warmup budget in the same call.

Old APINew API
Method + routenone - newPOST /v2/workspaces
Key permission (scope)none - newworkspace:provision, plus workspace:quota if you send dailyWarmupBudget. Personal key (ti_pk_) of an organization owner only.
Rate bucketnone - newwrite
Plan needednone - new-

What changed

  • New endpoint. Warning: the old POST /v1/workspaces registered a Google/Microsoft tenant. That call moved to POST /v2/workspaces/{workspaceId}/provider-workspaces. Sending a tenant body here fails validation or creates the wrong thing.
  • Only a personal key whose creator is an organization owner can call it. A workspace key gets 403 workspace_forbidden.
  • Every organization owner (the key creator included) becomes an owner of the new workspace.
  • dailyWarmupBudget is optional. If you leave it out, the workspace starts with a budget of 0. Set it later with PATCH /v2/workspaces/quotas.
  • If the budget would push the organization over its total cap, you get 400 quota_exceeds_org_limit and nothing is created.

Path and query parameters

None.

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
namestringyesnot empty, max 100 charactersWorkspace name.-
dailyWarmupBudgetintegerno0 or more; the organization total must stay within its capDaily warmup budget for the new workspace, taken from the organization's total. Sending this field at all (even 0) needs the workspace:quota scope.-

Example request (new)

curl -X POST "$TI_BASE_URL/v2/workspaces" \
  -H "Authorization: Bearer ti_pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Initech Sales",
    "dailyWarmupBudget": 500
  }'

Response (new)

201 Created.

New field (inside data)TypeWhat it meansOld field
idnumberNew workspace id. Use it as {workspaceId} from now on.-
namestringWorkspace name.-
quota.dailyWarmupBudgetnumberThe budget it received (0 if you sent none).-
{
  "data": {
    "id": 425,
    "name": "Initech Sales",
    "quota": { "dailyWarmupBudget": 500 }
  },
  "meta": {
    "request_id": "req_91f3d0c2aa",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestname missing, empty or longer than 100 characters; dailyWarmupBudget negative or not a whole number; unknown fields.Fix the body. Read error.details.
400quota_exceeds_org_limitdailyWarmupBudget plus what is already allocated is more than the organization's cap. Nothing was created.Send a smaller budget, or first lower another workspace with PATCH /v2/workspaces/quotas. Check free room with GET /v2/workspaces/quotas.
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the key.
403insufficient_scopeKey lacks workspace:provision, or you sent dailyWarmupBudget without workspace:quota.Add the scope, or leave out dailyWarmupBudget.
403workspace_forbiddenWorkspace key used, or the personal key's creator is not an organization owner.Use a personal key of an organization owner.
403subscription_pausedThe subscription is paused.Resume the subscription.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.

Read a workspace

Returns one workspace, including its daily warmup budget.

Old APINew API
Method + routenone - newGET /v2/workspaces/{workspaceId}
Key permission (scope)none - newworkspace:read
Rate bucketnone - newread
Plan needednone - new-

What changed

  • New endpoint. The old GET /v1/workspaces/{workspaceId}/preview was about a Google/Microsoft tenant; its replacement is GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview.
  • {workspaceId} is a number, not the old hashed tenant string like aB3xY7Qk.
  • quota is left out for old workspaces that never got a budget. Treat a missing quota as "no budget set".

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The TrulyInbox workspace id.-

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/412" \
  -H "Authorization: Bearer ti_ws_your_key"

Response (new)

200 OK.

New field (inside data)TypeWhat it meansOld field
idnumberWorkspace id.-
namestringWorkspace name.-
quota.dailyWarmupBudgetnumberDaily warmup budget. quota may be missing.-
{
  "data": {
    "id": 412,
    "name": "Acme Corp",
    "quota": { "dailyWarmupBudget": 1500 }
  },
  "meta": {
    "request_id": "req_3b8e5f1d07",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the key.
403insufficient_scopeKey lacks workspace:read.Add the scope.
403workspace_forbiddenWorkspace key used on a different workspace, or the key's user is not a member of it.Use the right workspaceId or key.
404not_foundNo such workspace in your organization.Check the id with GET /v2/workspaces.
429rate_limit_exceededRead bucket is empty.Wait error.retry_after seconds.

Rename a workspace

Changes the workspace name. This is the only field you can change here.

Old APINew API
Method + routenone - newPATCH /v2/workspaces/{workspaceId}
Key permission (scope)none - newworkspace:manage (key must act as workspace admin or owner)
Rate bucketnone - newwrite
Plan needednone - new-

What changed

  • New endpoint.
  • You cannot change the daily warmup budget here. Use PATCH /v2/workspaces/quotas (organization owner only) or set it at creation.
  • Unknown fields are rejected with 400 invalid_request.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The workspace to rename.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
namestringyesnot empty, max 100 charactersNew workspace name.-

Example request (new)

curl -X PATCH "$TI_BASE_URL/v2/workspaces/412" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - EU" }'

Response (new)

200 OK. Same fields as "Read a workspace".

{
  "data": {
    "id": 412,
    "name": "Acme Corp - EU",
    "quota": { "dailyWarmupBudget": 1500 }
  },
  "meta": {
    "request_id": "req_c40a9e7b12",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestname missing, empty or too long, or you sent another field such as dailyWarmupBudget.Send only name. Change budgets with PATCH /v2/workspaces/quotas.
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the key.
403insufficient_scopeKey lacks workspace:manage, or the key acts below admin.Use a key with workspace:manage at admin level.
403workspace_forbiddenKey cannot reach this workspace.Use the right key or id.
403forbiddenThe key's user is no longer an admin of the workspace.Use a key of a current admin.
404not_foundNo such workspace.Check the id.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.

List members

Returns everyone who can use the workspace and their role. Organization owners are included with isOrgOwner: true. Pending invites are not listed.

Old APINew API
Method + routenone - newGET /v2/workspaces/{workspaceId}/members
Key permission (scope)none - newworkspace:read
Rate bucketnone - newread
Plan needednone - new-

What changed

  • New endpoint. The old API had no member management.
  • The userId in each item is the id you pass to the change-role and remove calls.
  • Plain array in data, no pagination block.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The workspace.-

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/412/members" \
  -H "Authorization: Bearer ti_ws_your_key"

Response (new)

200 OK.

New field (inside data)TypeWhat it meansOld field
[].userIdnumberThe member's user id.-
[].emailstringThe member's email.-
[].namestring or nullDisplay name, null if not set.-
[].roleowner | admin | editor | viewerRole in this workspace.-
[].isOrgOwnerbooleantrue if this user is an owner of the whole organization. You cannot change or remove them here.-
{
  "data": [
    {
      "userId": 88,
      "email": "jane@acme.com",
      "name": "Jane Cooper",
      "role": "owner",
      "isOrgOwner": true
    },
    {
      "userId": 131,
      "email": "raj@acme.com",
      "name": null,
      "role": "editor",
      "isOrgOwner": false
    }
  ],
  "meta": {
    "request_id": "req_5d09b2e6f4",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the key.
403insufficient_scopeKey lacks workspace:read.Add the scope.
403workspace_forbiddenKey cannot reach this workspace.Use the right key or id.
404not_foundNo such workspace.Check the id.
429rate_limit_exceededRead bucket is empty.Wait error.retry_after seconds.