Docs
Migrating from v1Bulk connect

Bulk connect

Move the old /v1/workspaces bulk-connect API to /v2 provider workspaces.

Bulk connect imports many mailboxes at once from a Google Workspace or Microsoft 365 tenant (the customer's company account at Google or Microsoft); in the new API these tenants are called provider workspaces.

Warning: POST /v2/workspaces is not the old POST /v1/workspaces. In the new API, POST /v2/workspaces creates a TrulyInbox workspace (a folder of mailboxes inside your TrulyInbox account). It does not register a Google or Microsoft tenant. If you only change the host and the version number, your bulk-connect code will create empty TrulyInbox workspaces and connect nothing. All old /v1/workspaces/... bulk-connect calls must move to /v2/workspaces/{workspaceId}/provider-workspaces/....

Two ids now appear in every path:

  • {workspaceId} is your TrulyInbox workspace (a number). Your API key must have access to it.
  • {providerWorkspaceId} is the Google or Microsoft tenant you registered (a number). It replaces the old string workspaceId such as "aB3xY7Qk". You get it from data.id in the register response, or from the list call.

All routes in this page are plan-gated: bulk connect is a paid plan feature. If your plan does not include it, every call returns 403 forbidden. The calls that change data (consent link, register, sync) also need the key's user to have the editor role or higher in the TrulyInbox workspace; a viewer gets 403 forbidden.

End-to-end flow

Google Workspace

StepOld APINew API
1. Allow accessIn Google Admin Console, add domain-wide delegation (a Google setting that lets our service account act for the domain's mailboxes) for the TrulyInbox service account.Same step. The scope list now also needs gmail.readonly (see "Register a tenant").
2. Register the tenantPOST /v1/workspaces with provider: "google" and adminEmail. Keep workspaceId (string).POST /v2/workspaces/{workspaceId}/provider-workspaces with the same body. Keep data.id (number) as providerWorkspaceId.
3. Preview mailboxesGET /v1/workspaces/{workspaceId}/previewGET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview
4. Start the importPOST /v1/workspaces/{workspaceId}/sync, keep jobIdPOST /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync, keep data.jobId
5. Check progressGET /v1/workspaces/{workspaceId}/sync-status?jobId=...GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync-status?jobId=...

Microsoft 365

StepOld APINew API
1. Get the admin consent linkGET /v1/workspaces/microsoft/consent-url?domain=...GET /v2/workspaces/{workspaceId}/provider-workspaces/microsoft/consent-url?domain=...
2. Admin approvesSend url to the customer's Microsoft admin. They open it and approve.Same.
3. Register the tenantPOST /v1/workspaces with provider: "microsoft" and tenantId.POST /v2/workspaces/{workspaceId}/provider-workspaces with provider, tenantId and state (new, required). Keep data.id.
4. Preview mailboxesGET /v1/workspaces/{workspaceId}/previewGET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview
5. Start the importPOST /v1/workspaces/{workspaceId}/syncPOST /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync
6. Check progressGET /v1/workspaces/{workspaceId}/sync-status?jobId=...GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync-status?jobId=...

New in v2: GET /v2/workspaces/{workspaceId}/provider-workspaces lists the tenants you already registered, so you can find a providerWorkspaceId again later.


Microsoft only. Returns a link for the customer's Microsoft admin to open in a browser and approve TrulyInbox for their tenant. Google tenants skip this step.

Old APINew API
Method + routeGET /v1/workspaces/microsoft/consent-urlGET /v2/workspaces/{workspaceId}/provider-workspaces/microsoft/consent-url
Key permission (scope)any keyaccounts:write
Rate bucket20/min sharedread
Plan needed-paid plan feature

What changed

  • The route now sits under your TrulyInbox workspace: /v2/workspaces/{workspaceId}/provider-workspaces/....
  • The key needs the accounts:write scope, even though this is a GET. It still counts against the read rate bucket.
  • The link now carries a state value in its query string. You must send this state back when you register the tenant. You can read it from data.url now, or from the redirect after the admin approves.
  • The state is tied to the key's user and to this TrulyInbox workspace. Register the tenant with a key of the same user, in the same workspace.
  • The response no longer returns tenantId. Read it from the redirect after the admin approves.
  • An unknown domain is now a 422 unprocessable_entity (was 422 workspace_validation_failed).

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
domainquerystringnomax 255 charactersThe customer's Microsoft domain (for example acme.com) or tenant GUID. Pins the consent screen to that one tenant. Leave it out for a generic screen, where the admin approves for whichever Microsoft account they are signed in to.domain

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/123/provider-workspaces/microsoft/consent-url?domain=acme.com" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X GET "https://lupus-edge.trulyinbox.com/v1/workspaces/microsoft/consent-url?domain=acme.com" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new)

200 OK

New field (inside data)TypeWhat it meansOld field
urlstringThe consent link. Send it to the customer's Microsoft admin. It includes the state query parameter you need later. Pinned to one tenant when you sent domain.url
{
  "data": {
    "url": "https://login.microsoftonline.com/acme.com/adminconsent?client_id=...&redirect_uri=...&state=eyJvcmdhbml6YXRpb25JZCI6..."
  },
  "meta": {
    "request_id": "req_8c2d41f0a7",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "url": "https://login.microsoftonline.com/customerdomain.com/adminconsent?client_id=...&redirect_uri=...&state=...",
  "tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestdomain is not a string or is longer than 255 characters.Fix the query value.
401unauthorized / invalid_api_keyThe key is missing, wrong, or revoked.Check the Authorization header.
403insufficient_scopeThe key does not have accounts:write.Use a key with accounts:write.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403forbiddenYour plan does not include bulk connect, or the key's user is a viewer in this workspace.Upgrade the plan, or use a key of an editor, admin or owner.
403subscription_pausedThe subscription is paused.Resume the subscription.
422unprocessable_entityNo Microsoft tenant was found for domain.Check the domain, or leave domain out.
429rate_limit_exceededToo many read calls this minute.Wait error.retry_after seconds.
503internal_errorBulk connect is not set up on our side.Contact support.

Register a tenant

Registers a Google Workspace or Microsoft 365 tenant with TrulyInbox. We check the access first; nothing is stored if the check fails. Registering connects no mailboxes. Mailboxes are connected only when you start the import.

Old APINew API
Method + routePOST /v1/workspacesPOST /v2/workspaces/{workspaceId}/provider-workspaces
Key permission (scope)any keyaccounts:write
Rate bucket20/min sharedwrite
Plan needed-paid plan feature

What changed

  • Moved. Do not call POST /v2/workspaces. That creates a TrulyInbox workspace, not a tenant.
  • Microsoft now also needs state, taken from the consent link (see above). Without it you get 400 invalid_request.
  • The id you keep is now data.id, a number. The old workspaceId string (for example "aB3xY7Qk") is gone. Use data.id as {providerWorkspaceId} in every later call.
  • status is now "active" or "inactive" (was always "created"). The response also has domains and lastSyncedAt.
  • For Microsoft, adminEmail in the response is an empty string "". For Google, tenantId is null.
  • A bad admin email or missing Google delegation is now 400 invalid_request (was 422 workspace_validation_failed). The four old "already connected" codes are now one: 409 conflict.
  • Google delegation must now include these scopes: admin.directory.user.readonly, admin.directory.domain.readonly, gmail.send, gmail.modify, and gmail.readonly (new). Full names start with https://www.googleapis.com/auth/.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace. The tenant's mailboxes will be imported into it.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
providerstringyes"google", "microsoft"Which company the tenant is at.provider
adminEmailstringwhen provider is "google"valid email addressA Google Workspace super-admin mailbox. Our service account acts as this user to list the domain's mailboxes.adminEmail
tenantIdstringwhen provider is "microsoft"-The Microsoft tenant id. Get it from the redirect after the admin approves.tenantId
statestringwhen provider is "microsoft"must come from a consent link made in this workspace by the same key userBinds the admin's approval to you. Read it from the state query parameter of the consent link.-

Example request (new)

Google:

curl -X POST "$TI_BASE_URL/v2/workspaces/123/provider-workspaces" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "adminEmail": "admin@acme.com"
  }'

Microsoft:

curl -X POST "$TI_BASE_URL/v2/workspaces/123/provider-workspaces" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "microsoft",
    "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
    "state": "eyJvcmdhbml6YXRpb25JZCI6..."
  }'

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/workspaces" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "adminEmail": "admin@acme.com"
  }'

Response (new)

201 Created

New field (inside data)TypeWhat it meansOld field
idnumberThe tenant's id in TrulyInbox. Use it as {providerWorkspaceId}.workspaceId (was a string)
providerstring"google" or "microsoft".provider
adminEmailstringGoogle: the admin mailbox. Microsoft: "".adminEmail
tenantIdstring or nullMicrosoft: the tenant id. Google: null.tenantId
statusstring"active" or "inactive".status (was "created")
lastSyncedAtstring (date-time) or nullWhen the last import ran. null until the first one.-
domainsarrayDomains found in this tenant: domain and mailboxCount.-
{
  "data": {
    "id": 42,
    "provider": "google",
    "adminEmail": "admin@acme.com",
    "tenantId": null,
    "status": "active",
    "lastSyncedAt": null,
    "domains": []
  },
  "meta": {
    "request_id": "req_8c2d41f0a7",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "workspaceId": "aB3xY7Qk",
  "provider": "google",
  "adminEmail": "admin@customerdomain.com",
  "tenantId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "status": "created"
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestA field is missing or invalid (for example no adminEmail for Google, no state for Microsoft). Also: the admin email cannot be reached, Google delegation is missing scopes, the Microsoft state is invalid, or Microsoft approval could not be completed.Read error.message. Fix the body, or ask the customer's admin to redo delegation or consent.
401unauthorized / invalid_api_keyThe key is missing, wrong, or revoked.Check the Authorization header.
403insufficient_scopeThe key does not have accounts:write.Use a key with accounts:write.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403forbiddenYour plan does not include bulk connect, the key's user is a viewer, or the Microsoft state belongs to a different user or workspace.Upgrade, use an editor's key, or get a new consent link with this key in this workspace.
403subscription_pausedThe subscription is paused.Resume the subscription.
409conflictThis tenant is already registered, in your account or in another TrulyInbox account.Use the list call to find its id, or contact support if another account holds it.
429rate_limit_exceededToo many write calls this minute.Wait error.retry_after seconds.
503internal_errorBulk connect is not set up on our side.Contact support.

List registered tenants

New. Lists the Google and Microsoft tenants registered in this TrulyInbox workspace. Use it to find a providerWorkspaceId again.

Old APINew API
Method + routenone - newGET /v2/workspaces/{workspaceId}/provider-workspaces
Key permission (scope)-accounts:read
Rate bucket-read
Plan needed-paid plan feature

What changed

  • The old API had no way to list tenants. You had to store the workspaceId yourself.
  • The result is a plain array in data. There is no paging and no pagination object.

Path and query parameters

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

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/123/provider-workspaces" \
  -H "Authorization: Bearer ti_ws_your_key"

Response (new)

200 OK. data is an array. Each item has the same fields as the register response.

New field (inside data)TypeWhat it meansOld field
[].idnumberThe tenant's id. Use it as {providerWorkspaceId}.-
[].providerstring"google" or "microsoft".-
[].adminEmailstringGoogle: the admin mailbox. Microsoft: "".-
[].tenantIdstring or nullMicrosoft: the tenant id. Google: null.-
[].statusstring"active" or "inactive".-
[].lastSyncedAtstring (date-time) or nullWhen the last import ran.-
[].domains[].domainstringA domain in this tenant.-
[].domains[].mailboxCountnumberMailboxes on that domain.-
{
  "data": [
    {
      "id": 42,
      "provider": "google",
      "adminEmail": "admin@acme.com",
      "tenantId": null,
      "status": "active",
      "lastSyncedAt": "2026-09-29T10:15:00.000Z",
      "domains": [
        { "domain": "acme.com", "mailboxCount": 38 },
        { "domain": "acme.io", "mailboxCount": 7 }
      ]
    },
    {
      "id": 43,
      "provider": "microsoft",
      "adminEmail": "",
      "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
      "status": "active",
      "lastSyncedAt": null,
      "domains": []
    }
  ],
  "meta": {
    "request_id": "req_8c2d41f0a7",
    "timestamp": "2026-09-29T12:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyThe key is missing, wrong, or revoked.Check the Authorization header.
403insufficient_scopeThe key does not have accounts:read.Use a key with accounts:read.
403workspace_forbiddenThe key cannot access this workspaceId.Use the right workspace id or key.
403forbiddenYour plan does not include bulk connect.Upgrade the plan.
403subscription_pausedThe subscription is paused.Resume the subscription.
429rate_limit_exceededToo many read calls this minute.Wait error.retry_after seconds.