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 API | New API | |
|---|---|---|
| Method + route | GET /v1/workspaces/{workspaceId}/preview | GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/preview |
| Key permission (scope) | any key | accounts:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | paid plan feature |
What changed
- The tenant id in the path is now the number
providerWorkspaceId(was the stringworkspaceId). - New
page(default 1) andlimit(default 50) query parameters. The old docs had none. domainchanged 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_errorand the tenant stays registered. - The response has the same fields as before, now inside
data.newEmails[].domainis now filled for Microsoft too.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
providerWorkspaceId | path | number | yes | - | The tenant's id (data.id from register). | workspaceId (string) |
page | query | number | no | default 1, min 1 | Page number. | - |
limit | query | number | no | default 50, min 1 | Mailboxes per page. | - |
search | query | string | no | - | Part of an email address or display name. | search |
domain | query | string (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) | Type | What it means | Old field |
|---|---|---|---|
newEmails | array | This page of mailboxes you can connect. | newEmails |
newEmails[].email | string | The mailbox address. | newEmails[].email |
newEmails[].displayName | string or null | The person's name in the directory. | newEmails[].displayName |
newEmails[].domain | string | The mailbox domain. | newEmails[].domain |
total | number | How many mailboxes match your filters, across all pages. | total |
connectedCount | number | Mailboxes from this tenant already connected. | connectedCount |
domains | array | Each 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | providerWorkspaceId is not a number, or page / limit is below 1. | Fix the path or query. |
| 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. |
| 404 | not_found | No tenant with this providerWorkspaceId in this workspace. | Check the id with the list call. |
| 429 | rate_limit_exceeded | Too many read calls this minute. | Wait error.retry_after seconds. |
| 502 | internal_error | Google 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 API | New API | |
|---|---|---|
| Method + route | POST /v1/workspaces/{workspaceId}/sync | POST /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync |
| Key permission (scope) | any key | accounts:write |
| Rate bucket | 20/min shared | write |
| Plan needed | - | paid plan feature |
What changed
- The tenant id in the path is now the number
providerWorkspaceId. emailAccountIdsToDeleteis removed. To remove mailboxes, callDELETE /v2/workspaces/{workspaceId}/accounts/{id}for each one.tagNameis removed. To tag the new mailboxes, wait for the job to finish, take the account ids fromitemsin the progress response, and callPOST /v2/workspaces/{workspaceId}/accounts/bulk/tags.- Emails in
emailsToConnectthat are not in the tenant are now skipped silently. The old 422mailboxes_not_foundis gone. - The response now carries only
jobId. The oldstatusfield 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
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
providerWorkspaceId | path | number | yes | - | The tenant's id (data.id from register). | workspaceId (string) |
Request body
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
selectAll | boolean | yes | true, false | true: connect every mailbox not yet connected (narrowed by selectedDomains, minus deselect). false: connect only emailsToConnect. | selectAll |
selectedDomains | string[] | no | - | With selectAll: true, only these domains. Empty = all domains. | selectedDomains |
deselect | string[] | no | - | With selectAll: true, these emails are left out. | deselect |
emailsToConnect | string[] | when selectAll is false | at least 1 email when selectAll is false | The exact mailboxes to connect. | emailsToConnect |
enableWarmup | boolean | yes | true, false | Turn 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) | Type | What it means | Old field |
|---|---|---|---|
jobId | string | The 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | A required field is missing or has the wrong type, or selectAll is false and emailsToConnect is empty. | Fix the body. |
| 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. | Upgrade the plan, or use an editor's key. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 404 | not_found | No tenant with this providerWorkspaceId in this workspace. | Check the id with the list call. |
| 429 | rate_limit_exceeded | Too 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 API | New API | |
|---|---|---|
| Method + route | GET /v1/workspaces/{workspaceId}/sync-status | GET /v2/workspaces/{workspaceId}/provider-workspaces/{providerWorkspaceId}/sync-status |
| Key permission (scope) | any key | accounts:read |
| Rate bucket | 20/min shared | read |
| 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. Newstatus:pending,running,complete,failed. Notecompletedbecamecomplete. - 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 returnedstate: nullinstead. failures[].erroranditems[].jobItemErrorhold 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) and020008(the email domain is blocked).- When
selectAllwastrue,totalstays0. Stop polling onstatus, not onprocessed == total.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
providerWorkspaceId | path | number | yes | - | The tenant's id. | workspaceId (string) |
jobId | query | string | yes | - | 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) | Type | What it means | Old field |
|---|---|---|---|
status | string | "pending", "running", "complete" or "failed". | state |
total | number | Planned mailboxes. 0 when selectAll was true. | - |
processed | number | Mailboxes handled so far (succeeded + failed). | - |
succeeded | number | Mailboxes connected. | - |
failed | number | Mailboxes not connected. | - |
failures | array | Up to 100 failed mailboxes: email and error (internal 6-digit code). | failedReason (roughly) |
items | array of objects | One 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | providerWorkspaceId is not a number. | Fix the path. |
| 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. |
| 404 | not_found | No 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. |
| 429 | rate_limit_exceeded | Too many read calls this minute. | Poll less often, or wait error.retry_after seconds. |