Tags
Tags in /v2: list, create, set on one account, and add or remove on many.
Tags are labels you put on email accounts to group them; the new API lets you list and create them, set one account's tags in a single call, and add or remove tags on many accounts in one call.
Rules that apply to every section on this page:
- Tags are always addressed by name, never by id. Names are trimmed and must be 1 to 50 characters.
- Names are case-insensitive.
Salesandsalesare the same tag. The tag keeps the spelling it was first created with. without_tagsis reserved (it is a list filter value). You cannot use it as a tag name.- A workspace can hold at most 200 tags. One account can hold at most 25 tags.
- When you remove a tag from the last account that has it, the tag is deleted from the workspace list too.
- Every write on this page (create, replace, bulk) is a paid plan feature. A key on a plan without it gets 403
forbidden. Listing tags is not plan-gated. - Write calls also need a key whose user is at least an editor in the workspace. A viewer-level key gets 403
forbidden. - The new API rejects unknown body fields with 400
invalid_request. Do not send the old field names (emailAccountIds,tagson the bulk call).
List tags
Returns every tag in the workspace, sorted by name, with how many accounts carry each one. Use it to show a tag picker or to check a name before you use it.
| Old API | New API | |
|---|---|---|
| Method + route | none - new | GET /v2/workspaces/{workspaceId}/tags |
| Key permission (scope) | - | tags:read |
| Rate bucket | - | read |
| Plan needed | - | - |
What changed
- New endpoint. The old API had no way to list tags; you could only read
tags(an array of names) on each account. - The whole list comes back in one response. There is no paging.
- Each tag has an
id, anameand anaccountCount.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | The TrulyInbox workspace that owns the tags. | - |
Request body
No body.
Example request (new)
curl -X GET "$TI_BASE_URL/v2/workspaces/42/tags" \
-H "Authorization: Bearer ti_ws_your_key"Response (new)
200 OK. data is an array of tags.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
[].id | number | Tag id. | - |
[].name | string | Tag name, in the spelling it was created with. | - |
[].accountCount | number | How many accounts in the workspace have this tag. | - |
{
"data": [
{ "id": 311, "name": "Q1 Campaign", "accountCount": 0 },
{ "id": 305, "name": "Sales", "accountCount": 14 },
{ "id": 308, "name": "US", "accountCount": 9 }
],
"meta": {
"request_id": "req_7c2a91f0",
"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 | Key missing, wrong, or revoked. | Check the Authorization: Bearer header and the key. |
| 403 | insufficient_scope | The key does not have tags:read. | Add the scope to the key. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | subscription_paused | The subscription is paused (blocks reads too). | Resume the subscription. |
| 429 | rate_limit_exceeded | Read bucket used up. | Wait error.retry_after seconds, then retry. |
Create a tag
Creates one empty tag in the workspace. Use it when you want the tag to exist before any account has it. You do not need this call before tagging accounts: the bulk and replace calls create missing names for you.
| Old API | New API | |
|---|---|---|
| Method + route | none - new | POST /v2/workspaces/{workspaceId}/tags |
| Key permission (scope) | - | tags:write |
| Rate bucket | - | write |
| Plan needed | - | paid plan feature |
What changed
- New endpoint. In the old API a tag only came into existence when you assigned it.
- If a tag with the same name already exists (any upper/lower case), you get 409
conflict. It does not return the existing tag. - An empty tag stays in the list until you assign it and later remove it from its last account.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | The TrulyInbox workspace that will own the tag. | - |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
name | string | yes | 1 to 50 characters after trimming; not without_tags | The tag name. | - |
Example request (new)
curl -X POST "$TI_BASE_URL/v2/workspaces/42/tags" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{ "name": "Q1 Campaign" }'Response (new)
201 Created. data is the new tag.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
id | number | Tag id. | - |
name | string | Tag name, trimmed. | - |
accountCount | number | Always 0 for a new tag. | - |
{
"data": { "id": 311, "name": "Q1 Campaign", "accountCount": 0 },
"meta": {
"request_id": "req_4e81b2d7",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | Name is empty, longer than 50 characters, is without_tags, or the body has unknown fields. | Fix the name or body. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong, or revoked. | Check the header and the key. |
| 403 | insufficient_scope | The key does not have tags:write. | Add the scope to the key. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | forbidden | The plan does not include tag management, or the key's user is below editor in the workspace. | Upgrade the plan, or use a key with editor access. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 409 | conflict | A tag with this name already exists, or the workspace already has 200 tags. | For a duplicate, call List tags and reuse it. For the cap, remove unused tags first. |
| 429 | rate_limit_exceeded | Write bucket used up. | Wait error.retry_after seconds, then retry. |
Replace one account's tags
Sets the full tag list of one account. Tags you send are added (created if new); tags the account has but you did not send are removed. Use it when your system owns the account's tag list.
| Old API | New API | |
|---|---|---|
| Method + route | none - new | PUT /v2/workspaces/{workspaceId}/accounts/{id}/tags |
| Key permission (scope) | - | tags:write |
| Rate bucket | - | write |
| Plan needed | - | paid plan feature |
What changed
- New endpoint. In the old API you tagged one account by sending a single id to
tags/assignortags/unassign. That still works in the new API through the bulk call (next section). - This is a replace, not an add. Any tag you leave out is removed from the account.
- An empty list
[]removes all tags from the account. - Duplicate names in the list (any case) are merged into one.
- The response is the full account object, the same shape as
GET /v2/workspaces/{workspaceId}/accounts/{id}.tagsis a list of objects{ id, name }, not a list of names as in the old API.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | The TrulyInbox workspace that owns the account. | - |
id | path | number | yes | - | The email account id. | - |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
tags | string[] | yes | Max 25 names; each 1 to 50 characters; not without_tags. [] clears all tags. | The complete list of tag names the account should have after the call. | - |
Example request (new)
curl -X PUT "$TI_BASE_URL/v2/workspaces/42/accounts/1287/tags" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{ "tags": ["Sales", "Q1 Campaign"] }'To remove every tag from the account:
curl -X PUT "$TI_BASE_URL/v2/workspaces/42/accounts/1287/tags" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{ "tags": [] }'Response (new)
200 OK. data is the full account. Only the fields most useful here are listed; the rest are described on the Email accounts page.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
id | number | Email account id. | id |
emailAddress | string | The mailbox address. | fromEmail |
senderName | string or null | Display name on sent mail. | fromName |
status | string | Connection status. New values can appear; treat unknown ones as "not handled yet". | status (different values) |
warmupStatus | string | Warmup state of the account. | - |
tags | object[] | The account's tags after the call. | tags (was string[]) |
tags[].id | number | Tag id. | - |
tags[].name | string | Tag name, in its stored spelling. | - |
createdAt | string (date-time) | When the account was added. | createdAt |
{
"data": {
"id": 1287,
"emailAddress": "jane@acme.com",
"senderName": "Jane Cooper",
"provider": "google",
"status": "active",
"warmupStatus": "active",
"warmupCurrentLimit": 18,
"warmupMaxLimit": 40,
"setupScore": 82,
"deliverabilityRate": 96.4,
"createdAt": "2026-08-14T09:12:00.000Z",
"tags": [
{ "id": 311, "name": "Q1 Campaign" },
{ "id": 305, "name": "Sales" }
]
},
"meta": {
"request_id": "req_91d03a6c",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}(The real response has more account fields than shown here. The list is on the Email accounts page.)
Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | tags missing or not an array, more than 25 items, a name that is empty, over 50 characters or without_tags, or unknown body fields. | Fix the body. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong, or revoked. | Check the header and the key. |
| 403 | insufficient_scope | The key does not have tags:write. | Add the scope to the key. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | forbidden | The plan does not include tag management, or the key's user is below editor in the workspace. | Upgrade the plan, or use a key with editor access. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 404 | not_found | No account with this id in this workspace. | Check the account id and the workspace id. |
| 409 | conflict | New names in tags would push the workspace past 200 tags. | Reuse existing names, or remove unused tags from the workspace. |
| 429 | rate_limit_exceeded | Write bucket used up. | Wait error.retry_after seconds, then retry. |
Add or remove tags on many accounts
Adds tags to, and/or removes tags from, up to 200 accounts in one call. This one endpoint replaces both old endpoints, tags/assign and tags/unassign.
| Old API | New API | |
|---|---|---|
| Method + route | POST /v1/email-accounts/tags/assign and POST /v1/email-accounts/tags/unassign | POST /v2/workspaces/{workspaceId}/accounts/bulk/tags |
| Key permission (scope) | any key | tags:write |
| Rate bucket | 20/min shared | bulk |
| Plan needed | - | paid plan feature |
What changed
- Two calls become one. Put names to add in
addTagsand names to remove inremoveTags. Send either one or both. emailAccountIdsis renamedids(max 200). The singletagsfield is split intoaddTagsandremoveTags(max 25 names each).- Tags are still addressed by name. Unknown names in
addTagsare created. Unknown names inremoveTagsare ignored, as before. - Ids that are not in this workspace are skipped silently. There is no error for them. Check
data.accountsto see how many accounts were really changed. - The response is now three counts (
added,removed,accounts). The old API returned the list of changed accounts. If you need the new tag lists, callGET /v2/workspaces/{workspaceId}/accountsafterwards. - The call counts against the bulk bucket, which is smaller than the write bucket.
Old two-call flow vs new one-call body
To tag accounts 123 and 456 with Q3-outreach and take US off them:
Old - two requests:
curl -X POST "https://lupus-edge.trulyinbox.com/v1/email-accounts/tags/assign" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "emailAccountIds": [123, 456], "tags": ["Q3-outreach"] }'
curl -X POST "https://lupus-edge.trulyinbox.com/v1/email-accounts/tags/unassign" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "emailAccountIds": [123, 456], "tags": ["US"] }'New - one request:
curl -X POST "$TI_BASE_URL/v2/workspaces/42/accounts/bulk/tags" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{ "ids": [123, 456], "addTags": ["Q3-outreach"], "removeTags": ["US"] }'| Old body (assign) | Old body (unassign) | New body |
|---|---|---|
emailAccountIds: [123, 456] | emailAccountIds: [123, 456] | ids: [123, 456] |
tags: ["Q3-outreach"] | - | addTags: ["Q3-outreach"] |
| - | tags: ["US"] | removeTags: ["US"] |
Good to know:
- Adds run first, then removes. If the same name is in both lists, it ends up removed.
- Adding a tag an account already has does nothing and is not counted in
added. - If a removed tag is left on no account at all, it is deleted from the workspace tag list.
- There is no per-account 25-tag check on this call (the replace call has one). Do not rely on it to stop you.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | The TrulyInbox workspace that owns the accounts. | - (was not in the path) |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
ids | number[] | yes | 1 to 200 ids; whole numbers of 1 or more; no duplicates | Email account ids to change. | emailAccountIds |
addTags | string[] | no | Max 25 names; each 1 to 50 characters; not without_tags | Names to add to every account. New names are created. | tags on tags/assign |
removeTags | string[] | no | Max 25 names; each 1 to 50 characters | Names to remove from every account. Unknown names are ignored. | tags on tags/unassign |
If you send neither addTags nor removeTags, the call succeeds and changes nothing.
Example request (new)
curl -X POST "$TI_BASE_URL/v2/workspaces/42/accounts/bulk/tags" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{
"ids": [1287, 1288, 1291],
"addTags": ["Sales"],
"removeTags": ["Old Campaign"]
}'Example request (old)
See the two old requests above (tags/assign then tags/unassign).
Response (new)
200 OK.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
added | number | Tag assignments created, counted across all accounts (3 accounts × 1 new tag = 3). | - (old returned the accounts) |
removed | number | Tag assignments removed, counted across all accounts. | - |
accounts | number | Accounts in this workspace that the call applied to. Lower than ids.length if some ids were skipped. | - |
{
"data": {
"added": 3,
"removed": 2,
"accounts": 3
},
"meta": {
"request_id": "req_b52f10e8",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}If none of the ids are in the workspace, you still get 200 with { "added": 0, "removed": 0, "accounts": 0 }.
Response (old)
Both old endpoints returned a bare array of the changed accounts, with tags as names:
[
{
"id": 123,
"fromEmail": "jane@acme.com",
"fromName": "Jane Cooper",
"type": "gmail",
"status": "warming",
"createdAt": "2026-08-14T09:12:00.000Z",
"warmupScore": 92,
"outreachReadinessStatus": "readyForOutreach",
"workspaceId": null,
"tags": ["Q3-outreach"]
}
]Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | ids missing, empty, over 200, duplicated or not whole numbers; a list over 25 names; a bad tag name; or old field names such as emailAccountIds / tags in the body. (Old API: invalid_email_account_ids.) | Fix the body. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong, or revoked. | Check the header and the key. |
| 403 | insufficient_scope | The key does not have tags:write. | Add the scope to the key. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | forbidden | The plan does not include tag management, or the key's user is below editor in the workspace. | Upgrade the plan, or use a key with editor access. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 409 | conflict | New names in addTags would push the workspace past 200 tags. | Remove unused tags, or reuse existing names. |
| 429 | rate_limit_exceeded | Bulk bucket used up. | Wait error.retry_after seconds, then retry. |