Docs
Migrating from v1Tags

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. Sales and sales are the same tag. The tag keeps the spelling it was first created with.
  • without_tags is 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, tags on 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 APINew API
Method + routenone - newGET /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, a name and an accountCount.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-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)TypeWhat it meansOld field
[].idnumberTag id.-
[].namestringTag name, in the spelling it was created with.-
[].accountCountnumberHow 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

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyKey missing, wrong, or revoked.Check the Authorization: Bearer header and the key.
403insufficient_scopeThe key does not have tags:read.Add the scope to the key.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403subscription_pausedThe subscription is paused (blocks reads too).Resume the subscription.
429rate_limit_exceededRead 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 APINew API
Method + routenone - newPOST /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

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The TrulyInbox workspace that will own the tag.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
namestringyes1 to 50 characters after trimming; not without_tagsThe 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)TypeWhat it meansOld field
idnumberTag id.-
namestringTag name, trimmed.-
accountCountnumberAlways 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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestName is empty, longer than 50 characters, is without_tags, or the body has unknown fields.Fix the name or body.
401unauthorized / invalid_api_keyKey missing, wrong, or revoked.Check the header and the key.
403insufficient_scopeThe key does not have tags:write.Add the scope to the key.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403forbiddenThe 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.
403subscription_pausedThe subscription is paused.Resume the subscription.
409conflictA 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.
429rate_limit_exceededWrite 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 APINew API
Method + routenone - newPUT /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/assign or tags/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}. tags is a list of objects { id, name }, not a list of names as in the old API.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The TrulyInbox workspace that owns the account.-
idpathnumberyes-The email account id.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
tagsstring[]yesMax 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)TypeWhat it meansOld field
idnumberEmail account id.id
emailAddressstringThe mailbox address.fromEmail
senderNamestring or nullDisplay name on sent mail.fromName
statusstringConnection status. New values can appear; treat unknown ones as "not handled yet".status (different values)
warmupStatusstringWarmup state of the account.-
tagsobject[]The account's tags after the call.tags (was string[])
tags[].idnumberTag id.-
tags[].namestringTag name, in its stored spelling.-
createdAtstring (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

HTTPerror.codeWhen it happensWhat to do
400invalid_requesttags 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.
401unauthorized / invalid_api_keyKey missing, wrong, or revoked.Check the header and the key.
403insufficient_scopeThe key does not have tags:write.Add the scope to the key.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403forbiddenThe 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.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace.Check the account id and the workspace id.
409conflictNew names in tags would push the workspace past 200 tags.Reuse existing names, or remove unused tags from the workspace.
429rate_limit_exceededWrite 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 APINew API
Method + routePOST /v1/email-accounts/tags/assign and POST /v1/email-accounts/tags/unassignPOST /v2/workspaces/{workspaceId}/accounts/bulk/tags
Key permission (scope)any keytags:write
Rate bucket20/min sharedbulk
Plan needed-paid plan feature

What changed

  • Two calls become one. Put names to add in addTags and names to remove in removeTags. Send either one or both.
  • emailAccountIds is renamed ids (max 200). The single tags field is split into addTags and removeTags (max 25 names each).
  • Tags are still addressed by name. Unknown names in addTags are created. Unknown names in removeTags are ignored, as before.
  • Ids that are not in this workspace are skipped silently. There is no error for them. Check data.accounts to 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, call GET /v2/workspaces/{workspaceId}/accounts afterwards.
  • 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

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-The TrulyInbox workspace that owns the accounts.- (was not in the path)

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
idsnumber[]yes1 to 200 ids; whole numbers of 1 or more; no duplicatesEmail account ids to change.emailAccountIds
addTagsstring[]noMax 25 names; each 1 to 50 characters; not without_tagsNames to add to every account. New names are created.tags on tags/assign
removeTagsstring[]noMax 25 names; each 1 to 50 charactersNames 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)TypeWhat it meansOld field
addednumberTag assignments created, counted across all accounts (3 accounts × 1 new tag = 3).- (old returned the accounts)
removednumberTag assignments removed, counted across all accounts.-
accountsnumberAccounts 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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestids 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.
401unauthorized / invalid_api_keyKey missing, wrong, or revoked.Check the header and the key.
403insufficient_scopeThe key does not have tags:write.Add the scope to the key.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403forbiddenThe 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.
403subscription_pausedThe subscription is paused.Resume the subscription.
409conflictNew names in addTags would push the workspace past 200 tags.Remove unused tags, or reuse existing names.
429rate_limit_exceededBulk bucket used up.Wait error.retry_after seconds, then retry.