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 API | New API | |
|---|---|---|
| Method + route | GET /v1/email-accounts/{emailAccountId}/status | GET /v2/workspaces/{workspaceId}/accounts/{id} |
| Key permission (scope) | any key | accounts:read |
| Rate bucket | 20/min shared | read |
| 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.connectionErrorhas no replacement; checkwarmupStatusandwarmupPausedReason.warmupStatusvalues changed (RUNNING,PAUSED, ...).
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 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | id is not a number. | Send a numeric id. |
| 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 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 404 | not_found | No account with this id in this workspace. | Check the id and the workspace. |
| 429 | rate_limit_exceeded | Read 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 API | New API | |
|---|---|---|
| Method + route | none - new | GET /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.accountis the account object (see above). The other keys are new.
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 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) | Type | What it means | Old field |
|---|---|---|---|
account | account object | The account. See "The account object". | - |
last14Days | object[] | One row per day for the last 14 days. Days with no traffic are filled with zeros. | - |
last14Days[].date | string | Day, YYYY-MM-DD (UTC). | - |
last14Days[].sent | number | Original warmup emails sent that day. Replies and forwards this mailbox sent are not counted. | - |
last14Days[].delivered | number | Of that day's original sends, how many were delivered. | - |
last14Days[].opened | number | Of that day's original sends, how many were opened. | - |
last14Days[].replied | number | Replies 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 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 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 404 | not_found | No account with this id in this workspace. | Check the id and the workspace. |
| 429 | rate_limit_exceeded | Read 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 API | New API | |
|---|---|---|
| Method + route | POST /v1/email-accounts | POST /v2/workspaces/{workspaceId}/accounts |
| Key permission (scope) | any key | accounts:write (key owner needs editor role or higher) |
| Rate bucket | 20/min shared | write |
| Plan needed | - | - (the plan's mailbox limit applies) |
What changed
- The body is flat. There are no
smtpandimapobjects 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:
smtpEncryptionandimapEncryptiontake"SSL","TLS"or"NONE". - One
passwordfor SMTP.imapPasswordis optional and falls back topassword.imapUsernameis optional and falls back tosmtpUsername. 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
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Workspace to add the mailbox to. | - |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
emailAddress | string | yes | valid email | The mailbox address. | smtp.emailAddress |
senderName | string | no | - | Name shown as the sender. | fromName |
smtpHost | string | yes | - | SMTP server host. | smtp.host |
smtpPort | number | yes | whole number, 1 to 65535 | SMTP port (often 587 or 465). | smtp.port |
smtpEncryption | string | yes | SSL, TLS, NONE | SMTP encryption. | smtp.encryption (true/false) |
smtpUsername | string | yes | - | SMTP login name. | smtp.userName (was optional) |
password | string | yes | - | SMTP password or app password. Stored encrypted. | smtp.password |
imapHost | string | yes | - | IMAP server host. | imap.host |
imapPort | number | yes | whole number, 1 to 65535 | IMAP port (often 993). | imap.port |
imapEncryption | string | yes | SSL, TLS, NONE | IMAP encryption. | imap.encryption (true/false) |
imapUsername | string | no | defaults to smtpUsername | IMAP login name, if different. | imap.emailAddress |
imapPassword | string | no | defaults to password | IMAP 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) |
espPresetId | string | no | gmail, yahoo, zoho, sendgrid, mailgun, amazon-ses, elastic-email, yandex, godaddy | Known 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) |
displayName | string | no | - | 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | A 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. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong or revoked. | Check the Authorization: Bearer header. |
| 403 | insufficient_scope | The key lacks accounts:write. | Add the scope to the key. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | forbidden | The 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. |
| 403 | plan_limit_reached | The plan's mailbox limit is full. | Upgrade, or delete a mailbox first. |
| 403 | subscription_paused | The subscription is paused. No mailbox can be connected. | Resume the subscription. |
| 409 | conflict | This email address is already connected in TrulyInbox. | Find it with GET /v2/workspaces/{workspaceId}/accounts?q=<email> instead. |
| 429 | rate_limit_exceeded | Write bucket used up. | Wait error.retry_after seconds, then retry. |
Email accounts
Move email account calls from /v1/email-accounts to /v2: list, get, connect, disconnect, delete and bulk status.
Get an OAuth consent link to Disconnect an account
Returns a link that a person opens in a browser to connect a Gmail, Google Workspace, Outlook or Microsoft 365 mailbox. The mailbox is connected after they a...