Docs
Email Accounts

Generate an OAuth connection URL

Generate a provider OAuth connection URL

Returns a consent URL for Gmail / Google Workspace / Outlook / MS365. This is NOT a session or auth endpoint - it only builds the URL a human opens in a browser. The account is created on the provider redirect back to TrulyInbox, so an OAuth mailbox cannot be connected headlessly over the API. The URL embeds an encrypted state binding the connection to this request's workspace.

POST
/v2/workspaces/{workspaceId}/accounts/oauth-url

Path Parameters

workspaceIdnumber

Request Body

providerstring

Which provider consent screen to generate a URL for.

Value in"gmail" | "google_workspace" | "outlook" | "ms365"

Response Body

curl -X POST "https://lynx-api.trulyinbox.com/v2/workspaces/0/accounts/oauth-url" \  -H "Content-Type: application/json" \  -d '{    "provider": "gmail"  }'
{
  "data": {
    "provider": "gmail",
    "url": "https://accounts.google.com/o/oauth2/v2/auth?..."
  },
  "meta": {
    "request_id": "req_2f1c…",
    "timestamp": "2019-08-24T14:15:22Z"
  }
}
{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "details": {},
    "retry_after": 34
  },
  "meta": {
    "request_id": "req_2f1c…",
    "timestamp": "2019-08-24T14:15:22Z"
  }
}
{
  "error": {
    "code": "invalid_request",
    "message": "string",
    "details": {},
    "retry_after": 34
  },
  "meta": {
    "request_id": "req_2f1c…",
    "timestamp": "2019-08-24T14:15:22Z"
  }
}

Connect an email accountPOST

Connects a custom SMTP/IMAP mailbox to the workspace. The credentials are verified against both hosts before anything is written, and the password is encrypted at rest. OAuth providers (Gmail / Outlook) are connected through the browser consent flow, not this endpoint.

Connect a partner-managed OAuth mailbox (partner use only)POST

This endpoint is for TrulyInbox partners, not general API use: every call returns `403 partner_not_configured` unless your organization has a verified partner callback under Partner Integration in the app. You run your own consent screen and hold the refresh token; send us the access token. It is verified against the provider's own profile endpoint, and a mismatch with `emailAddress` is rejected. Renewal happens through your refresh callback. Warmup starts on its own once the domain's DNS records and the send-and-receive check pass; until then `warmup/enable` returns `409 mailbox_verification_pending`. To connect a mailbox yourself, use `oauth-url`.