Migrating from v1
Move an integration from the old lupus-edge /v1 API to the /v2 API - new key, new path, new auth header, new response shape, new rate limits and paging.
The old TrulyInbox API (lupus-edge, /v1) is being replaced by this one (/v2).
To move over, change four things everywhere: the base URL, the path, the
auth header, and how you read the response. This page walks through them in
order, then maps every old endpoint to its new route.
The old host keeps serving the old API while you migrate, so you can switch one endpoint at a time.
Where to find each area
Read this page once, then open the page for the area you use and migrate one endpoint at a time. Each endpoint shows the old call, the new call, every field, example requests and example responses.
| Page | What is in it |
|---|---|
| For AI assistants | The whole migration as one brief an AI assistant can follow |
| Email accounts | List, get, connect (SMTP/IMAP and OAuth), disconnect, delete, bulk status |
| Warmup | Status, activity, settings, start (enable/resume), pause, bulk start and pause |
| Tags | List, create, set, add and remove in bulk |
| Bulk connect | Google Workspace / Microsoft 365 tenants (the old "workspaces" API) |
| Deliverability & reports | Setup score, DNS, deliverability, dashboards and stats |
| Workspaces, members & budgets | New: TrulyInbox workspaces, team members, daily budgets |
| Health, limits & billing | Health check, rate-limit status, billing |
What changed at a glance
| Topic | Old API | New API |
|---|---|---|
| Base URL | https://lupus-edge.trulyinbox.com | The base URL on the Overview page |
| Path | /v1/email-accounts/... | /v2/workspaces/{workspaceId}/accounts/... |
| Account id in the path | {emailAccountId} | {id} |
| Auth header | X-Api-Key: <key> | Authorization: Bearer <key> |
| Key types | One key per account | Workspace key ti_ws_... or personal key ti_pk_... |
| Permissions | A key can do everything | Each key has scopes, e.g. accounts:read, warmup:manage |
| Success body | The plain object | Wrapped: { "data": ..., "meta": { "request_id", "timestamp" } } |
| Lists | { items, total, page, limit, totalPages }, no documented paging params | data array + pagination; send page and limit |
| Error body | { error_code, message, details } | { "error": { code, message, details, retry_after }, "meta" } |
| Rate limit | Flat 20 requests/min per key | Per plan, split into read / write / bulk, plus 100/min per IP |
| Warmup verbs | start / stop | enable / pause / resume |
| Removed | - | Bulk delete, bulk report, report export, dashboard |
| New areas | - | Workspaces, members, budgets, tags catalog, billing |
Step 1 - Get a new key and your workspace id
Old keys do not work on the new API.
- Create a key in the app: Settings → API keys. It is shown only once, so copy it straight away.
- Pick the key type.
- Workspace key (
ti_ws_...) works for one workspace only. Calling another workspace returns 403workspace_forbidden. - Personal key (
ti_pk_...) acts as you, in every workspace you belong to. Needed for organization-level calls such as creating workspaces.
- Workspace key (
- Pick scopes. Give the key only what it needs. A missing scope returns 403
insufficient_scope. The full list is under Scopes. - Find your workspace id. Open Settings → Workspaces and pick the
workspace; the id is the
workspaceIdvalue in the address bar (for example...&workspaceId=123). See Find your workspace id. - Put the id in every path:
/v2/workspaces/{workspaceId}/....
Revoking a key takes effect at once; the next call returns 401.
Step 2 - Change the call
Before (old):
curl https://lupus-edge.trulyinbox.com/v1/email-accounts \
-H "X-Api-Key: YOUR_OLD_KEY"After (new) - send your key as a bearer token, use the workspace-scoped path, and ask for a page:
curl "$TI_BASE_URL/v2/workspaces/123/accounts?page=1&limit=25" \
-H "Authorization: Bearer ti_ws_your_key"$TI_BASE_URL is the base URL shown on the Overview page.
Step 3 - Read the response the new way
Every success is wrapped in data. Every list adds pagination. Every error is
wrapped in error.
Success (single object):
{
"data": { "id": 4821, "emailAddress": "jane@acme.com", "status": "active" },
"meta": { "request_id": "req_2f1c9a7e", "timestamp": "2026-09-29T10:00:00.000Z" }
}Success (list):
{
"data": [ { "id": 4821, "emailAddress": "jane@acme.com" } ],
"meta": { "request_id": "req_2f1c9a7e", "timestamp": "2026-09-29T10:00:00.000Z" },
"pagination": { "page": 1, "per_page": 25, "total": 60, "total_pages": 3, "has_more": true }
}Error:
{
"error": {
"code": "insufficient_scope",
"message": "This key is missing the warmup:manage scope.",
"details": {}
},
"meta": { "request_id": "req_8b1d44c0", "timestamp": "2026-09-29T10:00:00.000Z" }
}Old error, for comparison:
{ "error_code": "not_found", "message": "Email account not found.", "details": {} }- Branch on
error.code, never onerror.message(messages can change). - Quote
meta.request_idwhen you contact support. 204 No Contentresponses (delete, mark read) have no body at all.- Treat unknown
statusvalues as "a state I do not handle yet" rather than failing. New values can be added without notice.
Error codes
| HTTP | error.code | What it means | What to do |
|---|---|---|---|
| 400 | invalid_request | A field is missing, wrong type or out of range. Unknown fields are also rejected. | Fix the body; details names the field. |
| 400 | mailbox_verification_failed | The mailbox failed its send-and-receive check. | Fix the mailbox, then try again. |
| 400 | quota_exceeds_org_limit | Workspace budgets would add up to more than your plan allows. | Lower another workspace's budget first. |
| 401 | unauthorized | No key sent. | Send Authorization: Bearer <key>. |
| 401 | invalid_api_key | Key unknown or revoked. | Create a new key. |
| 403 | insufficient_scope | Key lacks the scope this route needs. | Add the scope to the key. |
| 403 | workspace_forbidden | Key cannot reach this workspace. | Use the right workspace id or a personal key. |
| 403 | api_access_not_in_plan | Your plan has no API access. | Upgrade the plan. |
| 403 | forbidden | Your role or plan does not allow this action (paid plan feature). | Upgrade, or use an admin/owner key. |
| 403 | plan_limit_reached | No room for another mailbox on your plan. | Remove a mailbox or upgrade. |
| 403 | warmup_limit_reached | Already warming as many mailboxes as your plan allows. | Pause another mailbox or upgrade. |
| 403 | subscription_paused | The subscription is paused. The API then refuses every call, reads included. | Resume the subscription. |
| 403 | partner_not_configured | Partner token connect used without a verified partner setup. | Finish partner setup first. |
| 404 | not_found | The id does not exist in this workspace. | Check the id and the workspace. |
| 409 | conflict | The action clashes with the current state (e.g. already connected). | Read the current state first. |
| 409 | mailbox_verification_pending | The mailbox check is still running. | Stop retrying; warmup starts by itself when it passes. |
| 409 | check_in_progress | A health re-check is already running for this mailbox. | Wait; the result appears on its own. |
| 422 | email_mismatch | The OAuth token belongs to a different mailbox than emailAddress. | Send the token for the mailbox you named. |
| 422 | unprocessable_entity | The request is valid but cannot be applied. | Read message, fix the data. |
| 429 | rate_limit_exceeded / too_many_requests | Too many calls. | Wait retry_after seconds (also in Retry-After). |
| 429 | recheck_too_soon | This mailbox was re-checked less than 3 hours ago. | Wait; this limit is per mailbox, not your call rate. |
| 500 | internal_error | Our fault. | Retry later; send us meta.request_id. |
Old codes such as warmup_already_active, already_disconnected and
invalid_email_account_ids no longer exist.
Step 4 - Respect the new rate limits
The old API allowed a flat 20 calls per minute per key. The new API still counts per key, but the limits come from your organization's plan and are split into three separate buckets per minute. Every IP address also has a ceiling of 100 calls per minute across all keys.
| Plan | Read / min | Write / min | Bulk / min |
|---|---|---|---|
| Free | 5 | 2 | 1 |
| Starter | 10 | 5 | 2 |
| Trial / Growth | 20 | 10 | 4 |
| Scale | 30 | 15 | 6 |
| Scale +5k | 40 | 20 | 8 |
| Scale +10k | 45 | 22 | 9 |
| Scale +20k | 50 | 25 | 10 |
- The Free plan has no API access, so its keys get 403
api_access_not_in_plan; its row only matters if API access is added to the plan. - Read =
GETcalls. Write =POST,PATCH,PUT,DELETE. Bulk = every/bulk...route, even the ones that only read. - Headers on every response:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset,X-RateLimit-IP-Limit,X-RateLimit-IP-Remaining. On 429 you also getRetry-After. - A rejected call still uses budget, so wait for
Retry-Afterbefore retrying. - Five failed key attempts from one IP lock that IP out for 15 minutes.
- Zapier, Make and n8n may share an IP with other customers, so you can hit the IP limit early there.
The full model is under Rate limits. Read your
live budget from GET /v2/workspaces/{workspaceId}/rate-limit
instead of hard-coding it.
Step 5 - Page through lists
Old list calls documented no paging parameters. New list calls return one page at a
time. Send page (starts at 1) and limit, and keep calling while
pagination.has_more is true.
let page = 1;
const all = [];
while (true) {
const res = await fetch(
`${process.env.TI_BASE_URL}/v2/workspaces/123/accounts?page=${page}&limit=100`,
{ headers: { Authorization: `Bearer ${process.env.TI_KEY}` } },
);
const body = await res.json();
all.push(...body.data);
if (!body.pagination.has_more) break;
page++;
}Warmup activity and the bulk-connect preview are the exceptions: they return total,
page and limit inside data instead of a pagination block.
Every old endpoint and where it went
| Old | New |
|---|---|
GET /v1/health | GET /v1/health (unchanged path, new host; the only /v1 route left, no key needed) |
GET /v1/rate-limit | GET /v2/workspaces/{workspaceId}/rate-limit |
GET /v1/email-accounts | GET /v2/workspaces/{workspaceId}/accounts |
POST /v1/email-accounts | POST /v2/workspaces/{workspaceId}/accounts |
GET /v1/email-accounts/{emailAccountId}/status | GET /v2/workspaces/{workspaceId}/accounts/{id} |
POST /v1/email-accounts/bulk-status | POST /v2/workspaces/{workspaceId}/accounts/bulk-status |
POST /v1/email-accounts/{emailAccountId}/disconnect | POST /v2/workspaces/{workspaceId}/accounts/{id}/disconnect |
DELETE /v1/email-accounts/{emailAccountId} | DELETE /v2/workspaces/{workspaceId}/accounts/{id} |
POST /v1/email-accounts/bulk-delete | Removed - delete one by one |
POST /v1/email-accounts/oauth (returned 501) | POST /v2/workspaces/{workspaceId}/accounts/oauth-url |
GET /v1/email-accounts/microsoft/consent-url | GET /v2/workspaces/{workspaceId}/accounts/microsoft/consent-url |
POST /v1/email-accounts/tags/assign and /unassign | POST /v2/workspaces/{workspaceId}/accounts/bulk/tags |
GET /v1/workspaces/microsoft/consent-url | GET /v2/workspaces/{workspaceId}/provider-workspaces/microsoft/consent-url |
POST /v1/workspaces | POST /v2/workspaces/{workspaceId}/provider-workspaces |
GET /v1/workspaces/{workspaceId}/preview | GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview |
POST /v1/workspaces/{workspaceId}/sync | POST /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync |
GET /v1/workspaces/{workspaceId}/sync-status | GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync-status |
GET /v1/warmup-status/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup |
GET /v1/warmup-settings/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup/settings |
PATCH /v1/warmup-settings/{emailAccountId} | PATCH /v2/workspaces/{workspaceId}/accounts/{id}/warmup/settings |
POST /v1/warmup-settings/{emailAccountId}/start | POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/enable or /resume |
POST /v1/warmup-settings/{emailAccountId}/stop | POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/pause |
POST /v1/warmup-settings/bulk-action | POST /v2/workspaces/{workspaceId}/accounts/bulk/warmup/enable and /pause |
GET /v1/setup-score/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/setup-score |
POST /v1/setup-score/{emailAccountId}/refresh | POST /v2/workspaces/{workspaceId}/accounts/{id}/setup-score/refresh |
GET /v1/dns-health/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/dns |
POST /v1/deliverability-score/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/deliverability |
GET /v1/dashboard | Removed |
POST /v1/reports | GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats |
POST /v1/reports/bulk | Removed - call GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats per account |
POST /v1/reports/export | Removed - build the CSV yourself |
The new POST /v2/workspaces creates a TrulyInbox workspace. It does not
register a Google or Microsoft tenant like the old POST /v1/workspaces did. Old
bulk-connect code must move to /provider-workspaces.
Each area below has the full old and new call for every endpoint: request fields, response fields, examples and errors.
Migration checklist
- Create a new API key with only the scopes you need
- Note your workspace id
- Switch the base URL and the path prefix to
/v2/workspaces/{workspaceId} - Replace
X-Api-KeywithAuthorization: Bearer <key> - Read results from
dataand errors fromerror.code - Rename account fields (
fromEmail→emailAddress,fromName→senderName, ...) - List accounts:
search→q,sort→sortBy, oldsortBy→sortDir, and loop over pages - Rewrite the SMTP/IMAP connect body as flat fields
- Swap warmup
start/stopforenable/resume/pause, and split bulk warmup into two calls - Rename warmup settings fields and remove old ones (unknown fields return 400)
- Convert schedule days: old
day0 = Sunday, newdayOfWeek0 = Monday, so new = (old + 6) % 7 - Merge tag assign/unassign into one
bulk/tagscall (by tag name) - Replace report
from/todates withdays(max 30) - Move bulk-connect code from
/v1/workspacesto/provider-workspaces - Replace bulk delete, bulk report and report export with your own loops
- Pace calls with
X-RateLimit-Remainingand honourRetry-After - Handle unknown status values without failing (new ones can be added)
Partner integration
Embed TrulyInbox warmup in your own product — you run the OAuth consent screen and keep the refresh token, and we call you back for access tokens.
For AI assistants
A migration brief for AI coding assistants: what to change, rename tables, a reference client and recipes for removed endpoints.