For AI assistants
A migration brief for AI coding assistants: what to change, rename tables, a reference client and recipes for removed endpoints.
Hand this section to your AI coding assistant (Claude, ChatGPT, Cursor, GitHub Copilot or any other) together with your code. It tells the assistant exactly what to change. Field-level detail for each new route is in the API reference in the sidebar.
Your task
You are migrating a codebase that calls the old TrulyInbox API so it calls the
new /v2 API instead. Keep behaviour the same wherever the new API allows it.
Where an old feature no longer exists, apply the replacement recipe below and leave a
short code comment saying why.
Work in this order:
- Find every call site. Search the code for
lupus-edge,trulyinbox.com/v1,X-Api-Key,/v1/email-accounts,/v1/warmup-settings,/v1/warmup-status,/v1/workspaces,/v1/setup-score,/v1/dns-health,/v1/deliverability-score,/v1/dashboard,/v1/reports,/v1/rate-limit, and field names such asemailAccountId,fromEmail,fromName,error_code,timeSlots,maxSendingLimit. List what you found before changing anything. - Centralise the client. If requests are built in many places, add one small client (base URL, auth header, envelope unwrap, error mapping, paging, 429 retry) and route every call through it. See Reference client.
- Migrate endpoint by endpoint using the endpoint map above and the rename tables below. Change request paths, methods, query names, body fields, and every place that reads a response field.
- Handle removed endpoints with the recipes.
- Update tests and fixtures. Mocked responses must use the new
data/metaenvelope and the new field names. - Report back: a table of every call site changed (old → new), anything you could not migrate, and every new configuration value the user must supply (API key, workspace id).
Never invent fields. If something is not covered here, look it up in the API reference or ask the user.
Global rules
| What | Old | New |
|---|---|---|
| Path prefix | /v1/... | /v2/workspaces/{workspaceId}/... (workspace id is a number, from config) |
| Auth header | X-Api-Key: <key> | Authorization: Bearer <key> |
| Key | One key | A new key is required. Old keys do not work. |
| Account id in path | {emailAccountId} (string in some old calls) | {id} (number) |
| Success body | The plain object / array | { data, meta }, so read body.data |
| List body | { items, total, page, limit, totalPages } | { data: [...], meta, pagination } |
| Error body | { error_code, message, details } | { error: { code, message, details, retry_after? }, meta }, so branch on error.code |
| 204 responses | - | No body at all (delete account) |
| Unknown request fields | Ignored | Rejected with 400 invalid_request. Remove every old field name. |
| Rate limit | 20/min per key | Per key by plan, in three buckets (read, write, bulk), plus 100/min per IP. Honour Retry-After on 429. |
| Paused subscription | - | Every call, reads included, returns 403 subscription_paused |
Old API keys do not work on v2: the user must create a new API key after they are migrated to v2. To get their workspace ids, they can call List workspaces.
New configuration the user must provide: TRULYINBOX_API_KEY (a new key) and
TRULYINBOX_WORKSPACE_ID (a number). The scopes the key needs depend on the calls
used: accounts:read, accounts:write, warmup:read, warmup:manage, tags:read,
tags:write, analytics:read (plus billing:read, workspace:*
only for new-only features).
What changes per endpoint
| Old | What changes |
|---|---|
GET /v1/health | Response is now { data: { status, timestamp }, meta }. |
GET /v1/rate-limit | Counts against the read bucket; shows all three buckets. |
GET /v1/email-accounts | Query renames (below); paged. |
POST /v1/email-accounts | Body is flat (below); returns the account object; may auto-enable warmup. |
GET .../{emailAccountId}/status | Returns the full account object. |
POST .../bulk-status | emailAccountIds → accountIds (numbers, max 50, unique); result { accounts, notFound }; bulk bucket. |
POST .../disconnect | Returns the account object; already disconnected → 400 invalid_request (was 409). |
DELETE .../{emailAccountId} | 204, no body. |
POST /v1/email-accounts/oauth (returned 501) | POST .../accounts/oauth-url returns a consent link for gmail, google_workspace, outlook, ms365. |
GET .../microsoft/consent-url | Same email query and { url, expiresAt }; needs accounts:write. |
POST .../tags/assign + /unassign | One call, { ids, addTags, removeTags }, by tag name; bulk bucket. |
POST /v1/workspaces | Do not call the new POST /v2/workspaces (that creates a TrulyInbox workspace). Use /provider-workspaces. Microsoft now also needs state. data.id is the numeric providerWorkspaceId. |
GET /v1/workspaces/{workspaceId}/preview | Path id is now the numeric providerWorkspaceId; domain is a JSON array string such as ["a.com","b.com"]; takes page, limit. |
POST .../sync | emailAccountIdsToDelete and tagName removed; the response is only { jobId }. |
GET .../sync-status | { state, failedReason } → { status, total, processed, succeeded, failed, failures[] }. Stop polling when status is complete or failed. |
GET /v1/warmup-status/{emailAccountId} | Full account with ramp progress; per-email detail is GET .../accounts/{id}/warmup/activity. |
GET / PATCH /v1/warmup-settings/{emailAccountId} | Renames (below); unknown fields → 400. |
POST .../warmup-settings/{emailAccountId}/start | warmup/enable for a first start, warmup/resume after a pause or suspension. Returns the account object. |
POST .../warmup-settings/{emailAccountId}/stop | warmup/pause. Returns the account object. |
POST /v1/warmup-settings/bulk-action | Split by action into bulk/warmup/enable and bulk/warmup/pause. Body { ids } (max 200); no action, no tags (resolve tags to ids with GET .../accounts?tags=... first). Result { succeeded: [ids], failed: [{ id, error }] }. |
GET /v1/setup-score/{emailAccountId} | { score, band, items[], dnsCheckedAt }; band null means never scored. |
POST .../setup-score/{emailAccountId}/refresh | Once per 3 hours per mailbox (429 recheck_too_soon); 409 check_in_progress means wait. |
GET /v1/dns-health/{emailAccountId} | Reads stored records only; raw record data instead of pass/fail; data: null means not checked yet. |
POST /v1/deliverability-score/{emailAccountId} | Now a GET with no body, a fixed 30 days and no per-ESP split. Different formula, so scores are not comparable. |
GET /v1/dashboard | Removed, with no single replacement. For counts by status, list accounts with a status filter and read pagination.total. |
POST /v1/reports | Now a GET; from / to → days (max 30). |
POST /v1/reports/bulk | Removed. Call GET .../accounts/{id}/analytics/stats once per account (read bucket). |
Renames
Account object (response)
| Old | New |
|---|---|
id / emailAccountId | id |
fromEmail | emailAddress |
fromName | senderName |
type (gmail, microsoft, smtp-imap) | provider |
status (active, warming, paused, error, auth-expired) | status (CONNECTED / DISCONNECTED) and warmupStatus. There is no 1:1 mapping. |
authStatus, connectionError | status. connectionError has no replacement; check warmupStatus and warmupPausedReason. |
warmupStatus (active, paused, stopped, blocked) | warmupStatus, warmupPausedReason |
healthScore | setupScore (0-100) |
warmupScore, outreachReadinessStatus | deliverabilityRate; readiness is now the list filter outreachReadiness |
lastConnectedAt | Removed |
workspaceId (string) | Removed (it is in the URL) |
tags (names) | tags ([{ id, name }]) |
Treat unknown enum values (status, state, provider) as "not handled yet" and never throw on them; new values are added over time.
List accounts query
| Old | New |
|---|---|
search | q |
sort (createdAt, fromEmail, fromName) | sortBy (email, status, score, createdAt) |
sortBy (ASC, DESC) | sortDir (asc, desc). Careful: sortBy changed meaning. |
status | status (all, active, throttled, paused, suspended, cooldown, maintenance, disconnected; repeatable) |
tags | tags (by name, any match) |
| - | page (default 1), limit (default 25, max 100). Loop while pagination.has_more. |
SMTP/IMAP connect body
The new body is flat, with no nested objects.
| Old | New |
|---|---|
fromName | senderName |
emailServiceProvider (required) | espPresetId (optional, e.g. "zoho") |
smtp.emailAddress | emailAddress |
smtp.host / smtp.port | smtpHost / smtpPort |
smtp.encryption (true/false) | smtpEncryption ("SSL", "TLS", "NONE") |
smtp.userName (optional) | smtpUsername (required) |
smtp.password | password |
imap.host / imap.port | imapHost / imapPort |
imap.encryption (true/false) | imapEncryption ("SSL", "TLS", "NONE") |
imap.emailAddress | imapUsername (optional, defaults to smtpUsername) |
imap.password | imapPassword (optional, defaults to password) |
Email uniqueness is global: connecting an address that is already connected anywhere
returns 409 conflict.
Warmup settings (GET and PATCH)
| Old | New |
|---|---|
maxSendingLimit | warmupMaxLimit (min 5, max is the plan cap maxWarmupPerAccount) |
warmUpInitialSendingLimit | Removed (the ramp always starts at 5). Do not send. |
increaseEmailsByNumber | Removed (the ramp is automatic). Do not send. |
dailySendingLimit | warmupCurrentLimit on GET .../accounts/{id}/warmup (read-only, not in settings) |
strategy | Removed. Do not send. |
timeZone | timezone |
warmupLanguage | language |
googleVolume / microsoftVolume / othersVolume (PATCH), googleVolumePercentage, microsoftVolumePercentage, othersVolumePercentage (GET) | espMode: "CUSTOM" + espGooglePct / espMicrosoftPct / espOthersPct (send all three, sum 100; paid plan feature) |
replyRate | replyRateMode: "CUSTOM" + replyRate (ignored unless the mode is CUSTOM); "LEVEL" is automatic |
timeSlots[{ day, fromHour, fromMinute, toHour, toMinute, isEnabled }] | schedule[{ dayOfWeek, slotIndex, weight, enabled, startTime: "HH:MM", endTime: "HH:MM" }] |
upcomingContentConfig | industry, topics, templateLabels, templateRatioPercent. PATCH also takes contentMode, customPrompt and templateLabelIds; GET does not return them. |
warmupStatus | Removed from settings. Read GET .../accounts/{id}/warmup. |
| - | New: senderName, dkimSelector, warmupFolder |
Schedule conversion is easy to get wrong:
- Day numbering changed: old
day0 = Sunday; newdayOfWeek0 = Monday and 6 = Sunday. Convert withdayOfWeek = (day + 6) % 7. - The schedule is replaced whole: send all 7 days (1-2 slots each).
startTimemust be beforeendTime, even on disabled days. - On an enabled day each slot must be at least 2 hours and the day at least 6 hours in total; slot weights on an enabled day sum to 100.
contentMode: "industry_topic"needs at least one topic.
// Old timeSlots → new schedule (one slot per day)
const pad = (n) => String(n).padStart(2, '0');
function toSchedule(timeSlots) {
return timeSlots.map((s) => ({
dayOfWeek: (s.day + 6) % 7,
slotIndex: 0,
weight: 100,
enabled: s.isEnabled,
startTime: `${pad(s.fromHour)}:${pad(s.fromMinute)}`,
endTime: `${pad(s.toHour)}:${pad(s.toMinute)}`,
}));
}Error handling
Map on error.code, never on error.message. The codes and what to do about each are
in the error code table above. In code:
- Do not retry:
invalid_request,unauthorized,invalid_api_key,insufficient_scope,workspace_forbidden,mailbox_verification_pending(warmup starts by itself when the check passes). - Wait
error.retry_after(orRetry-After) seconds, then retry:rate_limit_exceeded,too_many_requests. - Do not back off globally:
recheck_too_soonis a per-mailbox 3-hour limit on setup-score refresh, not your call rate. - Log
meta.request_idand retry later:internal_error.
Delete any handler that matches the old codes warmup_already_active,
already_disconnected, invalid_email_account_ids, workspace_validation_failed or
mailboxes_not_found. They no longer exist.
Reference client
TypeScript; adapt it to the codebase's language and HTTP library. TRULYINBOX_BASE_URL
is the base URL.
const BASE = process.env.TRULYINBOX_BASE_URL!;
const KEY = process.env.TRULYINBOX_API_KEY!;
const WS = Number(process.env.TRULYINBOX_WORKSPACE_ID);
export class TrulyInboxError extends Error {
constructor(
public status: number,
public code: string,
message: string,
public details?: unknown,
public requestId?: string,
) {
super(message);
}
}
export async function ti<T>(
method: string,
path: string,
body?: unknown,
retries = 3,
): Promise<{ data: T; pagination?: any }> {
const res = await fetch(`${BASE}${path.replace('{workspaceId}', String(WS))}`, {
method,
headers: {
Authorization: `Bearer ${KEY}`,
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 204) return { data: undefined as T };
const json = await res.json();
if (!res.ok) {
const code = json?.error?.code ?? 'internal_error';
if ((code === 'rate_limit_exceeded' || code === 'too_many_requests') && retries > 0) {
const wait = Number(res.headers.get('Retry-After') ?? json.error.retry_after ?? 5);
await new Promise((r) => setTimeout(r, wait * 1000));
return ti<T>(method, path, body, retries - 1);
}
throw new TrulyInboxError(
res.status,
code,
json?.error?.message ?? res.statusText,
json?.error?.details,
json?.meta?.request_id,
);
}
return { data: json.data as T, pagination: json.pagination };
}
export async function tiAll<T>(path: string, limit = 100): Promise<T[]> {
const out: T[] = [];
for (let page = 1; ; page++) {
const sep = path.includes('?') ? '&' : '?';
const { data, pagination } = await ti<T[]>('GET', `${path}${sep}page=${page}&limit=${limit}`);
out.push(...data);
if (!pagination?.has_more) return out;
}
}
// usage:
// const accounts = await tiAll<Account>('/v2/workspaces/{workspaceId}/accounts');
// await ti('POST', `/v2/workspaces/{workspaceId}/accounts/${id}/warmup/pause`);Recipes for removed endpoints
- Bulk delete: for each id,
DELETE /v2/workspaces/{workspaceId}/accounts/{id}(expect 204; treat 404 as already gone). Run sequentially or with low concurrency and watchX-RateLimit-Remaining(write bucket). - Report export and bulk report:
tiAll('/v2/workspaces/{workspaceId}/accounts')for the ids, thenGET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats?days=<1-30>for each id, one at a time (read bucket). Write the CSV rows fromdata.dailyBreakdown[]and collect ids that return 404 separately. - Bulk warmup by tag:
tiAll('/v2/workspaces/{workspaceId}/accounts?tags=<name>'), take theids, chunk by 200, and callPOST .../accounts/bulk/warmup/enableorPOST .../accounts/bulk/warmup/pause. - Report
from/to:days = min(30, ceil((now - from) / 1 day)). The window always ends today (UTC), so custom past ranges are no longer possible.
Done checklist
- No remaining references to
lupus-edge,X-Api-Keyor/v1/paths - Every response read goes through
data; every list is paged - No old field names sent in any body (they return 400)
- Error handling keyed on
error.code; 429 retried afterRetry-After - Schedule days converted with
(day + 6) % 7 - Removed endpoints replaced with loops
- Tests and fixtures use the new envelope and names
- The user was told which new config values and key scopes are needed