Email accounts
Move email account calls from /v1/email-accounts to /v2: list, get, connect, disconnect, delete and bulk status.
These endpoints list, read, connect, disconnect and delete the mailboxes (email accounts) in one TrulyInbox workspace.
The account object
List, get one, both connect calls, disconnect, set tags, bulk-status and the account overview all return the same account object. In the new API it sits inside data (or inside data[] for the list). The old API had three different, smaller shapes for this. The table below is the full new object. The other sections link back here instead of repeating it.
Important rules before you map fields:
- Old
status,authStatusandwarmupStatusdo not map one-to-one to new values. Usestatusfor "is the mailbox connected" andwarmupStatus(withwarmupPausedReason) for "is it warming". - New status values can be added at any time. Treat any value you do not know as "not handled yet". Do not crash on it.
nullusually means "not known yet" or "never checked". It does not mean0or "failed".
| New field | Type | What it means | Old field |
|---|---|---|---|
id | number | The account id. Use it in every /accounts/{id} path. | id (list), emailAccountId (status, connect, bulk-status) |
emailAddress | string | The mailbox address. | fromEmail |
senderName | string or null | The name shown as the sender. null means not set (this lowers the setup score). | fromName |
provider | string | The ESP (email provider like Gmail or Outlook). One of GMAIL, GOOGLE_WORKSPACE, OUTLOOK, MS365, SMTP, ZOHO, YAHOO, SENDGRID, MAILGUN, AMAZON_SES, ELASTIC_EMAIL, YANDEX, GODADDY. The last eight are SMTP mailboxes matched to a known provider. | type (gmail, microsoft, smtp-imap) |
status | string | Connection flag: CONNECTED or DISCONNECTED. | authStatus (connected, auth_expired) - no 1:1 match |
warmupStatus | string | Warmup state: PENDING, RUNNING, THROTTLED, MAINTENANCE, PAUSED. | warmupStatus (active, paused, stopped, blocked) - values changed |
warmupPausedReason | string or null | A code for why warmup is paused or suspended, for example HARD_BOUNCE. null when warmup is not paused. | none (new) |
warmupMaxLimit | number | Highest daily warmup sends you allow. Warmup climbs toward this number. | maxSendingLimit (warmup settings) |
warmupCurrentLimit | number | Daily sending limit in force today. | dailySendingLimit (warmup settings) |
deliverabilityRate | number or null | Share of warmup emails that landed in the inbox, 0 to 100. null means no score yet. | warmupScore (closest match, not the same formula) |
spfData | object or null | Stored SPF record: { isValid, spfResults }. null means never checked. It does not mean "missing". | none (new) |
dkimData | object or null | Stored DKIM record: { isValid, dkimRecord, selector, ... }. null means never checked. | none (new) |
dmarcData | object or null | Stored DMARC record: { isValid, dmarcResults }. null means never checked. | none (new) |
mxRecordData | object or null | Stored MX records: { isValid, mxRecords }. null means never checked. | none (new) |
setupScore | number or null | Setup score, 0 to 100 (SPF, DKIM, DMARC, MX and blacklist checks). null means never scored. It is not the same as 0. | healthScore |
createdAt | string (date-time) | When the account was connected. | createdAt (list only) |
warmupStartDate | string (date-time) or null | When warmup first started. null if warmup never started. | none (new) |
replyRate | number | Target reply rate in percent. This is a setting, not a measured result. | replyRate (warmup settings) |
warmupPreference | string | ESP mix mode: AUTO or CUSTOM. | none (new) |
contentIndustry | string or null | Industry used to write warmup emails. | part of upcomingContentConfig (warmup settings) |
contentTopics | string[] | Topics used to write warmup emails. May be null when none are set. | part of upcomingContentConfig (warmup settings) |
contentLanguage | string | Language of warmup emails. | warmupLanguage (warmup settings) |
blacklistedAt | string (date-time) or null | When the domain or IP was found on a blacklist. null if not listed. | none (new) |
blacklistSource | string or null | Which blacklist listed the domain. | none (new) |
todaySent | number | Warmup emails sent today. 0 when there is no traffic. | none (new) |
todayReceived | number | Warmup emails received today. | none (new) |
sevenDaySent | number | Warmup emails sent in the last 7 days. | none (new) |
sevenDayReceived | number | Warmup emails received in the last 7 days. | none (new) |
tags | object[] | Tags on this account. Each tag is { id, name }. | tags (list of name strings) |
Old fields with no new field:
outreachReadinessStatus- there is no field. Use the list filteroutreachReadiness(ready,warming,not_ready) instead.warmupScore- usedeliverabilityRate, or the analytics endpoints.workspaceId- the TrulyInbox workspace is now in the URL.
Example account object (this is what data holds for a single account):
{
"id": 4821,
"emailAddress": "jane@acme.com",
"senderName": "Jane Cooper",
"provider": "GOOGLE_WORKSPACE",
"status": "CONNECTED",
"warmupStatus": "RUNNING",
"warmupPausedReason": null,
"setupScore": 100,
"deliverabilityRate": 96.4,
"replyRate": 30,
"warmupCurrentLimit": 18,
"warmupMaxLimit": 40,
"warmupStartDate": "2026-09-19T09:00:00.000Z",
"warmupPreference": "AUTO",
"todaySent": 11,
"todayReceived": 9,
"sevenDaySent": 104,
"sevenDayReceived": 97,
"spfData": {
"isValid": true,
"spfResults": "v=spf1 include:_spf.google.com ~all"
},
"dkimData": {
"isValid": true,
"dkimRecord": ["v=DKIM1; k=rsa; p=MIIBIjANBgkq..."],
"selector": "google"
},
"dmarcData": {
"isValid": true,
"dmarcResults": "v=DMARC1; p=none; rua=mailto:dmarc@acme.com"
},
"mxRecordData": {
"isValid": true,
"mxRecords": [{ "exchange": "smtp.google.com", "priority": 1 }]
},
"blacklistedAt": null,
"blacklistSource": null,
"contentIndustry": "Software",
"contentTopics": ["product updates", "customer success"],
"contentLanguage": "English",
"tags": [{ "id": 12, "name": "Q3-outreach" }],
"createdAt": "2026-09-18T14:03:10.000Z"
}List email accounts
Returns the mailboxes in a workspace, one page at a time. Call it to show your users their accounts or to find account ids.
| Old API | New API | |
|---|---|---|
| Method + route | GET /v1/email-accounts | GET /v2/workspaces/{workspaceId}/accounts |
| Key permission (scope) | any key | accounts:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
- The list is now in
data(an array). The olditems,total,page,limit,totalPagesmoved topagination(page,per_page,total,total_pages,has_more). - Paging now works: send
pageandlimit. Loop whilepagination.has_moreistrue. The old API had no paging parameters. - CAREFUL:
sortBychanged meaning. OldsortBywas the direction (ASC/DESC). NewsortByis the field, and the direction issortDir(asc/desc, lower case). searchis nowq. Thestatusfilter uses new values (see below).- Each item is the full account object (see above), not the old short item.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
page | query | number | no | default 1, min 1, max 100000 | Page number. | - |
limit | query | number | no | default 25, min 1, max 100 | Accounts per page. | - |
q | query | string | no | - | Search by email address or sender name. | search |
status | query | string, can repeat | no | all, active, throttled, paused, suspended, cooldown, maintenance, disconnected | Filter by status group. cooldown is a spam or bounce-rate suspension that resumes on its own; suspended is every other suspension. Repeat for several: ?status=paused&status=suspended. | status (active, warming, paused, error, auth-expired) |
provider | query | string, can repeat | no | all, gmail, google_workspace, outlook, ms365, smtp, zoho, ... (14 values - full list in the new docs) | Filter by provider. | - |
tags | query | string, can repeat | no | - | Tag names. Returns accounts with any of the names. | tags |
sortBy | query | string | no | default createdAt; email, status, score, createdAt | Field to sort by. score sorts by deliverability. | sort (createdAt, fromEmail, fromName) |
sortDir | query | string | no | default desc; asc, desc | Sort direction. | sortBy (ASC, DESC) |
domain | query | string | no | - | Exact email domain, case-insensitive. | - |
outreachReadiness | query | string, can repeat | no | ready, warming, not_ready | Filter by readiness for cold outreach. | outreachReadinessStatus (response field) |
esp | query | string | no | auto, custom | Filter by ESP mix mode (warmupPreference). | - |
setupScoreMin / setupScoreMax | query | number | no | 0 to 100; max must be ≥ min | Setup score range. | - |
deliverabilityMin / deliverabilityMax | query | number | no | 0 to 100; max must be ≥ min | Deliverability rate range. | - |
maxLimitMin / maxLimitMax | query | number | no | 5 to 100; max must be ≥ min | Range for warmupMaxLimit. | - |
startDateFrom / startDateTo | query | string | no | YYYY-MM-DD, inclusive; to must be ≥ from | Date the account entered the warmup pool. | - |
espGoogleMin / espGoogleMax | query | number | no | 0 to 100; max must be ≥ min | Range for the Google share of the ESP mix. | - |
espMicrosoftMin / espMicrosoftMax | query | number | no | 0 to 100; max must be ≥ min | Range for the Microsoft share. | - |
espOthersMin / espOthersMax | query | number | no | 0 to 100; max must be ≥ min | Range for the "other providers" share. | - |
Status filter mapping (no exact match): old warming → new active (plus throttled); old paused → paused; old auth-expired and error → suspended, or cooldown for a spam/bounce-rate stop that clears itself (check warmupPausedReason); old active (connected, not warming) has no group - those accounts only show with no status filter or status=all.
Request body
No body.
Example request (new)
curl -G "$TI_BASE_URL/v2/workspaces/57/accounts" \
-H "Authorization: Bearer ti_ws_your_key" \
--data-urlencode "q=acme.com" \
--data-urlencode "status=paused" \
--data-urlencode "status=suspended" \
--data-urlencode "tags=Q3-outreach" \
--data-urlencode "sortBy=email" \
--data-urlencode "sortDir=asc" \
--data-urlencode "page=1" \
--data-urlencode "limit=50"Example request (old)
curl -X GET "https://lupus-edge.trulyinbox.com/v1/email-accounts?search=acme.com&status=paused&sort=fromEmail&sortBy=ASC" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK. data is an array of account objects (see above). Paging is in pagination:
| New field | Type | What it means | Old field |
|---|---|---|---|
data[] | account object | One mailbox. See "The account object". | items[] |
pagination.page | number | Current page. | page |
pagination.per_page | number | Page size you asked for. | limit |
pagination.total | number | Accounts that match the filters. | total |
pagination.total_pages | number | Number of pages. | totalPages |
pagination.has_more | boolean | true if there is another page. | - |
Shortened example (each item has every field of the account object):
{
"data": [
{
"id": 4821,
"emailAddress": "jane@acme.com",
"senderName": "Jane Cooper",
"provider": "GOOGLE_WORKSPACE",
"status": "CONNECTED",
"warmupStatus": "PAUSED",
"setupScore": 100,
"deliverabilityRate": 96.4,
"warmupCurrentLimit": 18,
"tags": [{ "id": 12, "name": "Q3-outreach" }],
"createdAt": "2026-09-18T14:03:10.000Z"
}
],
"meta": {
"request_id": "req_6b0e2c1a-3f4d-4c55-9b7e-0d1f2a3b4c5d",
"timestamp": "2026-09-29T10:00:00.000Z"
},
"pagination": {
"page": 1,
"per_page": 50,
"total": 3,
"total_pages": 1,
"has_more": false
}
}Response (old)
{
"items": [
{
"id": 4821,
"fromEmail": "jane@acme.com",
"fromName": "Jane Cooper",
"type": "gmail",
"status": "paused",
"createdAt": "2026-09-18T14:03:10.000Z",
"warmupScore": 92,
"outreachReadinessStatus": "readyForOutreach",
"workspaceId": null,
"tags": ["Q3-outreach"]
}
],
"total": 3,
"page": 1,
"limit": 25,
"totalPages": 1
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | A filter value is not allowed, or a max is smaller than its min. | Fix the query. error.details names the field. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong or revoked. | Check the Authorization: Bearer header. |
| 403 | insufficient_scope | The key lacks accounts:read. | Add the scope to the key. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | api_access_not_in_plan | The plan does not include API access. | Upgrade the plan. |
| 403 | subscription_paused | The subscription is paused. Every call is blocked, reads too. | Resume the subscription. |
| 429 | rate_limit_exceeded | Read bucket used up. | Wait error.retry_after seconds, then retry. |
For AI assistants
A migration brief for AI coding assistants: what to change, rename tables, a reference client and recipes for removed endpoints.
Get one email account to Connect an SMTP/IMAP mailbox
Returns one account by id. Use it to check the state of a single mailbox. It replaces the old "status" endpoint.