Docs
Migrating from v1Workspaces, members & budgets

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.

Invite a member

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.

Old APINew API
Method + routenone - newPOST /v2/workspaces/{workspaceId}/members/invite
Key permission (scope)none - newworkspace:manage (key must act as workspace admin or owner)
Rate bucketnone - newwrite
Plan needednone - newpaid plan feature (team members)

What changed

  • New endpoint.
  • You cannot invite someone as owner. Allowed roles are admin, editor, viewer.
  • Inviting as admin needs a caller who is an organization owner or admin. A workspace key never is, so use a personal key for admin invites.
  • The invite expires after 48 hours (see expiresAt).

Path and query parameters

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

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
emailstringyesvalid email addressWho to invite.-
rolestringyesadmin, editor, viewerRole they get when they accept.-

Example request (new)

curl -X POST "$TI_BASE_URL/v2/workspaces/412/members/invite" \
  -H "Authorization: Bearer ti_pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria@acme.com",
    "role": "editor"
  }'

Response (new)

201 Created.

New field (inside data)TypeWhat it meansOld field
idnumberInvite id.-
emailstringInvited email.-
roleadmin | editor | viewerRole they will get.-
expiresAtstring (date-time)When the invite stops working.-
{
  "data": {
    "id": 2071,
    "email": "maria@acme.com",
    "role": "editor",
    "expiresAt": "2026-10-01T10:00:00.000Z"
  },
  "meta": {
    "request_id": "req_e82f1a6c39",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestBad email, or role is not admin, editor or viewer.Fix the body.
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the key.
403insufficient_scopeKey lacks workspace:manage, or acts below admin.Use a key with workspace:manage at admin level.
403workspace_forbiddenKey cannot reach this workspace.Use the right key or id.
403forbiddenInviting as admin without being an organization owner or admin; your plan does not include team members; or the key's creator is no longer a workspace admin.Use a personal key of an organization owner or admin; upgrade the plan if needed.
404not_foundNo such workspace.Check the id.
409conflictAlready a member, an invite is already pending for this email, or the person belongs to another organization.Do not retry. Check the member list.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.

Change a member's role

Sets a new role for an existing member.

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

What changed

  • New endpoint.
  • userId is the userId from the member list, not an invite id.
  • Allowed roles are admin, editor, viewer. You cannot make someone owner here.
  • A key cannot change the role of its own user.
  • Organization owners (isOrgOwner: true) cannot be changed here.
  • Giving the admin role, or changing someone who is admin now, needs a caller who is an organization owner or admin. A workspace key cannot do this.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The workspace.-
userIdpathnumberyes-The member's user id from the member list.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
rolestringyesadmin, editor, viewerThe new role.-

Example request (new)

curl -X PATCH "$TI_BASE_URL/v2/workspaces/412/members/131" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "role": "viewer" }'

Response (new)

200 OK. The updated member, same fields as one item of "List members".

{
  "data": {
    "userId": 131,
    "email": "raj@acme.com",
    "name": null,
    "role": "viewer",
    "isOrgOwner": false
  },
  "meta": {
    "request_id": "req_4a7c0d9e21",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestrole not allowed (for example owner), or you tried to change your own key user's role.Fix the role, or use another admin's key.
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the key.
403insufficient_scopeKey lacks workspace:manage, or acts below admin.Use a key with workspace:manage at admin level.
403workspace_forbiddenKey cannot reach this workspace.Use the right key or id.
403forbiddenTarget is an organization owner; admin involved without an organization owner or admin caller; plan lacks team members; or the key's creator is no longer a workspace admin.Manage owners in the TrulyInbox app; use a personal key of an organization owner or admin for admin changes.
404not_foundNo such workspace, or that user is not a member.Check ids with GET /v2/workspaces/{workspaceId}/members.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.

Remove a member

Removes a user from the workspace. The user keeps their TrulyInbox account and their other workspaces. Their email accounts stay in this workspace.

Old APINew API
Method + routenone - newDELETE /v2/workspaces/{workspaceId}/members/{userId}
Key permission (scope)none - newworkspace:manage (key must act as workspace admin or owner)
Rate bucketnone - newwrite
Plan needednone - newpaid plan feature (team members)

What changed

  • New endpoint.
  • Returns 204 with no body.
  • Removing a member whose role is admin needs a caller who is an organization owner or admin.
  • Careful: if userId is the key's own user, this is "leave workspace". The key then loses access to the workspace.
  • Organization owners are managed at organization level. Do not use this call for them; the last owner can never be removed.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The workspace.-
userIdpathnumberyes-The member's user id from the member list.-

Request body

No body.

Example request (new)

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

Response (new)

204 No Content. No body, no meta.

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:manage, or acts below admin.Use a key with workspace:manage at admin level.
403workspace_forbiddenKey cannot reach this workspace.Use the right key or id.
403forbiddenTarget is an admin and the caller is not an organization owner or admin; target is the last organization owner; plan lacks team members; or the key's creator is no longer a workspace admin.Use a personal key of an organization owner or admin; manage owners in the TrulyInbox app.
404not_foundNo such workspace, or that user is not a member.Treat as already removed.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.

Read budgets (quotas)

Shows the organization's total daily warmup cap, how much of it is given out, and each workspace's share.

Old APINew API
Method + routenone - newGET /v2/workspaces/quotas
Key permission (scope)none - newworkspace:quota. Personal key (ti_pk_) of an organization owner only.
Rate bucketnone - newread
Plan needednone - new-

What changed

  • New endpoint. The old API had no per-workspace budget.
  • orgLimit: null means unlimited, not zero. Do not treat null as "no room".
  • Free room = orgLimit - allocated (when orgLimit is not null).

Path and query parameters

None.

Request body

No body.

Example request (new)

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

Response (new)

200 OK.

New field (inside data)TypeWhat it meansOld field
orgLimitnumber or nullTotal daily warmup emails your plan allows across all workspaces. null = unlimited.-
allocatednumberSum of every active workspace's dailyWarmupBudget. The same number the update call checks against orgLimit.-
workspaces[].workspaceIdnumberWorkspace id.-
workspaces[].dailyWarmupBudgetnumberThat workspace's daily share.-
{
  "data": {
    "orgLimit": 2500,
    "allocated": 2000,
    "workspaces": [
      { "workspaceId": 412, "dailyWarmupBudget": 1500 },
      { "workspaceId": 418, "dailyWarmupBudget": 500 }
    ]
  },
  "meta": {
    "request_id": "req_0b6d3f8a55",
    "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:quota.Add the scope.
403workspace_forbiddenWorkspace key used, or the personal key's creator is not an organization owner.Use a personal key of an organization owner.
429rate_limit_exceededRead bucket is empty.Wait error.retry_after seconds.

Move daily warmup budget between workspaces

Sets dailyWarmupBudget for the workspaces you list. Workspaces you do not list keep their budget. Use it to give a new workspace budget, or to move budget from one workspace to another.

Old APINew API
Method + routenone - newPATCH /v2/workspaces/quotas
Key permission (scope)none - newworkspace:quota. Personal key (ti_pk_) of an organization owner only.
Rate bucketnone - newwrite
Plan needednone - new-

What changed

  • New endpoint.
  • The cap is checked once for the whole request, before anything is saved. So to move budget, lower one workspace and raise another in the same call. This works even when the organization is fully allocated. Two separate calls would fail: the "raise" call alone goes over the cap.
  • About quota_exceeds_org_limit (400): the new total of all workspace budgets (listed ones with their new values, plus unlisted ones as they are) would be more than orgLimit. Nothing is saved. Fix it by lowering another workspace in the same request, or by asking for less. Read the free room first with GET /v2/workspaces/quotas. If orgLimit is null (unlimited), this error does not happen.
  • A lower budget applies at once. If a workspace already sent more today than its new budget, it stops sending warmup emails for the rest of the day.
  • Listing the same workspace twice is a 400 invalid_request.

Path and query parameters

None.

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
quotasarray of objectsyesat least 1 item; each workspaceId only onceThe budgets to set.-
quotas[].workspaceIdintegeryesa workspace in your organizationWhich workspace.-
quotas[].dailyWarmupBudgetintegeryes0 or moreIts new daily budget.-

Example request (new)

Move 500 from workspace 412 to workspace 418 (total stays 2000):

curl -X PATCH "$TI_BASE_URL/v2/workspaces/quotas" \
  -H "Authorization: Bearer ti_pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "quotas": [
      { "workspaceId": 412, "dailyWarmupBudget": 1000 },
      { "workspaceId": 418, "dailyWarmupBudget": 1000 }
    ]
  }'

Response (new)

200 OK. data is the list of workspaces you updated, with their new budgets.

New field (inside data)TypeWhat it meansOld field
[].workspaceIdnumberWorkspace id.-
[].dailyWarmupBudgetnumberNew daily budget.-
{
  "data": [
    { "workspaceId": 412, "dailyWarmupBudget": 1000 },
    { "workspaceId": 418, "dailyWarmupBudget": 1000 }
  ],
  "meta": {
    "request_id": "req_f17b2c4e90",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400quota_exceeds_org_limitThe new total of all budgets is more than orgLimit. Nothing was saved.Lower another workspace in the same call, or ask for less. Check GET /v2/workspaces/quotas.
400invalid_requestEmpty quotas, a workspace listed twice, a negative or non-whole budget, or unknown fields.Fix the body.
401unauthorized / invalid_api_keyMissing, wrong or revoked key.Check the key.
403insufficient_scopeKey lacks workspace:quota.Add the scope.
403workspace_forbiddenWorkspace key used, or the personal key's creator is not an organization owner.Use a personal key of an organization owner.
404not_foundA listed workspaceId is not in your organization. Nothing was saved.Check ids with GET /v2/workspaces.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.