Docs
Migrating from v1Deliverability & reports

Account stats to Report export (removed)

Returns daily warmup numbers for one mailbox, plus its current warmup state. It replaces the old single account report.

Account stats

Returns daily warmup numbers for one mailbox, plus its current warmup state. It replaces the old single account report.

Old APINew API
Method + routePOST /v1/reportsGET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats
Key permission (scope)any keyanalytics:read
Rate bucket20/min sharedread
Plan needed--

What changed

  • The method is now GET. The account id moved from the body (emailAccountId) into the path (id).
  • from and to are replaced by one days query parameter (1–30, default 30). The window always ends today. See "Turning from/to into days" below.
  • days[] (the array) is renamed dailyBreakdown[]. Do not confuse it with the new days query parameter.
  • Per day, inbox, other, undelivered, replied and the per-day deliverabilityRate are gone. spam becomes spamDetected. bounced is new.
  • New top-level fields: warmupStatus, currentLimit, deliverabilityRate.
  • The top-level deliverabilityRate is the mailbox's latest daily deliverability score (a rolling 7-day figure). It does not change with days. It is 0 when no score exists yet.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
idpathnumberyes-The email account id.emailAccountId (was in the body)
daysquerynumberno1–30, default 30How many days back from today to include.from / to (body)

Request body - No body.

Turning from/to into days

The new window is "the last days days, up to and including today". Rows are dated YYYY-MM-DD in UTC.

  1. Set days = number of days from your old from date to today (UTC).
  2. If that number is above 30, use 30. Older data is not available per account.
  3. After the call, drop rows whose date is after your old to date.

Worked example, today is 2026-09-29:

  • Old body: { "from": "2026-09-15", "to": "2026-09-22" }.
  • 2026-09-15 to 2026-09-29 is 14 days, so call ?days=14. You get rows from 2026-09-15 to 2026-09-29.
  • Keep only rows with date ≤ 2026-09-22.
const today = new Date(new Date().toISOString().slice(0, 10)); // UTC midnight
const from = new Date("2026-09-15");
const days = Math.min(30, Math.max(1, Math.round((today - from) / 86400000)));
// GET /v2/workspaces/{workspaceId}/accounts/456/analytics/stats?days=14
const rows = body.data.dailyBreakdown.filter(r => r.date >= "2026-09-15" && r.date <= "2026-09-22");

Days with no activity have no row. If you need a row for every day, fill the missing dates with zeros yourself.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/123/accounts/456/analytics/stats?days=14" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/reports" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAccountId": 456,
    "from": "2026-09-15",
    "to": "2026-09-22"
  }'

Response (new) - 200 OK

New field (inside data)TypeWhat it meansOld field
accountIdnumberThe email account id.emailAccountId
emailAddressstringThe mailbox address.-
warmupStatusstringCurrent warmup state, for example RUNNING, PAUSED, THROTTLED.-
currentLimitnumberToday's warmup sending limit.-
deliverabilityRatenumberLatest daily deliverability score (rolling 7 days), 0–100.- (old had it per day)
dailyBreakdownarrayOne row per day with activity, oldest first.days
dailyBreakdown[].datestringDay, YYYY-MM-DD.days[].date
dailyBreakdown[].sentnumberSent that day.days[].sent
dailyBreakdown[].receivednumberReceived that day.days[].received
dailyBreakdown[].bouncednumberBounced that day.- (closest: days[].undelivered)
dailyBreakdown[].spamDetectednumberLanded in spam that day.days[].spam

The old from and to echo fields are gone.

