Docs
Migrating from v1Email accounts

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.

Get one email account

Returns one account by id. Use it to check the state of a single mailbox. It replaces the old "status" endpoint.

Old APINew API
Method + routeGET /v1/email-accounts/{emailAccountId}/statusGET /v2/workspaces/{workspaceId}/accounts/{id}
Key permission (scope)any keyaccounts:read
Rate bucket20/min sharedread
Plan needed--

What changed

  • The path no longer ends in /status. The id is now {id} under the workspace.
  • It returns the full account object (see above), not the old 11-field status.
  • emailAccountId → id, fromEmail → emailAddress, healthScore → setupScore, warmupScore → deliverabilityRate (closest match).
  • type → provider. authStatus → status. connectionError has no replacement; check warmupStatus and warmupPausedReason.
  • warmupStatus values changed (RUNNING, PAUSED, ...).

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
idpathnumberyes-The account id.emailAccountId

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/57/accounts/4821" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X GET "https://lupus-edge.trulyinbox.com/v1/email-accounts/4821/status" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new)

200 OK. data is the account object (see above).

{
  "data": {
    "id": 4821,
    "emailAddress": "jane@acme.com",
    "senderName": "Jane Cooper",
    "provider": "GOOGLE_WORKSPACE",
    "status": "CONNECTED",
    "warmupStatus": "PAUSED",
    "warmupPausedReason": "AUTH_FAILED",
    "setupScore": 100,
    "deliverabilityRate": 96.4,
    "replyRate": 30,
    "warmupCurrentLimit": 18,
    "warmupMaxLimit": 40,
    "warmupStartDate": "2026-09-19T09:00:00.000Z",
    "warmupPreference": "AUTO",
    "todaySent": 0,
    "todayReceived": 0,
    "sevenDaySent": 81,
    "sevenDayReceived": 77,
    "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" },
    "mxRecordData": { "isValid": true, "mxRecords": [{ "exchange": "smtp.google.com", "priority": 1 }] },
    "blacklistedAt": null,
    "blacklistSource": null,
    "contentIndustry": "Software",
    "contentTopics": ["product updates"],
    "contentLanguage": "English",
    "tags": [{ "id": 12, "name": "Q3-outreach" }],
    "createdAt": "2026-09-18T14:03:10.000Z"
  },
  "meta": {
    "request_id": "req_1c9a7e0b-52d4-4f0e-8a61-3e2b9d7c4f10",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

(The warmupPausedReason value above is an illustration.)

Response (old)

{
  "emailAccountId": 4821,
  "fromEmail": "jane@acme.com",
  "type": "gmail",
  "authStatus": "auth_expired",
  "warmupStatus": "blocked",
  "healthScore": null,
  "warmupScore": 92,
  "outreachReadinessStatus": "readyForOutreach",
  "connectionError": null,
  "lastConnectedAt": null,
  "workspaceId": null
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestid is not a number.Send a numeric id.
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.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace.Check the id and the workspace.
429rate_limit_exceededRead bucket used up.Wait error.retry_after seconds, then retry.

Account overview

New endpoint. Returns the account plus 14 days of daily numbers in one call. Use it for an account detail page. For the domain security breakdown, call DNS records.

Old APINew API
Method + routenone - newGET /v2/workspaces/{workspaceId}/accounts/{id}/overview
Key permission (scope)-accounts:read
Rate bucket-read
Plan needed--

What changed

  • New. The old API needed several calls (status, setup score, DNS health, reports) for the same data.
  • data.account is the account object (see above). The other keys are new.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
idpathnumberyes-The account id.-

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/57/accounts/4821/overview" \
  -H "Authorization: Bearer ti_ws_your_key"

Response (new)

200 OK.

New field (inside data)TypeWhat it meansOld field
accountaccount objectThe account. See "The account object".-
last14Daysobject[]One row per day for the last 14 days. Days with no traffic are filled with zeros.-
last14Days[].datestringDay, YYYY-MM-DD (UTC).-
last14Days[].sentnumberOriginal warmup emails sent that day. Replies and forwards this mailbox sent are not counted.-
last14Days[].deliverednumberOf that day's original sends, how many were delivered.-
last14Days[].openednumberOf that day's original sends, how many were opened.-
last14Days[].repliednumberReplies this mailbox received to that day's sends, thread replies included. Replies it sent are not counted.-
{
  "data": {
    "account": { "id": 4821, "emailAddress": "jane@acme.com", "setupScore": 82, "warmupCurrentLimit": 18 },
    "last14Days": [
      { "date": "2026-09-28", "sent": 17, "delivered": 17, "opened": 12, "replied": 5 },
      { "date": "2026-09-29", "sent": 11, "delivered": 11, "opened": 6, "replied": 2 }
    ]
  },
  "meta": {
    "request_id": "req_8d2f4a10-7b3c-4e9d-a1f2-6c5b4e3d2a19",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

(Shortened: account holds every field of the account object.)

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
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.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace.Check the id and the workspace.
429rate_limit_exceededRead bucket used up.Wait error.retry_after seconds, then retry.

Connect an SMTP/IMAP mailbox

Connects a mailbox with an SMTP/IMAP login (custom mail server, Zoho, Yahoo, SendGrid and similar). TrulyInbox tests both servers before it saves anything.

Old APINew API
Method + routePOST /v1/email-accountsPOST /v2/workspaces/{workspaceId}/accounts
Key permission (scope)any keyaccounts:write (key owner needs editor role or higher)
Rate bucket20/min sharedwrite
Plan needed-- (the plan's mailbox limit applies)

What changed

  • The body is flat. There are no smtp and imap objects any more.
  • smtp.emailAddress → emailAddress. smtp.userName → smtpUsername, and it is now REQUIRED. Send the mailbox address if the server logs in with it.
  • Encryption is a word, not true/false: smtpEncryption and imapEncryption take "SSL", "TLS" or "NONE".
  • One password for SMTP. imapPassword is optional and falls back to password. imapUsername is optional and falls back to smtpUsername.
  • emailServiceProvider (required) → espPresetId (optional). fromName → senderName.
  • The response is the full account object (status 201), not { emailAccountId, fromEmail, fromName, type, status }. TrulyInbox also tries to turn on warmup right after connecting. The old API never did. It starts sending once the DNS and send/receive checks pass.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Workspace to add the mailbox to.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
emailAddressstringyesvalid emailThe mailbox address.smtp.emailAddress
senderNamestringno-Name shown as the sender.fromName
smtpHoststringyes-SMTP server host.smtp.host
smtpPortnumberyeswhole number, 1 to 65535SMTP port (often 587 or 465).smtp.port
smtpEncryptionstringyesSSL, TLS, NONESMTP encryption.smtp.encryption (true/false)
smtpUsernamestringyes-SMTP login name.smtp.userName (was optional)
passwordstringyes-SMTP password or app password. Stored encrypted.smtp.password
imapHoststringyes-IMAP server host.imap.host
imapPortnumberyeswhole number, 1 to 65535IMAP port (often 993).imap.port
imapEncryptionstringyesSSL, TLS, NONEIMAP encryption.imap.encryption (true/false)
imapUsernamestringnodefaults to smtpUsernameIMAP login name, if different.imap.emailAddress
imapPasswordstringnodefaults to passwordIMAP password, if different. Set it when sending and reading use different services (for example SendGrid for sending plus a real mailbox for replies).imap.password (was required)
espPresetIdstringnogmail, yahoo, zoho, sendgrid, mailgun, amazon-ses, elastic-email, yandex, godaddyKnown provider this mailbox uses. Leave it out for a custom server. If the address clearly belongs to a different provider, the call is rejected.emailServiceProvider (was required)
displayNamestringno-Old alias of senderName. Ignored when senderName is sent. Do not use in new code.-

Old emailServiceProvider values with no preset (other, gsuite, azure, mailjet): leave espPresetId out.

Example request (new)

curl -X POST "$TI_BASE_URL/v2/workspaces/57/accounts" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "jane@acme.com",
    "senderName": "Jane Cooper",
    "smtpHost": "smtp.zoho.com",
    "smtpPort": 587,
    "smtpEncryption": "TLS",
    "smtpUsername": "jane@acme.com",
    "password": "app-password-here",
    "imapHost": "imap.zoho.com",
    "imapPort": 993,
    "imapEncryption": "SSL",
    "espPresetId": "zoho"
  }'

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/email-accounts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromName": "Jane Cooper",
    "emailServiceProvider": "zoho",
    "smtp": { "emailAddress": "jane@acme.com", "host": "smtp.zoho.com", "port": 587, "password": "app-password-here", "encryption": true },
    "imap": { "host": "imap.zoho.com", "port": 993, "password": "app-password-here", "encryption": true }
  }'

Response (new)

201 Created. data is the account object (see above). Shortened example:

{
  "data": {
    "id": 4907,
    "emailAddress": "jane@acme.com",
    "senderName": "Jane Cooper",
    "provider": "ZOHO",
    "status": "CONNECTED",
    "warmupStatus": "PENDING",
    "setupScore": null,
    "warmupCurrentLimit": 0,
    "warmupMaxLimit": 20,
    "tags": [],
    "createdAt": "2026-09-29T10:00:00.000Z"
  },
  "meta": {
    "request_id": "req_3e7b9c21-0a4f-4d6e-b8c3-2f1e0d9c8b7a",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "emailAccountId": 4907,
  "fromEmail": "jane@acme.com",
  "fromName": "Jane Cooper",
  "type": "smtp-imap",
  "status": "active"
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestA field is missing or wrong. Or TrulyInbox could not log in to the SMTP or IMAP server. Or the address does not match the chosen espPresetId. Or the host is not allowed.Read error.message, fix the settings, try again. Do not retry unchanged.
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeThe key lacks accounts:write.Add the scope to the key.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403forbiddenThe key owner is only a viewer in this workspace, or the email domain is blocked.Use a key from an editor, or use another mailbox.
403plan_limit_reachedThe plan's mailbox limit is full.Upgrade, or delete a mailbox first.
403subscription_pausedThe subscription is paused. No mailbox can be connected.Resume the subscription.
409conflictThis email address is already connected in TrulyInbox.Find it with GET /v2/workspaces/{workspaceId}/accounts?q=<email> instead.
429rate_limit_exceededWrite bucket used up.Wait error.retry_after seconds, then retry.