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...
Get an OAuth consent link
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 approve access. It is not connected by this API call.
| Old API | New API | |
|---|---|---|
| Method + route | POST /v1/email-accounts/oauth (always returned 501 not_implemented) | POST /v2/workspaces/{workspaceId}/accounts/oauth-url |
| Key permission (scope) | any key | accounts:write (key owner needs editor role or higher) |
| Rate bucket | 20/min shared | write |
| Plan needed | - | - |
What changed
- The old endpoint was "coming soon" and never worked. The new one works, but it returns a link, not an account.
- Send
provider. You get back{ provider, url }. - A person must open
url, sign in and approve. After that, find the new account withGET /v2/workspaces/{workspaceId}/accounts?q=<email>. - The link is tied to the workspace in the path. The mailbox is added to that workspace.
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 |
|---|---|---|---|---|---|
provider | string | yes | gmail, google_workspace, outlook, ms365 | Which sign-in screen to open. outlook is a personal Microsoft account; ms365 is a work account. | - |
Example request (new)
curl -X POST "$TI_BASE_URL/v2/workspaces/57/accounts/oauth-url" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{ "provider": "google_workspace" }'Example request (old)
curl -X POST "https://lupus-edge.trulyinbox.com/v1/email-accounts/oauth" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
provider | string | The provider you asked for. | - |
url | string | Single-use consent link. Open it in a browser. | - |
{
"data": {
"provider": "google_workspace",
"url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=..."
},
"meta": {
"request_id": "req_5a1d3f7c-9e2b-4c80-b6d4-7f3a2e1c0b9d",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Response (old)
The old endpoint returned 501 with error_code not_implemented. No success response existed.
Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | provider is missing or not one of the four values. | Send a valid provider. |
| 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. | Use a key from an editor. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 429 | rate_limit_exceeded | Write bucket used up. | Wait error.retry_after seconds, then retry. |
Connect an OAuth mailbox with your own token (partners only)
New endpoint for TrulyInbox partners. A partner runs its own Google or Microsoft consent screen and sends TrulyInbox a live access token. TrulyInbox connects the mailbox without a browser. If you are not a registered partner, use "Get an OAuth consent link" instead.
| Old API | New API | |
|---|---|---|
| Method + route | none - new (the old POST /v1/email-accounts/oauth planned this but returned 501) | POST /v2/workspaces/{workspaceId}/accounts/oauth |
| Key permission (scope) | - | accounts:write (key owner needs editor role or higher) |
| Rate bucket | - | write |
| Plan needed | - | Your organization must have a verified partner callback (Settings → API keys). Without it every call fails with partner_not_configured. |
What changed
- New. It only works after you register and verify your partner callback endpoints.
- Send an access token only. There is no refresh token field. TrulyInbox calls your refresh callback when it needs a new token.
- TrulyInbox asks the provider which mailbox the token opens. If it is not
emailAddress, the call fails withemail_mismatch. - Warmup starts by itself once DNS and the send/receive check pass (within your plan's limit). You do not need to call
warmup/enable. - Calling it again for a mailbox your integration already connected in the same workspace updates the token. It does not create a duplicate. Use this to recover an account stuck in
SUSPENDED_AUTH.
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 |
|---|---|---|---|---|---|
provider | string | yes | gmail, google_workspace, outlook, ms365 | Who issued the token. | - |
emailAddress | string | yes | valid email, max 255 characters | The mailbox the token opens. Checked against the provider. | - |
accessToken | string | yes | 1 to 4096 characters | A live provider access token. | - |
expiresAt | string | yes | ISO 8601 UTC, at least 5 minutes in the future | When the token expires. | - |
senderName | string | no | max 255 characters | Name shown as the sender. Without it the setup score is lower. | - |
displayName | string | no | max 255 characters | Old alias of senderName. Ignored when senderName is sent. | - |
Example request (new)
curl -X POST "$TI_BASE_URL/v2/workspaces/57/accounts/oauth" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{
"provider": "gmail",
"emailAddress": "jane@acme.com",
"accessToken": "ya29.a0AfH6SMBx...",
"expiresAt": "2026-09-29T11:00:00.000Z",
"senderName": "Jane Cooper"
}'Response (new)
201 Created. data is the account object (see above). Shortened example:
{
"data": {
"id": 4912,
"emailAddress": "jane@acme.com",
"senderName": "Jane Cooper",
"provider": "GMAIL",
"status": "CONNECTED",
"tags": [],
"createdAt": "2026-09-29T10:00:00.000Z"
},
"meta": {
"request_id": "req_0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | A field is missing or wrong, the provider is not supported for this flow, or expiresAt is less than 5 minutes away. | Fix the body. Send a fresher token. |
| 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 | partner_not_configured | Your organization has no verified partner callback. | Register and verify it under Settings → API keys, or use oauth-url. |
| 403 | plan_limit_reached | The plan's mailbox limit is full. | Upgrade, or delete a mailbox first. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 409 | conflict | The address is already connected another way, by another partner, or in another workspace. | Do not retry. Find the existing account. |
| 422 | email_mismatch | The token belongs to a different mailbox than emailAddress. | Send the token for the right mailbox. |
| 429 | rate_limit_exceeded | Write bucket used up. | Wait error.retry_after seconds, then retry. |
Microsoft single-mailbox consent link
Returns a single-use link that connects one Microsoft mailbox. Send the link to the mailbox owner. It only works if they sign in as the address you gave.
| Old API | New API | |
|---|---|---|
| Method + route | GET /v1/email-accounts/microsoft/consent-url | GET /v2/workspaces/{workspaceId}/accounts/microsoft/consent-url |
| Key permission (scope) | any key | accounts:write (key owner needs editor role or higher) - note: a write scope on a GET |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
- Only the path moved (now under the workspace). The
emailquery and the{ url, expiresAt }result are the same, now insidedata. - Your key needs
accounts:write, even though this is a GET. - After consent, the browser lands on a result page with
partnerConnectStatus(andpartnerConnectReasonon failure) in the URL. The old flow showed a message on the TrulyInbox homepage. - Warmup now turns on by itself for the new account (within your plan's limit). The old flow did not start warmup.
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. | - |
email | query | string | yes | valid email | The mailbox to connect. The Microsoft sign-in must match this address. It also pre-fills the sign-in screen. | email |
Request body
No body.
Example request (new)
curl -G "$TI_BASE_URL/v2/workspaces/57/accounts/microsoft/consent-url" \
-H "Authorization: Bearer ti_ws_your_key" \
--data-urlencode "email=alice@company.com"Example request (old)
curl -X GET "https://lupus-edge.trulyinbox.com/v1/email-accounts/microsoft/consent-url?email=alice%40company.com" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
url | string | Single-use consent link. Send it to the mailbox owner. | url |
expiresAt | string (date-time) | The link stops working at this time (30 minutes after creation). | expiresAt |
{
"data": {
"url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&login_hint=alice%40company.com&state=...",
"expiresAt": "2026-09-29T10:30:00.000Z"
},
"meta": {
"request_id": "req_9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Then poll GET /v2/workspaces/{workspaceId}/accounts?q=alice@company.com to confirm the mailbox was added.
Response (old)
{
"url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...&state=...",
"expiresAt": "2026-08-13T12:30:00.000Z"
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | email is missing or not a valid address. | Send a valid email. |
| 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. | Use a key from an editor. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 429 | rate_limit_exceeded | Read bucket used up. | Wait error.retry_after seconds, then retry. |
| 503 | internal_error | Microsoft connect is not set up on the TrulyInbox side. | Contact support@trulyinbox.com. |
Check status of many accounts
Returns up to 50 accounts in one call. Use it to refresh a dashboard without one call per account.
| Old API | New API | |
|---|---|---|
| Method + route | POST /v1/email-accounts/bulk-status | POST /v2/workspaces/{workspaceId}/accounts/bulk-status |
| Key permission (scope) | any key | accounts:read |
| Rate bucket | 20/min shared | bulk |
| Plan needed | - | - |
What changed
- Body field
emailAccountIds→accountIds. Still max 50. Duplicate ids are now rejected. - Response
results→data.accounts. Each item is the full account object (see above), not the old status item. - Unknown ids no longer fail the whole call. They are listed in
data.notFound. - It uses the
bulkrate bucket, which is smaller thanread.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
accountIds | number[] | yes | 1 to 50 ids, whole numbers ≥ 1, no duplicates | Accounts to read. | emailAccountIds |
Example request (new)
curl -X POST "$TI_BASE_URL/v2/workspaces/57/accounts/bulk-status" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{ "accountIds": [4821, 4907, 9999] }'Example request (old)
curl -X POST "https://lupus-edge.trulyinbox.com/v1/email-accounts/bulk-status" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "emailAccountIds": [4821, 4907] }'Response (new)
200 OK.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
accounts | account object[] | Accounts found, in the order you asked. See "The account object". | results |
notFound | number[] | Ids that do not exist in this workspace. | - (old returned 400 invalid_email_account_ids) |
Shortened example (each item has every field of the account object):
{
"data": {
"accounts": [
{ "id": 4821, "emailAddress": "jane@acme.com", "warmupStatus": "RUNNING", "setupScore": 100 },
{ "id": 4907, "emailAddress": "sales@acme.com", "warmupStatus": "PAUSED", "setupScore": 82 }
],
"notFound": [9999]
},
"meta": {
"request_id": "req_2d4f6a8c-0e1b-4c3d-9f5a-7b6c8d0e2f41",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Response (old)
{
"results": [
{
"emailAccountId": 4821,
"fromEmail": "jane@acme.com",
"type": "gmail",
"authStatus": "connected",
"warmupStatus": "active",
"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 | accountIds is empty, has more than 50 ids, has duplicates, or has a non-number. | Fix the list. Split big lists into groups of 50. |
| 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. |
| 429 | rate_limit_exceeded | Bulk bucket used up. | Wait error.retry_after seconds, then retry. |
Disconnect an account
Stops warmup and removes the saved login, but keeps the account, its settings and its history. Use it when you want to stop a mailbox without losing data.
| Old API | New API | |
|---|---|---|
| Method + route | POST /v1/email-accounts/{emailAccountId}/disconnect | POST /v2/workspaces/{workspaceId}/accounts/{id}/disconnect |
| Key permission (scope) | any key | accounts:write (key owner needs editor role or higher) |
| Rate bucket | 20/min shared | write |
| Plan needed | - | - |
What changed
- The response is the full account object (see above), not
{ emailAccountId, status: "disconnected" }. Checkstatus=DISCONNECTED. - Disconnecting an account that is already disconnected now returns
400 invalid_request. The old API returned409 already_disconnected. - You cannot reconnect over the API. Reconnecting is a browser flow in the TrulyInbox app.
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 POST "$TI_BASE_URL/v2/workspaces/57/accounts/4821/disconnect" \
-H "Authorization: Bearer ti_ws_your_key"Example request (old)
curl -X POST "https://lupus-edge.trulyinbox.com/v1/email-accounts/4821/disconnect" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK. data is the account object (see above). Shortened example:
{
"data": {
"id": 4821,
"emailAddress": "jane@acme.com",
"status": "DISCONNECTED",
"warmupStatus": "PAUSED",
"tags": [{ "id": 12, "name": "Q3-outreach" }],
"createdAt": "2026-09-18T14:03:10.000Z"
},
"meta": {
"request_id": "req_7c5e3a1f-9d8b-4f6e-a4c2-0b1d3e5f7a9c",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Response (old)
{
"emailAccountId": 4821,
"status": "disconnected"
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | The account is already disconnected. | Treat it as done. |
| 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. | Use a key from an editor. |
| 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 | Write bucket used up. | Wait error.retry_after seconds, then retry. |
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.
Delete an account to Note: Microsoft redirect path
Permanently deletes the account and all its warmup history. This cannot be undone. Use "Disconnect an account" if you want to keep the data.