Docs
Migrating from v1

For AI assistants

A migration brief for AI coding assistants: what to change, rename tables, a reference client and recipes for removed endpoints.

Download .mdPaste it into Claude (or another assistant) along with your code.

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:

  1. 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 as emailAccountId, fromEmail, fromName, error_code, timeSlots, maxSendingLimit. List what you found before changing anything.
  2. 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.
  3. 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.
  4. Handle removed endpoints with the recipes.
  5. Update tests and fixtures. Mocked responses must use the new data / meta envelope and the new field names.
  6. 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

WhatOldNew
Path prefix/v1/.../v2/workspaces/{workspaceId}/... (workspace id is a number, from config)
Auth headerX-Api-Key: <key>Authorization: Bearer <key>
KeyOne keyA new key is required. Old keys do not work.
Account id in path{emailAccountId} (string in some old calls){id} (number)
Success bodyThe 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 fieldsIgnoredRejected with 400 invalid_request. Remove every old field name.
Rate limit20/min per keyPer 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

OldWhat changes
GET /v1/healthResponse is now { data: { status, timestamp }, meta }.
GET /v1/rate-limitCounts against the read bucket; shows all three buckets.
GET /v1/email-accountsQuery renames (below); paged.
POST /v1/email-accountsBody is flat (below); returns the account object; may auto-enable warmup.
GET .../{emailAccountId}/statusReturns the full account object.
POST .../bulk-statusemailAccountIds → accountIds (numbers, max 50, unique); result { accounts, notFound }; bulk bucket.
POST .../disconnectReturns 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-urlSame email query and { url, expiresAt }; needs accounts:write.
POST .../tags/assign + /unassignOne call, { ids, addTags, removeTags }, by tag name; bulk bucket.
POST /v1/workspacesDo 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}/previewPath id is now the numeric providerWorkspaceId; domain is a JSON array string such as ["a.com","b.com"]; takes page, limit.
POST .../syncemailAccountIdsToDelete 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}/startwarmup/enable for a first start, warmup/resume after a pause or suspension. Returns the account object.
POST .../warmup-settings/{emailAccountId}/stopwarmup/pause. Returns the account object.
POST /v1/warmup-settings/bulk-actionSplit 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}/refreshOnce 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/dashboardRemoved, with no single replacement. For counts by status, list accounts with a status filter and read pagination.total.
POST /v1/reportsNow a GET; from / to → days (max 30).
POST /v1/reports/bulkRemoved. Call GET .../accounts/{id}/analytics/stats once per account (read bucket).

Renames

Account object (response)

OldNew
id / emailAccountIdid
fromEmailemailAddress
fromNamesenderName
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, connectionErrorstatus. connectionError has no replacement; check warmupStatus and warmupPausedReason.
warmupStatus (active, paused, stopped, blocked)warmupStatus, warmupPausedReason
healthScoresetupScore (0-100)
warmupScore, outreachReadinessStatusdeliverabilityRate; readiness is now the list filter outreachReadiness
lastConnectedAtRemoved
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

OldNew
searchq
sort (createdAt, fromEmail, fromName)sortBy (email, status, score, createdAt)
sortBy (ASC, DESC)sortDir (asc, desc). Careful: sortBy changed meaning.
statusstatus (all, active, throttled, paused, suspended, cooldown, maintenance, disconnected; repeatable)
tagstags (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.

OldNew
fromNamesenderName
emailServiceProvider (required)espPresetId (optional, e.g. "zoho")
smtp.emailAddressemailAddress
smtp.host / smtp.portsmtpHost / smtpPort
smtp.encryption (true/false)smtpEncryption ("SSL", "TLS", "NONE")
smtp.userName (optional)smtpUsername (required)
smtp.passwordpassword
imap.host / imap.portimapHost / imapPort
imap.encryption (true/false)imapEncryption ("SSL", "TLS", "NONE")
imap.emailAddressimapUsername (optional, defaults to smtpUsername)
imap.passwordimapPassword (optional, defaults to password)

Email uniqueness is global: connecting an address that is already connected anywhere returns 409 conflict.

Warmup settings (GET and PATCH)

OldNew
maxSendingLimitwarmupMaxLimit (min 5, max is the plan cap maxWarmupPerAccount)
warmUpInitialSendingLimitRemoved (the ramp always starts at 5). Do not send.
increaseEmailsByNumberRemoved (the ramp is automatic). Do not send.
dailySendingLimitwarmupCurrentLimit on GET .../accounts/{id}/warmup (read-only, not in settings)
strategyRemoved. Do not send.
timeZonetimezone
warmupLanguagelanguage
googleVolume / microsoftVolume / othersVolume (PATCH), googleVolumePercentage, microsoftVolumePercentage, othersVolumePercentage (GET)espMode: "CUSTOM" + espGooglePct / espMicrosoftPct / espOthersPct (send all three, sum 100; paid plan feature)
replyRatereplyRateMode: "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" }]
upcomingContentConfigindustry, topics, templateLabels, templateRatioPercent. PATCH also takes contentMode, customPrompt and templateLabelIds; GET does not return them.
warmupStatusRemoved from settings. Read GET .../accounts/{id}/warmup.
-New: senderName, dkimSelector, warmupFolder

Schedule conversion is easy to get wrong:

  • Day numbering changed: old day 0 = Sunday; new dayOfWeek 0 = Monday and 6 = Sunday. Convert with dayOfWeek = (day + 6) % 7.
  • The schedule is replaced whole: send all 7 days (1-2 slots each). startTime must be before endTime, 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 (or Retry-After) seconds, then retry: rate_limit_exceeded, too_many_requests.
  • Do not back off globally: recheck_too_soon is a per-mailbox 3-hour limit on setup-score refresh, not your call rate.
  • Log meta.request_id and 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 watch X-RateLimit-Remaining (write bucket).
  • Report export and bulk report: tiAll('/v2/workspaces/{workspaceId}/accounts') for the ids, then GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats?days=<1-30> for each id, one at a time (read bucket). Write the CSV rows from data.dailyBreakdown[] and collect ids that return 404 separately.
  • Bulk warmup by tag: tiAll('/v2/workspaces/{workspaceId}/accounts?tags=<name>'), take the ids, chunk by 200, and call POST .../accounts/bulk/warmup/enable or POST .../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-Key or /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 after Retry-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