Docs
Migrating from v1

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.

PageWhat is in it
For AI assistantsThe whole migration as one brief an AI assistant can follow
Email accountsList, get, connect (SMTP/IMAP and OAuth), disconnect, delete, bulk status
WarmupStatus, activity, settings, start (enable/resume), pause, bulk start and pause
TagsList, create, set, add and remove in bulk
Bulk connectGoogle Workspace / Microsoft 365 tenants (the old "workspaces" API)
Deliverability & reportsSetup score, DNS, deliverability, dashboards and stats
Workspaces, members & budgetsNew: TrulyInbox workspaces, team members, daily budgets
Health, limits & billingHealth check, rate-limit status, billing

What changed at a glance

TopicOld APINew API
Base URLhttps://lupus-edge.trulyinbox.comThe base URL on the Overview page
Path/v1/email-accounts/.../v2/workspaces/{workspaceId}/accounts/...
Account id in the path{emailAccountId}{id}
Auth headerX-Api-Key: <key>Authorization: Bearer <key>
Key typesOne key per accountWorkspace key ti_ws_... or personal key ti_pk_...
PermissionsA key can do everythingEach key has scopes, e.g. accounts:read, warmup:manage
Success bodyThe plain objectWrapped: { "data": ..., "meta": { "request_id", "timestamp" } }
Lists{ items, total, page, limit, totalPages }, no documented paging paramsdata array + pagination; send page and limit
Error body{ error_code, message, details }{ "error": { code, message, details, retry_after }, "meta" }
Rate limitFlat 20 requests/min per keyPer plan, split into read / write / bulk, plus 100/min per IP
Warmup verbsstart / stopenable / 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.

  1. Create a key in the app: Settings → API keys. It is shown only once, so copy it straight away.
  2. Pick the key type.
    • Workspace key (ti_ws_...) works for one workspace only. Calling another workspace returns 403 workspace_forbidden.
    • Personal key (ti_pk_...) acts as you, in every workspace you belong to. Needed for organization-level calls such as creating workspaces.
  3. Pick scopes. Give the key only what it needs. A missing scope returns 403 insufficient_scope. The full list is under Scopes.
  4. Find your workspace id. Open Settings → Workspaces and pick the workspace; the id is the workspaceId value in the address bar (for example ...&workspaceId=123). See Find your workspace id.
  5. 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 on error.message (messages can change).
  • Quote meta.request_id when you contact support.
  • 204 No Content responses (delete, mark read) have no body at all.
  • Treat unknown status values as "a state I do not handle yet" rather than failing. New values can be added without notice.

Error codes

HTTPerror.codeWhat it meansWhat to do
400invalid_requestA field is missing, wrong type or out of range. Unknown fields are also rejected.Fix the body; details names the field.
400mailbox_verification_failedThe mailbox failed its send-and-receive check.Fix the mailbox, then try again.
400quota_exceeds_org_limitWorkspace budgets would add up to more than your plan allows.Lower another workspace's budget first.
401unauthorizedNo key sent.Send Authorization: Bearer <key>.
401invalid_api_keyKey unknown or revoked.Create a new key.
403insufficient_scopeKey lacks the scope this route needs.Add the scope to the key.
403workspace_forbiddenKey cannot reach this workspace.Use the right workspace id or a personal key.
403api_access_not_in_planYour plan has no API access.Upgrade the plan.
403forbiddenYour role or plan does not allow this action (paid plan feature).Upgrade, or use an admin/owner key.
403plan_limit_reachedNo room for another mailbox on your plan.Remove a mailbox or upgrade.
403warmup_limit_reachedAlready warming as many mailboxes as your plan allows.Pause another mailbox or upgrade.
403subscription_pausedThe subscription is paused. The API then refuses every call, reads included.Resume the subscription.
403partner_not_configuredPartner token connect used without a verified partner setup.Finish partner setup first.
404not_foundThe id does not exist in this workspace.Check the id and the workspace.
409conflictThe action clashes with the current state (e.g. already connected).Read the current state first.
409mailbox_verification_pendingThe mailbox check is still running.Stop retrying; warmup starts by itself when it passes.
409check_in_progressA health re-check is already running for this mailbox.Wait; the result appears on its own.
422email_mismatchThe OAuth token belongs to a different mailbox than emailAddress.Send the token for the mailbox you named.
422unprocessable_entityThe request is valid but cannot be applied.Read message, fix the data.
429rate_limit_exceeded / too_many_requestsToo many calls.Wait retry_after seconds (also in Retry-After).
429recheck_too_soonThis mailbox was re-checked less than 3 hours ago.Wait; this limit is per mailbox, not your call rate.
500internal_errorOur 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.

