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.
| Route | Personal key (ti_pk_) of an org owner | Workspace key (ti_ws_) | Scope |
|---|---|---|---|
GET /v2/workspaces | yes - every workspace in the organization | yes - only its own workspace, as a one-item list | personal: workspace:provision; workspace key: workspace:read |
POST /v2/workspaces | yes | no (403 workspace_forbidden) | workspace:provision (+ workspace:quota if you send dailyWarmupBudget) |
GET /v2/workspaces/quotas | yes | no (403 workspace_forbidden) | workspace:quota |
PATCH /v2/workspaces/quotas | yes | no (403 workspace_forbidden) | workspace:quota |
GET /v2/workspaces/{workspaceId} | yes (key's user must belong to the workspace) | yes, own workspace | workspace:read |
PATCH /v2/workspaces/{workspaceId} | yes, as workspace admin | yes, if the key acts as admin | workspace:manage |
GET /v2/workspaces/{workspaceId}/members | yes | yes, own workspace | workspace:read |
POST /v2/workspaces/{workspaceId}/members/invite | yes, as workspace admin | yes, but cannot invite an admin | workspace:manage |
PATCH /v2/workspaces/{workspaceId}/members/{userId} | yes, as workspace admin | yes, but cannot assign or change admin | workspace:manage |
DELETE /v2/workspaces/{workspaceId}/members/{userId} | yes, as workspace admin | yes, but cannot remove an admin | workspace: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
adminrole 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 API | New API | |
|---|---|---|
| Method + route | none - new | GET /v2/workspaces |
| Key permission (scope) | none - new | workspace:provision (personal key of an org owner) or workspace:read (workspace key) |
| Rate bucket | none - new | read |
| Plan needed | none - 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 isGET /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 nopaginationblock.
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) | Type | What it means | Old field |
|---|---|---|---|
[].id | number | Workspace id. Use it as {workspaceId} in other paths. | - |
[].name | string | Workspace name. | - |
[].quota.dailyWarmupBudget | number | Daily 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Missing, wrong or revoked key. | Check the Authorization: Bearer header and the key. |
| 403 | insufficient_scope | Personal key without workspace:provision, or workspace key without workspace:read. | Create a key with the right scope. |
| 403 | workspace_forbidden | Personal key whose creator is not an organization owner. | Use a key created by an organization owner. |
| 403 | api_access_not_in_plan | Your plan does not include API access. | Upgrade the plan. |
| 403 | subscription_paused | The subscription is paused. Every v2 call is blocked, reads too. | Resume the subscription. |
| 429 | rate_limit_exceeded | Read 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 API | New API | |
|---|---|---|
| Method + route | none - new | POST /v2/workspaces |
| Key permission (scope) | none - new | workspace:provision, plus workspace:quota if you send dailyWarmupBudget. Personal key (ti_pk_) of an organization owner only. |
| Rate bucket | none - new | write |
| Plan needed | none - new | - |
What changed
- New endpoint. Warning: the old
POST /v1/workspacesregistered a Google/Microsoft tenant. That call moved toPOST /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
ownerof the new workspace. dailyWarmupBudgetis optional. If you leave it out, the workspace starts with a budget of 0. Set it later withPATCH /v2/workspaces/quotas.- If the budget would push the organization over its total cap, you get 400
quota_exceeds_org_limitand nothing is created.
Path and query parameters
None.
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
name | string | yes | not empty, max 100 characters | Workspace name. | - |
dailyWarmupBudget | integer | no | 0 or more; the organization total must stay within its cap | Daily 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) | Type | What it means | Old field |
|---|---|---|---|
id | number | New workspace id. Use it as {workspaceId} from now on. | - |
name | string | Workspace name. | - |
quota.dailyWarmupBudget | number | The 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | name missing, empty or longer than 100 characters; dailyWarmupBudget negative or not a whole number; unknown fields. | Fix the body. Read error.details. |
| 400 | quota_exceeds_org_limit | dailyWarmupBudget 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. |
| 401 | unauthorized / invalid_api_key | Missing, wrong or revoked key. | Check the key. |
| 403 | insufficient_scope | Key lacks workspace:provision, or you sent dailyWarmupBudget without workspace:quota. | Add the scope, or leave out dailyWarmupBudget. |
| 403 | workspace_forbidden | Workspace key used, or the personal key's creator is not an organization owner. | Use a personal key of an organization owner. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 429 | rate_limit_exceeded | Write bucket is empty. | Wait error.retry_after seconds. |
Read a workspace
Returns one workspace, including its daily warmup budget.
| Old API | New API | |
|---|---|---|
| Method + route | none - new | GET /v2/workspaces/{workspaceId} |
| Key permission (scope) | none - new | workspace:read |
| Rate bucket | none - new | read |
| Plan needed | none - new | - |
What changed
- New endpoint. The old
GET /v1/workspaces/{workspaceId}/previewwas about a Google/Microsoft tenant; its replacement isGET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview. {workspaceId}is a number, not the old hashed tenant string likeaB3xY7Qk.quotais left out for old workspaces that never got a budget. Treat a missingquotaas "no budget set".
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | 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) | Type | What it means | Old field |
|---|---|---|---|
id | number | Workspace id. | - |
name | string | Workspace name. | - |
quota.dailyWarmupBudget | number | Daily 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Missing, wrong or revoked key. | Check the key. |
| 403 | insufficient_scope | Key lacks workspace:read. | Add the scope. |
| 403 | workspace_forbidden | Workspace key used on a different workspace, or the key's user is not a member of it. | Use the right workspaceId or key. |
| 404 | not_found | No such workspace in your organization. | Check the id with GET /v2/workspaces. |
| 429 | rate_limit_exceeded | Read 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 API | New API | |
|---|---|---|
| Method + route | none - new | PATCH /v2/workspaces/{workspaceId} |
| Key permission (scope) | none - new | workspace:manage (key must act as workspace admin or owner) |
| Rate bucket | none - new | write |
| Plan needed | none - 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
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | The workspace to rename. | - |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
name | string | yes | not empty, max 100 characters | New 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | name missing, empty or too long, or you sent another field such as dailyWarmupBudget. | Send only name. Change budgets with PATCH /v2/workspaces/quotas. |
| 401 | unauthorized / invalid_api_key | Missing, wrong or revoked key. | Check the key. |
| 403 | insufficient_scope | Key lacks workspace:manage, or the key acts below admin. | Use a key with workspace:manage at admin level. |
| 403 | workspace_forbidden | Key cannot reach this workspace. | Use the right key or id. |
| 403 | forbidden | The key's user is no longer an admin of the workspace. | Use a key of a current admin. |
| 404 | not_found | No such workspace. | Check the id. |
| 429 | rate_limit_exceeded | Write 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 API | New API | |
|---|---|---|
| Method + route | none - new | GET /v2/workspaces/{workspaceId}/members |
| Key permission (scope) | none - new | workspace:read |
| Rate bucket | none - new | read |
| Plan needed | none - new | - |
What changed
- New endpoint. The old API had no member management.
- The
userIdin each item is the id you pass to the change-role and remove calls. - Plain array in
data, nopaginationblock.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | 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) | Type | What it means | Old field |
|---|---|---|---|
[].userId | number | The member's user id. | - |
[].email | string | The member's email. | - |
[].name | string or null | Display name, null if not set. | - |
[].role | owner | admin | editor | viewer | Role in this workspace. | - |
[].isOrgOwner | boolean | true 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Missing, wrong or revoked key. | Check the key. |
| 403 | insufficient_scope | Key lacks workspace:read. | Add the scope. |
| 403 | workspace_forbidden | Key cannot reach this workspace. | Use the right key or id. |
| 404 | not_found | No such workspace. | Check the id. |
| 429 | rate_limit_exceeded | Read bucket is empty. | Wait error.retry_after seconds. |
Account stats to Report export (removed)
Returns daily warmup numbers for one mailbox, plus its current warmup state. It replaces the old single account report.
Invite a member to Move daily warmup budget between workspaces
Sends an invitation email and returns the pending invite. The person becomes a member only after they accept, so they do not appear in the member list yet.