Docs
Migrating from v1Bulk connect

Preview mailboxes to Check import progress (sync-status)

Lists the tenant's mailboxes that are not connected yet. Use it to choose what to import.

Preview mailboxes

Lists the tenant's mailboxes that are not connected yet. Use it to choose what to import.

Old APINew API
Method + routeGET /v1/workspaces/{workspaceId}/previewGET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview
Key permission (scope)any keyaccounts:read
Rate bucket20/min sharedread
Plan needed-paid plan feature

What changed

  • The tenant id in the path is now the number providerWorkspaceId (was the string workspaceId).
  • New page (default 1) and limit (default 50) query parameters. The old docs had none.
  • domain changed format. Old: comma-separated (domain=a.com,b.com). New: one JSON array (domain=["a.com","b.com"], URL-encoded). A single plain domain (domain=acme.com) still works. A comma-separated list is treated as one domain name and matches nothing.
  • A failed preview no longer deletes the registration. If the tenant's directory cannot be read, you get HTTP 502 internal_error and the tenant stays registered.
  • The response has the same fields as before, now inside data. newEmails[].domain is now filled for Microsoft too.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
providerWorkspaceIdpathnumberyes-The tenant's id (data.id from register).workspaceId (string)
pagequerynumbernodefault 1, min 1Page number.-
limitquerynumbernodefault 50, min 1Mailboxes per page.-
searchquerystringno-Part of an email address or display name.search
domainquerystring (JSON array)no-Only these domains. One value holding a JSON array, e.g. ["acme.com","acme.io"]. Empty = all domains.domain (comma-separated)

Request body

No body.

Example request (new)

curl -G "$TI_BASE_URL/v2/workspaces/123/provider-workspaces/42/preview" \
  -H "Authorization: Bearer ti_ws_your_key" \
  --data-urlencode 'domain=["acme.com","acme.io"]' \
  --data-urlencode 'search=jane' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=50'

Example request (old)

curl -X GET "https://lupus-edge.trulyinbox.com/v1/workspaces/aB3xY7Qk/preview?search=jane&domain=acme.com,acme.io" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new)

200 OK. The match count (total) is inside data, not in a pagination object. The response does not echo page or limit.

New field (inside data)TypeWhat it meansOld field
newEmailsarrayThis page of mailboxes you can connect.newEmails
newEmails[].emailstringThe mailbox address.newEmails[].email
newEmails[].displayNamestring or nullThe person's name in the directory.newEmails[].displayName
newEmails[].domainstringThe mailbox domain.newEmails[].domain
totalnumberHow many mailboxes match your filters, across all pages.total
connectedCountnumberMailboxes from this tenant already connected.connectedCount
domainsarrayEach domain with its count of connectable mailboxes (domain, count). Ignores your domain and search filters.domains
{
  "data": {
    "newEmails": [
      { "email": "jane@acme.com", "displayName": "Jane Doe", "domain": "acme.com" },
      { "email": "jane.ops@acme.io", "displayName": "Jane Ops", "domain": "acme.io" }
    ],
    "total": 2,
    "connectedCount": 5,
    "domains": [
      { "domain": "acme.com", "count": 33 },
      { "domain": "acme.io", "count": 7 }
    ]
  },
  "meta": {
    "request_id": "req_8c2d41f0a7",
    "timestamp": "2026-09-29T10:05:00.000Z"
  }
}

Response (old)

{
  "newEmails": [
    { "email": "jane@customerdomain.com", "displayName": "Jane Doe", "domain": "customerdomain.com" }
  ],
  "total": 25,
  "page": 1,
  "limit": 10,
  "connectedCount": 5,
  "domains": [
    { "domain": "customerdomain.com", "count": 25 }
  ]
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestproviderWorkspaceId is not a number, or page / limit is below 1.Fix the path or query.
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.
404not_foundNo tenant with this providerWorkspaceId in this workspace.Check the id with the list call.
429rate_limit_exceededToo many read calls this minute.Wait error.retry_after seconds.
502internal_errorGoogle or Microsoft refused to list the mailboxes (for example, delegation or consent was removed).Ask the customer's admin to check delegation or consent, then retry.

Start the import (sync)

Starts a background job that connects the mailboxes you chose. It returns at once with a jobId. Use the progress call to follow it.

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

What changed

  • The tenant id in the path is now the number providerWorkspaceId.
  • emailAccountIdsToDelete is removed. To remove mailboxes, call DELETE /v2/workspaces/{workspaceId}/accounts/{id} for each one.
  • tagName is removed. To tag the new mailboxes, wait for the job to finish, take the account ids from items in the progress response, and call POST /v2/workspaces/{workspaceId}/accounts/bulk/tags.
  • Emails in emailsToConnect that are not in the tenant are now skipped silently. The old 422 mailboxes_not_found is gone.
  • The response now carries only jobId. The old status field is gone.
  • If your plan has no room for all mailboxes, the job connects as many as fit. The rest appear as failures in the progress call.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
providerWorkspaceIdpathnumberyes-The tenant's id (data.id from register).workspaceId (string)

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
selectAllbooleanyestrue, falsetrue: connect every mailbox not yet connected (narrowed by selectedDomains, minus deselect). false: connect only emailsToConnect.selectAll
selectedDomainsstring[]no-With selectAll: true, only these domains. Empty = all domains.selectedDomains
deselectstring[]no-With selectAll: true, these emails are left out.deselect
emailsToConnectstring[]when selectAll is falseat least 1 email when selectAll is falseThe exact mailboxes to connect.emailsToConnect
enableWarmupbooleanyestrue, falseTurn on warmup for each mailbox that connects. This is best effort: a mailbox that cannot start warmup (for example, no warmup room left in the plan) is still connected and still counted as succeeded.enableWarmup
----Removed. Use DELETE /v2/workspaces/{workspaceId}/accounts/{id}.emailAccountIdsToDelete
----Removed. Use POST /v2/workspaces/{workspaceId}/accounts/bulk/tags after the job.tagName

Example request (new)

curl -X POST "$TI_BASE_URL/v2/workspaces/123/provider-workspaces/42/sync" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "selectAll": true,
    "selectedDomains": ["acme.com"],
    "deselect": ["ceo@acme.com"],
    "enableWarmup": true
  }'

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/workspaces/aB3xY7Qk/sync" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selectAll": true,
    "selectedDomains": ["acme.com"],
    "deselect": ["ceo@acme.com"],
    "emailsToConnect": [],
    "enableWarmup": true,
    "emailAccountIdsToDelete": [],
    "tagName": "partner-import"
  }'