PlanRead / minWrite / minBulk / min
Free521
Starter1052
Trial / Growth20104
Scale30156
Scale +5k40208
Scale +10k45229
Scale +20k502510
  • 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 = GET calls. 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 get Retry-After.
  • A rejected call still uses budget, so wait for Retry-After before 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

OldNew
GET /v1/healthGET /v1/health (unchanged path, new host; the only /v1 route left, no key needed)
GET /v1/rate-limitGET /v2/workspaces/{workspaceId}/rate-limit
GET /v1/email-accountsGET /v2/workspaces/{workspaceId}/accounts
POST /v1/email-accountsPOST /v2/workspaces/{workspaceId}/accounts
GET /v1/email-accounts/{emailAccountId}/statusGET /v2/workspaces/{workspaceId}/accounts/{id}
POST /v1/email-accounts/bulk-statusPOST /v2/workspaces/{workspaceId}/accounts/bulk-status
POST /v1/email-accounts/{emailAccountId}/disconnectPOST /v2/workspaces/{workspaceId}/accounts/{id}/disconnect
DELETE /v1/email-accounts/{emailAccountId}DELETE /v2/workspaces/{workspaceId}/accounts/{id}
POST /v1/email-accounts/bulk-deleteRemoved - delete one by one
POST /v1/email-accounts/oauth (returned 501)POST /v2/workspaces/{workspaceId}/accounts/oauth-url
GET /v1/email-accounts/microsoft/consent-urlGET /v2/workspaces/{workspaceId}/accounts/microsoft/consent-url
POST /v1/email-accounts/tags/assign and /unassignPOST /v2/workspaces/{workspaceId}/accounts/bulk/tags
GET /v1/workspaces/microsoft/consent-urlGET /v2/workspaces/{workspaceId}/provider-workspaces/microsoft/consent-url
POST /v1/workspacesPOST /v2/workspaces/{workspaceId}/provider-workspaces
GET /v1/workspaces/{workspaceId}/previewGET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview
POST /v1/workspaces/{workspaceId}/syncPOST /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync
GET /v1/workspaces/{workspaceId}/sync-statusGET /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}/startPOST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/enable or /resume
POST /v1/warmup-settings/{emailAccountId}/stopPOST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/pause
POST /v1/warmup-settings/bulk-actionPOST /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}/refreshPOST /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/dashboardRemoved
POST /v1/reportsGET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats
POST /v1/reports/bulkRemoved - call GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats per account
POST /v1/reports/exportRemoved - 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-Key with Authorization: Bearer <key>
  • Read results from data and errors from error.code
  • Rename account fields (fromEmail → emailAddress, fromName → senderName, ...)
  • List accounts: search → q, sort → sortBy, old sortBy → sortDir, and loop over pages
  • Rewrite the SMTP/IMAP connect body as flat fields
  • Swap warmup start/stop for enable/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 day 0 = Sunday, new dayOfWeek 0 = Monday, so new = (old + 6) % 7
  • Merge tag assign/unassign into one bulk/tags call (by tag name)
  • Replace report from/to dates with days (max 30)
  • Move bulk-connect code from /v1/workspaces to /provider-workspaces
  • Replace bulk delete, bulk report and report export with your own loops
  • Pace calls with X-RateLimit-Remaining and honour Retry-After
  • Handle unknown status values without failing (new ones can be added)