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 API | New API | |
|---|---|---|
| Method + route | POST /v1/reports | GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats |
| Key permission (scope) | any key | analytics:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
- The method is now
GET. The account id moved from the body (emailAccountId) into the path (id). fromandtoare replaced by onedaysquery parameter (1–30, default 30). The window always ends today. See "Turning from/to into days" below.days[](the array) is renameddailyBreakdown[]. Do not confuse it with the newdaysquery parameter.- Per day,
inbox,other,undelivered,repliedand the per-daydeliverabilityRateare gone.spambecomesspamDetected.bouncedis new. - New top-level fields:
warmupStatus,currentLimit,deliverabilityRate. - The top-level
deliverabilityRateis the mailbox's latest daily deliverability score (a rolling 7-day figure). It does not change withdays. It is 0 when no score exists yet.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
id | path | number | yes | - | The email account id. | emailAccountId (was in the body) |
days | query | number | no | 1–30, default 30 | How 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.
- Set
days= number of days from your oldfromdate to today (UTC). - If that number is above 30, use 30. Older data is not available per account.
- After the call, drop rows whose
dateis after your oldtodate.
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) | Type | What it means | Old field |
|---|---|---|---|
accountId | number | The email account id. | emailAccountId |
emailAddress | string | The mailbox address. | - |
warmupStatus | string | Current warmup state, for example RUNNING, PAUSED, THROTTLED. | - |
currentLimit | number | Today's warmup sending limit. | - |
deliverabilityRate | number | Latest daily deliverability score (rolling 7 days), 0–100. | - (old had it per day) |
dailyBreakdown | array | One row per day with activity, oldest first. | days |
dailyBreakdown[].date | string | Day, YYYY-MM-DD. | days[].date |
dailyBreakdown[].sent | number | Sent that day. | days[].sent |
dailyBreakdown[].received | number | Received that day. | days[].received |
dailyBreakdown[].bounced | number | Bounced that day. | - (closest: days[].undelivered) |
dailyBreakdown[].spamDetected | number | Landed 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | days is not a whole number from 1 to 30. Replaces the old date_range_too_large. | Cap days at 30. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong, or revoked. | Check the header and the key. |
| 403 | insufficient_scope | Key does not have analytics:read. | Add the scope to the key. |
| 403 | workspace_forbidden | Key cannot access this workspace. | Use the right workspaceId or key. |
| 404 | not_found | No email account with this id in this workspace. | Check the id. |
| 429 | rate_limit_exceeded | Read 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 API | New API | |
|---|---|---|
| Method + route | POST /v1/reports/bulk | removed - call GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats per account |
| Key permission (scope) | any key | analytics:read |
| Rate bucket | 20/min shared | read (one call per account) |
| Plan needed | - | - |
What changed
- One call per mailbox. The old
emailAccountIdslist becomes a loop over account ids. from/tobecomedays(1–30, default 30). Use the same conversion as in Account stats.- An id that is not in this workspace returns
404 not_foundfor 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 API | New API | |
|---|---|---|
| Method + route | POST /v1/reports/export | removed |
| Key permission (scope) | any key | analytics:read + accounts:read (for the recipe below) |
| Rate bucket | 20/min shared | read |
| 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/torange becomesdays(max 30). Older per-account data is not available. - The old "omit
emailAccountIdsto export all accounts" becomes: list all account ids first, then read stats for each one.
Recipe
- Get all account ids: call
GET /v2/workspaces/{workspaceId}/accounts?page=1&limit=100and keep calling with the nextpagewhilepagination.has_moreistrue. Collect everydata[].id. - For each id, call
GET /v2/workspaces/{workspaceId}/accounts/{id}/analytics/stats?days=30. These calls use the read bucket. On 429, waiterror.retry_afterseconds and retry the same id. On 404, log the id (it was deleted or is not in this workspace) and move on. - For each response, write one CSV row per
dailyBreakdownentry. - If you need your old
from/torange, filter rows bydateas 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.2warmup_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.
DNS records to Account deliverability
Returns the stored SPF, DKIM, DMARC and MX records for the mailbox's domain, with the blacklist results and a score per check. Use it for a detailed domain health screen.
Workspaces, members & budgets
New in /v2: TrulyInbox workspaces, team members and daily warmup budgets.