{
  "data": {
    "accountId": 456,
    "emailAddress": "jane@acme.com",
    "warmupStatus": "RUNNING",
    "currentLimit": 35,
    "deliverabilityRate": 96.5,
    "dailyBreakdown": [
      { "date": "2026-09-15", "sent": 28, "received": 26, "bounced": 0, "spamDetected": 1 },
      { "date": "2026-09-16", "sent": 30, "received": 29, "bounced": 1, "spamDetected": 0 }
    ]
  },
  "meta": {
    "request_id": "req_c3902e1d",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "emailAccountId": 456,
  "from": "2026-09-15",
  "to": "2026-09-22",
  "days": [
    {
      "date": "2026-09-15",
      "sent": 25,
      "inbox": 20,
      "received": 22,
      "spam": 3,
      "other": 2,
      "undelivered": 0,
      "replied": 5,
      "deliverabilityRate": 92.5
    }
  ]
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestdays is not a whole number from 1 to 30. Replaces the old date_range_too_large.Cap days at 30.
401unauthorized / invalid_api_keyKey missing, wrong, or revoked.Check the header and the key.
403insufficient_scopeKey does not have analytics:read.Add the scope to the key.
403workspace_forbiddenKey cannot access this workspace.Use the right workspaceId or key.
404not_foundNo email account with this id in this workspace.Check the id.
429rate_limit_exceededRead bucket is used up.Wait error.retry_after seconds, then retry.

Bulk report (removed)

The old bulk report has no single-call replacement. Call Account stats once per mailbox instead.

Old APINew API
Method + routePOST /v1/reports/bulkremoved - call GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats per account
Key permission (scope)any keyanalytics:read
Rate bucket20/min sharedread (one call per account)
Plan needed--

What changed

  • One call per mailbox. The old emailAccountIds list becomes a loop over account ids.
  • from / to become days (1–30, default 30). Use the same conversion as in Account stats.
  • An id that is not in this workspace returns 404 not_found for that call only. Log it and carry on with the rest.

Report export (removed)

The old endpoint queued a CSV report and emailed it. The new API has no export endpoint. Build the CSV yourself from Account stats.

Old APINew API
Method + routePOST /v1/reports/exportremoved
Key permission (scope)any keyanalytics:read + accounts:read (for the recipe below)
Rate bucket20/min sharedread
Plan needed--

What changed

  • No jobId, no email. You get the data straight away and write the file in your own code.
  • The old from / to range becomes days (max 30). Older per-account data is not available.
  • The old "omit emailAccountIds to export all accounts" becomes: list all account ids first, then read stats for each one.

Recipe

  1. Get all account ids: call GET /v2/workspaces/{workspaceId}/accounts?page=1&limit=100 and keep calling with the next page while pagination.has_more is true. Collect every data[].id.
  2. For each id, call GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats?days=30. These calls use the read bucket. On 429, wait error.retry_after seconds and retry the same id. On 404, log the id (it was deleted or is not in this workspace) and move on.
  3. For each response, write one CSV row per dailyBreakdown entry.
  4. If you need your old from/to range, filter rows by date as shown in Account stats.

Example CSV columns:

account_id,email_address,date,sent,received,bounced,spam_detected,warmup_status,current_limit,deliverability_rate
456,jane@acme.com,2026-09-28,34,33,0,1,RUNNING,35,96.5
456,jane@acme.com,2026-09-29,35,34,1,0,RUNNING,35,96.5
457,mark@acme.com,2026-09-28,20,19,0,2,PAUSED,20,91.2

warmup_status to deliverability_rate repeat the account-level values on every row. deliverability_rate is the account's current score, not a per-day figure. The old per-day inbox, other, undelivered and replied columns cannot be filled.

# One account (repeat for each id)
curl -X GET "$TI_BASE_URL/v2/workspaces/123/accounts/456/analytics/stats?days=30" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/reports/export" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAccountIds": ["456", "457"],
    "from": "2026-09-01",
    "to": "2026-09-29"
  }'

Response (old) - 202 Accepted

{
  "jobId": "a1b2c3d4",
  "status": "queued"
}

Errors you should handle - see Account stats and the list accounts endpoint. The old date_range_too_large has no equivalent; cap days at 30 instead.