Docs
Email Accounts

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

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.

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

Path Parameters

workspaceIdnumber

Request Body

providerstring

Which provider the access token was issued by.

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

The mailbox this token opens. Verified server-side against the provider’s own profile endpoint - a mismatch is rejected, never silently corrected.

accessTokenstring

A live provider access token. There is deliberately NO refreshToken field - TrulyInbox does not want yours and will not accept one; token renewal happens through your refresh callback.

expiresAtstring

ISO 8601 UTC. Must be at least 5 minutes in the future.

senderName?string

Sender name. Absent means a lower setup score until set.

displayName?stringDeprecated

Deprecated alias of senderName, ignored when senderName is present.

Response Body

curl -X POST "https://lynx-api.trulyinbox.com/v2/workspaces/0/accounts/oauth" \  -H "Content-Type: application/json" \  -d '{    "provider": "gmail",    "emailAddress": "jane@customer.com",    "accessToken": "ya29.a0AfH6SM...",    "expiresAt": "2026-09-07T13:45:00.000Z",    "senderName": "Jane Doe",    "displayName": "Jane Doe"  }'
{
  "data": {
    "id": 0,
    "emailAddress": "string",
    "senderName": "string",
    "provider": "string",
    "authMethod": "string",
    "status": "string",
    "accountState": "string",
    "statusBucket": "string",
    "sendCheckFailed": true,
    "receiveCheckFailed": true,
    "structuredStatus": {},
    "warmupStatus": "string",
    "warmupPausedAt": "2019-08-24T14:15:22Z",
    "warmupPausedReason": "string",
    "throttleReason": "string",
    "cooldownUntil": "2019-08-24T14:15:22Z",
    "warmupMinLimit": 0,
    "warmupMaxLimit": 0,
    "warmupCurrentLimit": 0,
    "warmupRampupDay": 0,
    "warmupStrategy": "string",
    "timezone": "string",
    "poolTier": "string",
    "deliverabilityRate": 0,
    "spfData": {},
    "dkimData": {},
    "dmarcData": {},
    "mxRecordData": {},
    "dnsCheckedAt": "2019-08-24T14:15:22Z",
    "setupScore": 82,
    "inboxPlacementScore": 0,
    "lastVerifiedAt": "2019-08-24T14:15:22Z",
    "pushNotificationsActive": true,
    "createdAt": "2019-08-24T14:15:22Z",
    "source": "string",
    "dwdWorkspaceId": 0,
    "partnerIntegrationId": 0,
    "domainRegisteredAt": "2019-08-24T14:15:22Z",
    "mailboxCreatedAt": "2019-08-24T14:15:22Z",
    "warmupStartDate": "2019-08-24T14:15:22Z",
    "replyRate": 0,
    "warmupPreference": "string",
    "contentIndustry": "string",
    "contentTopics": [
      "string"
    ],
    "contentLanguage": "string",
    "blacklistedAt": "2019-08-24T14:15:22Z",
    "blacklistSource": "string",
    "todaySent": 0,
    "todayReceived": 0,
    "sevenDaySent": 0,
    "sevenDayReceived": 0,
    "tags": [
      {
        "id": 0,
        "name": "string",
        "color": "string"
      }
    ],
    "activeBulkJobId": "string",
    "activeImportId": "string"
  },
  "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"
  }
}

Generate an OAuth connection URLPOST

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.

Get a Microsoft single-mailbox consent linkGET

Connect ONE Microsoft mailbox without running your own OAuth app. Give the mailbox address (`email`) you want connected; the connection completes only if the Microsoft account that grants consent resolves to that address, which is what confirms ownership. The returned link is single-use and expires in 30 minutes - send it to the mailbox owner to open when they are ready. Once they finish they land on a result page carrying `partnerConnectStatus` (and, on failure, `partnerConnectReason`); poll GET .../accounts to confirm the mailbox connected. Warmup is enabled automatically on the new account, subject to plan capacity.