Response (new)

202 Accepted

New field (inside data)TypeWhat it meansOld field
jobIdstringThe job id. Send it to the progress call.jobId
{
  "data": {
    "jobId": "8f3b2c1e-5d7a-4e21-9b6f-0a1c2d3e4f5a"
  },
  "meta": {
    "request_id": "req_8c2d41f0a7",
    "timestamp": "2026-09-29T10:10:00.000Z"
  }
}

Response (old)

{
  "status": "processing",
  "jobId": "dwd-sync-aB3xY7Qk-1720000000000"
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestA required field is missing or has the wrong type, or selectAll is false and emailsToConnect is empty.Fix the body.
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.Upgrade the plan, or use an editor's key.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo tenant with this providerWorkspaceId in this workspace.Check the id with the list call.
429rate_limit_exceededToo many write calls this minute.Wait error.retry_after seconds.

Check import progress (sync-status)

Returns the progress of an import job. Call it every few seconds until status is "complete" or "failed".

Old APINew API
Method + routeGET /v1/workspaces/{workspaceId}/sync-statusGET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync-status
Key permission (scope)any keyaccounts:read
Rate bucket20/min sharedread
Plan needed-paid plan feature

What changed

  • The response shape is new. Old: { state, failedReason }. New: { status, total, processed, succeeded, failed, failures, items }.
  • Status values changed. Old state: waiting, active, completed, failed, delayed. New status: pending, running, complete, failed. Note completed became complete.
  • You now get counts and a per-mailbox list, not just one state.
  • A finished job is kept for about 24 hours (was 12). After that you get 404 not_found. The old API returned state: null instead.
  • failures[].error and items[].jobItemError hold a TrulyInbox internal 6-digit code, not a public snake_case code. Log it. The two you will see most: 020002 (the plan's mailbox limit is reached) and 020008 (the email domain is blocked).
  • When selectAll was true, total stays 0. Stop polling on status, not on processed == total.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
providerWorkspaceIdpathnumberyes-The tenant's id.workspaceId (string)
jobIdquerystringyes-The jobId from the sync call.jobId

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/123/provider-workspaces/42/sync-status?jobId=8f3b2c1e-5d7a-4e21-9b6f-0a1c2d3e4f5a" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X GET "https://lupus-edge.trulyinbox.com/v1/workspaces/aB3xY7Qk/sync-status?jobId=dwd-sync-aB3xY7Qk-1720000000000" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new)

200 OK

New field (inside data)TypeWhat it meansOld field
statusstring"pending", "running", "complete" or "failed".state
totalnumberPlanned mailboxes. 0 when selectAll was true.-
processednumberMailboxes handled so far (succeeded + failed).-
succeedednumberMailboxes connected.-
failednumberMailboxes not connected.-
failuresarrayUp to 100 failed mailboxes: email and error (internal 6-digit code).failedReason (roughly)
itemsarray of objectsOne entry per handled mailbox. Connected ones have jobItemStatus: "succeeded", email, and the new account's fields (such as id, emailAddress, status). Failed ones have only email, displayName, jobItemStatus: "failed" and jobItemError. The spec lists this as string[], but the entries are objects.-
{
  "data": {
    "status": "complete",
    "total": 0,
    "processed": 3,
    "succeeded": 2,
    "failed": 1,
    "failures": [
      { "email": "sam@acme.com", "error": "020002" }
    ],
    "items": [
      { "jobItemStatus": "succeeded", "email": "jane@acme.com", "id": 5012, "emailAddress": "jane@acme.com", "status": "active" },
      { "jobItemStatus": "succeeded", "email": "raj@acme.com", "id": 5013, "emailAddress": "raj@acme.com", "status": "active" },
      { "jobItemStatus": "failed", "email": "sam@acme.com", "displayName": "Sam Lee", "jobItemError": "020002" }
    ]
  },
  "meta": {
    "request_id": "req_8c2d41f0a7",
    "timestamp": "2026-09-29T10:12:00.000Z"
  }
}

(Succeeded items are shortened here. Real ones carry more account fields.)

Response (old)

{
  "state": "completed",
  "failedReason": "Google API error: access_denied"
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestproviderWorkspaceId is not a number.Fix the path.
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.
404not_foundNo tenant with this id in this workspace, or the jobId is unknown, belongs to another workspace, or expired (about 24 hours).Check the ids. If the job expired, list the accounts instead.
429rate_limit_exceededToo many read calls this minute.Poll less often, or wait error.retry_after seconds.