Docs
Migrating from v1Email accounts

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, authStatus and warmupStatus do not map one-to-one to new values. Use status for "is the mailbox connected" and warmupStatus (with warmupPausedReason) 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.
  • null usually means "not known yet" or "never checked". It does not mean 0 or "failed".
New fieldTypeWhat it meansOld field
idnumberThe account id. Use it in every /accounts/{id} path.id (list), emailAccountId (status, connect, bulk-status)
emailAddressstringThe mailbox address.fromEmail
senderNamestring or nullThe name shown as the sender. null means not set (this lowers the setup score).fromName
providerstringThe 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)
statusstringConnection flag: CONNECTED or DISCONNECTED.authStatus (connected, auth_expired) - no 1:1 match
warmupStatusstringWarmup state: PENDING, RUNNING, THROTTLED, MAINTENANCE, PAUSED.warmupStatus (active, paused, stopped, blocked) - values changed
warmupPausedReasonstring or nullA code for why warmup is paused or suspended, for example HARD_BOUNCE. null when warmup is not paused.none (new)
warmupMaxLimitnumberHighest daily warmup sends you allow. Warmup climbs toward this number.maxSendingLimit (warmup settings)
warmupCurrentLimitnumberDaily sending limit in force today.dailySendingLimit (warmup settings)
deliverabilityRatenumber or nullShare of warmup emails that landed in the inbox, 0 to 100. null means no score yet.warmupScore (closest match, not the same formula)
spfDataobject or nullStored SPF record: { isValid, spfResults }. null means never checked. It does not mean "missing".none (new)
dkimDataobject or nullStored DKIM record: { isValid, dkimRecord, selector, ... }. null means never checked.none (new)
dmarcDataobject or nullStored DMARC record: { isValid, dmarcResults }. null means never checked.none (new)
mxRecordDataobject or nullStored MX records: { isValid, mxRecords }. null means never checked.none (new)
setupScorenumber or nullSetup score, 0 to 100 (SPF, DKIM, DMARC, MX and blacklist checks). null means never scored. It is not the same as 0.healthScore
createdAtstring (date-time)When the account was connected.createdAt (list only)
warmupStartDatestring (date-time) or nullWhen warmup first started. null if warmup never started.none (new)
replyRatenumberTarget reply rate in percent. This is a setting, not a measured result.replyRate (warmup settings)
warmupPreferencestringESP mix mode: AUTO or CUSTOM.none (new)
contentIndustrystring or nullIndustry used to write warmup emails.part of upcomingContentConfig (warmup settings)
contentTopicsstring[]Topics used to write warmup emails. May be null when none are set.part of upcomingContentConfig (warmup settings)
contentLanguagestringLanguage of warmup emails.warmupLanguage (warmup settings)
blacklistedAtstring (date-time) or nullWhen the domain or IP was found on a blacklist. null if not listed.none (new)
blacklistSourcestring or nullWhich blacklist listed the domain.none (new)
todaySentnumberWarmup emails sent today. 0 when there is no traffic.none (new)
todayReceivednumberWarmup emails received today.none (new)
sevenDaySentnumberWarmup emails sent in the last 7 days.none (new)
sevenDayReceivednumberWarmup emails received in the last 7 days.none (new)
tagsobject[]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 filter outreachReadiness (ready, warming, not_ready) instead.
  • warmupScore - use deliverabilityRate, 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 APINew API
Method + routeGET /v1/email-accountsGET /v2/workspaces/{workspaceId}/accounts
Key permission (scope)any keyaccounts:read
Rate bucket20/min sharedread
Plan needed--

What changed

  • The list is now in data (an array). The old items, total, page, limit, totalPages moved to pagination (page, per_page, total, total_pages, has_more).
  • Paging now works: send page and limit. Loop while pagination.has_more is true. The old API had no paging parameters.
  • CAREFUL: sortBy changed meaning. Old sortBy was the direction (ASC/DESC). New sortBy is the field, and the direction is sortDir (asc/desc, lower case).
  • search is now q. The status filter uses new values (see below).
  • Each item is the full account object (see above), not the old short item.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
pagequerynumbernodefault 1, min 1, max 100000Page number.-
limitquerynumbernodefault 25, min 1, max 100Accounts per page.-
qquerystringno-Search by email address or sender name.search
statusquerystring, can repeatnoall, active, throttled, paused, suspended, cooldown, maintenance, disconnectedFilter 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)
providerquerystring, can repeatnoall, gmail, google_workspace, outlook, ms365, smtp, zoho, ... (14 values - full list in the new docs)Filter by provider.-
tagsquerystring, can repeatno-Tag names. Returns accounts with any of the names.tags
sortByquerystringnodefault createdAt; email, status, score, createdAtField to sort by. score sorts by deliverability.sort (createdAt, fromEmail, fromName)
sortDirquerystringnodefault desc; asc, descSort direction.sortBy (ASC, DESC)
domainquerystringno-Exact email domain, case-insensitive.-
outreachReadinessquerystring, can repeatnoready, warming, not_readyFilter by readiness for cold outreach.outreachReadinessStatus (response field)
espquerystringnoauto, customFilter by ESP mix mode (warmupPreference).-
setupScoreMin / setupScoreMaxquerynumberno0 to 100; max must be ≥ minSetup score range.-
deliverabilityMin / deliverabilityMaxquerynumberno0 to 100; max must be ≥ minDeliverability rate range.-
maxLimitMin / maxLimitMaxquerynumberno5 to 100; max must be ≥ minRange for warmupMaxLimit.-
startDateFrom / startDateToquerystringnoYYYY-MM-DD, inclusive; to must be ≥ fromDate the account entered the warmup pool.-
espGoogleMin / espGoogleMaxquerynumberno0 to 100; max must be ≥ minRange for the Google share of the ESP mix.-
espMicrosoftMin / espMicrosoftMaxquerynumberno0 to 100; max must be ≥ minRange for the Microsoft share.-
espOthersMin / espOthersMaxquerynumberno0 to 100; max must be ≥ minRange 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 fieldTypeWhat it meansOld field
data[]account objectOne mailbox. See "The account object".items[]
pagination.pagenumberCurrent page.page
pagination.per_pagenumberPage size you asked for.limit
pagination.totalnumberAccounts that match the filters.total
pagination.total_pagesnumberNumber of pages.totalPages
pagination.has_morebooleantrue 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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestA filter value is not allowed, or a max is smaller than its min.Fix the query. error.details names the field.
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeThe key lacks accounts:read.Add the scope to the key.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403api_access_not_in_planThe plan does not include API access.Upgrade the plan.
403subscription_pausedThe subscription is paused. Every call is blocked, reads too.Resume the subscription.
429rate_limit_exceededRead bucket used up.Wait error.retry_after seconds, then retry.