Overview | TrulyInbox API

The TrulyInbox Public API gives external consumers — automation tools (n8n, Zapier), AI agents, and partner integrations — programmatic access to your TrulyInbox workspaces.

Every endpoint lives under a workspace-scoped path:

/v2/workspaces/{workspaceId}/...

What you can do

Domain	Capabilities
Accounts	Connect, list, read, disconnect, and delete email accounts; inspect DNS and setup score; bulk operations across up to 50 accounts.
Warmup	Read and update warmup settings; enable, pause, and resume warmup per account; read per-message send history.
Tags	List and create tags; set the tags on an account.
Analytics	Read workspace overview, trends, leaderboard, deliverability, and per-account stats.
Notifications	List notifications; mark one as read; mark all as read.
Workspace	Read and rename the workspace; list, invite, re-role, and remove its members.
Provider workspaces	Connect a Google Workspace or Microsoft 365 tenant and bulk-import its mailboxes.
Billing	Read the organization plan, usage against limits, and resolved capabilities.

Base URL

https://api-norma.trulyinbox.com

The base URL mirrors the backend's PUBLIC_API_BASE_URL configuration. The interactive Try it playground on each endpoint page targets the same base URL, so you can exercise requests without leaving the docs.

Get an API key

API keys are created from the TrulyInbox web app:

Open Settings → API keys at /settings.
Create a key. Choose its type and scopes (see Authentication).
Copy the plaintext key immediately — it is shown exactly once and cannot be retrieved again. Store it somewhere safe.

There are two key types:

Workspace key (ti_ws_…) — bound to a single workspace.
Personal key (ti_pk_…) — acts as your user across any workspace you belong to.

Find your workspace id

Every path is workspace-scoped — /v2/workspaces/{workspaceId}/… — so a request needs the numeric id of the workspace you are reading or changing.

To read it from the web app: open Settings → Workspaces and select the workspace you want. The id appears in the address bar as the workspaceId search parameter:

https://app.trulyinbox.com/settings?section=workspaces&workspaceId=123
                                                                   ↑
                                                          your workspace id

If you created a workspace key, it is already bound to one workspace — the one it was created for — and calling any other workspace with it returns Api.WorkspaceForbidden (403). A personal key works against every workspace you are a member of, so you choose the id per request.

A personal key granted the workspace:provision scope can also read the ids over the API with GET /v2/workspaces, and create new ones with POST /v2/workspaces. Both additionally require that the key belongs to an organization owner, so for most integrations reading the id from the app as above — or storing it alongside the key in your configuration — remains the simpler path.

Your first request

Every request needs an Authorization: Bearer <key> header. Replace :workspaceId with the numeric id of your workspace.

curl https://api-norma.trulyinbox.com/v1/workspaces/123/tags \
  -H "Authorization: Bearer ti_ws_your_key_here"

A successful response uses the standard envelope:

{
  "success": true,
  "data": [
    { "id": 1, "name": "production" },
    { "id": 2, "name": "cold-outreach" }
  ],
  "errorCode": null,
  "errorMessage": null
}

The shape of data is documented per endpoint in the API reference. The envelope itself — and the error codes that can appear in errorCode — are documented once under Errors.

How it fits together

Authentication is via an API key passed as a bearer token. See Authentication.
Authorization is enforced by scopes stamped on the key, intersected with the key's role in the target workspace. See Scopes.
Rate limiting is applied per key on a fixed window, with limits that vary by your plan tier. See Rate limits.
Responses use a uniform envelope and 6-digit error codes. See Errors.
Changes are recorded with dates, and breaking ones are announced 90 days before they take effect. See Changelog.
Partner integrations — where you run the OAuth consent screen and keep the refresh token — follow their own contract. See Partner integration.

Ready to go deeper? Browse the full endpoint reference under Public API.