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/workspacesis not the oldPOST /v1/workspaces. In the new API,POST /v2/workspacescreates 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 stringworkspaceIdsuch as"aB3xY7Qk". You get it fromdata.idin 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
| Step | Old API | New API |
|---|---|---|
| 1. Allow access | In 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 tenant | POST /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 mailboxes | GET /v1/workspaces/{workspaceId}/preview | GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview |
| 4. Start the import | POST /v1/workspaces/{workspaceId}/sync, keep jobId | POST /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync, keep data.jobId |
| 5. Check progress | GET /v1/workspaces/{workspaceId}/sync-status?jobId=... | GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync-status?jobId=... |
Microsoft 365
| Step | Old API | New API |
|---|---|---|
| 1. Get the admin consent link | GET /v1/workspaces/microsoft/consent-url?domain=... | GET /v2/workspaces/{workspaceId}/provider-workspaces/microsoft/consent-url?domain=... |
| 2. Admin approves | Send url to the customer's Microsoft admin. They open it and approve. | Same. |
| 3. Register the tenant | POST /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 mailboxes | GET /v1/workspaces/{workspaceId}/preview | GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview |
| 5. Start the import | POST /v1/workspaces/{workspaceId}/sync | POST /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync |
| 6. Check progress | GET /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.
Get the Microsoft admin consent link
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 API | New API | |
|---|---|---|
| Method + route | GET /v1/workspaces/microsoft/consent-url | GET /v2/workspaces/{workspaceId}/provider-workspaces/microsoft/consent-url |
| Key permission (scope) | any key | accounts:write |
| Rate bucket | 20/min shared | read |
| 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:writescope, even though this is a GET. It still counts against the read rate bucket. - The link now carries a
statevalue in its query string. You must send thisstateback when you register the tenant. You can read it fromdata.urlnow, or from the redirect after the admin approves. - The
stateis 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
domainis now a 422unprocessable_entity(was 422workspace_validation_failed).
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
domain | query | string | no | max 255 characters | The 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) | Type | What it means | Old field |
|---|---|---|---|
url | string | The 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | domain is not a string or is longer than 255 characters. | Fix the query value. |
| 401 | unauthorized / invalid_api_key | The key is missing, wrong, or revoked. | Check the Authorization header. |
| 403 | insufficient_scope | The key does not have accounts:write. | Use a key with accounts:write. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | forbidden | Your 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. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 422 | unprocessable_entity | No Microsoft tenant was found for domain. | Check the domain, or leave domain out. |
| 429 | rate_limit_exceeded | Too many read calls this minute. | Wait error.retry_after seconds. |
| 503 | internal_error | Bulk 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 API | New API | |
|---|---|---|
| Method + route | POST /v1/workspaces | POST /v2/workspaces/{workspaceId}/provider-workspaces |
| Key permission (scope) | any key | accounts:write |
| Rate bucket | 20/min shared | write |
| 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 400invalid_request. - The id you keep is now
data.id, a number. The oldworkspaceIdstring (for example"aB3xY7Qk") is gone. Usedata.idas{providerWorkspaceId}in every later call. statusis now"active"or"inactive"(was always"created"). The response also hasdomainsandlastSyncedAt.- For Microsoft,
adminEmailin the response is an empty string"". For Google,tenantIdisnull. - A bad admin email or missing Google delegation is now 400
invalid_request(was 422workspace_validation_failed). The four old "already connected" codes are now one: 409conflict. - Google delegation must now include these scopes:
admin.directory.user.readonly,admin.directory.domain.readonly,gmail.send,gmail.modify, andgmail.readonly(new). Full names start withhttps://www.googleapis.com/auth/.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace. The tenant's mailboxes will be imported into it. | - |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
provider | string | yes | "google", "microsoft" | Which company the tenant is at. | provider |
adminEmail | string | when provider is "google" | valid email address | A Google Workspace super-admin mailbox. Our service account acts as this user to list the domain's mailboxes. | adminEmail |
tenantId | string | when provider is "microsoft" | - | The Microsoft tenant id. Get it from the redirect after the admin approves. | tenantId |
state | string | when provider is "microsoft" | must come from a consent link made in this workspace by the same key user | Binds 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) | Type | What it means | Old field |
|---|---|---|---|
id | number | The tenant's id in TrulyInbox. Use it as {providerWorkspaceId}. | workspaceId (was a string) |
provider | string | "google" or "microsoft". | provider |
adminEmail | string | Google: the admin mailbox. Microsoft: "". | adminEmail |
tenantId | string or null | Microsoft: the tenant id. Google: null. | tenantId |
status | string | "active" or "inactive". | status (was "created") |
lastSyncedAt | string (date-time) or null | When the last import ran. null until the first one. | - |
domains | array | Domains 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | A 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. |
| 401 | unauthorized / invalid_api_key | The key is missing, wrong, or revoked. | Check the Authorization header. |
| 403 | insufficient_scope | The key does not have accounts:write. | Use a key with accounts:write. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | forbidden | Your 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. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 409 | conflict | This 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. |
| 429 | rate_limit_exceeded | Too many write calls this minute. | Wait error.retry_after seconds. |
| 503 | internal_error | Bulk 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 API | New API | |
|---|---|---|
| Method + route | none - new | GET /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
workspaceIdyourself. - The result is a plain array in
data. There is no paging and nopaginationobject.
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
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) | Type | What it means | Old field |
|---|---|---|---|
[].id | number | The tenant's id. Use it as {providerWorkspaceId}. | - |
[].provider | string | "google" or "microsoft". | - |
[].adminEmail | string | Google: the admin mailbox. Microsoft: "". | - |
[].tenantId | string or null | Microsoft: the tenant id. Google: null. | - |
[].status | string | "active" or "inactive". | - |
[].lastSyncedAt | string (date-time) or null | When the last import ran. | - |
[].domains[].domain | string | A domain in this tenant. | - |
[].domains[].mailboxCount | number | Mailboxes 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | The key is missing, wrong, or revoked. | Check the Authorization header. |
| 403 | insufficient_scope | The key does not have accounts:read. | Use a key with accounts:read. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the right workspace id or key. |
| 403 | forbidden | Your plan does not include bulk connect. | Upgrade the plan. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 429 | rate_limit_exceeded | Too many read calls this minute. | Wait error.retry_after seconds. |