Docs
Migrating from v1Email accounts

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...

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 APINew API
Method + routePOST /v1/email-accounts/oauth (always returned 501 not_implemented)POST /v2/workspaces/{workspaceId}/accounts/oauth-url
Key permission (scope)any keyaccounts:write (key owner needs editor role or higher)
Rate bucket20/min sharedwrite
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 with GET /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

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

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
providerstringyesgmail, google_workspace, outlook, ms365Which 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)TypeWhat it meansOld field
providerstringThe provider you asked for.-
urlstringSingle-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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestprovider is missing or not one of the four values.Send a valid provider.
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.Use a key from an editor.
403subscription_pausedThe subscription is paused.Resume the subscription.
429rate_limit_exceededWrite 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 APINew API
Method + routenone - 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 with email_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

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

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
providerstringyesgmail, google_workspace, outlook, ms365Who issued the token.-
emailAddressstringyesvalid email, max 255 charactersThe mailbox the token opens. Checked against the provider.-
accessTokenstringyes1 to 4096 charactersA live provider access token.-
expiresAtstringyesISO 8601 UTC, at least 5 minutes in the futureWhen the token expires.-
senderNamestringnomax 255 charactersName shown as the sender. Without it the setup score is lower.-
displayNamestringnomax 255 charactersOld 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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestA 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.
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.
403partner_not_configuredYour organization has no verified partner callback.Register and verify it under Settings → API keys, or use oauth-url.
403plan_limit_reachedThe plan's mailbox limit is full.Upgrade, or delete a mailbox first.
403subscription_pausedThe subscription is paused.Resume the subscription.
409conflictThe address is already connected another way, by another partner, or in another workspace.Do not retry. Find the existing account.
422email_mismatchThe token belongs to a different mailbox than emailAddress.Send the token for the right mailbox.
429rate_limit_exceededWrite bucket used up.Wait error.retry_after seconds, then retry.

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 APINew API
Method + routeGET /v1/email-accounts/microsoft/consent-urlGET /v2/workspaces/{workspaceId}/accounts/microsoft/consent-url
Key permission (scope)any keyaccounts:write (key owner needs editor role or higher) - note: a write scope on a GET
Rate bucket20/min sharedread
Plan needed--

What changed

  • Only the path moved (now under the workspace). The email query and the { url, expiresAt } result are the same, now inside data.
  • Your key needs accounts:write, even though this is a GET.
  • After consent, the browser lands on a result page with partnerConnectStatus (and partnerConnectReason on 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

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Workspace to add the mailbox to.-
emailquerystringyesvalid emailThe 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)TypeWhat it meansOld field
urlstringSingle-use consent link. Send it to the mailbox owner.url
expiresAtstring (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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestemail is missing or not a valid address.Send a valid email.
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.Use a key from an editor.
403subscription_pausedThe subscription is paused.Resume the subscription.
429rate_limit_exceededRead bucket used up.Wait error.retry_after seconds, then retry.
503internal_errorMicrosoft 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 APINew API
Method + routePOST /v1/email-accounts/bulk-statusPOST /v2/workspaces/{workspaceId}/accounts/bulk-status
Key permission (scope)any keyaccounts:read
Rate bucket20/min sharedbulk
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 bulk rate bucket, which is smaller than read.

Path and query parameters

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

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
accountIdsnumber[]yes1 to 50 ids, whole numbers ≥ 1, no duplicatesAccounts 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)TypeWhat it meansOld field
accountsaccount object[]Accounts found, in the order you asked. See "The account object".results
notFoundnumber[]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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestaccountIds is empty, has more than 50 ids, has duplicates, or has a non-number.Fix the list. Split big lists into groups of 50.
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.
429rate_limit_exceededBulk 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 APINew API
Method + routePOST /v1/email-accounts/{emailAccountId}/disconnectPOST /v2/workspaces/{workspaceId}/accounts/{id}/disconnect
Key permission (scope)any keyaccounts:write (key owner needs editor role or higher)
Rate bucket20/min sharedwrite
Plan needed--

What changed

  • The response is the full account object (see above), not { emailAccountId, status: "disconnected" }. Check status = DISCONNECTED.
  • Disconnecting an account that is already disconnected now returns 400 invalid_request. The old API returned 409 already_disconnected.
  • You cannot reconnect over the API. Reconnecting is a browser flow in the TrulyInbox app.

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 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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestThe account is already disconnected.Treat it as done.
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.Use a key from an editor.
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_exceededWrite bucket used up.Wait error.retry_after seconds, then retry.