Bulk Connect Mailboxes

Bulk connecting your Google Workspace or Microsoft 365 tenant is now possible over the API, not just through the TrulyInbox UI. This guide covers both providers, step by step, along with the endpoint to call at each stage. For full request/response formats, parameters, and error codes, see the endpoint references linked at each step.

For any questions or help, contact us at support@trulyinbox.com or book a meeting.

Connecting a Google Workspace

Step 1: Authorize domain-wide delegation

Before anything else, your Google Workspace admin needs to authorize TrulyInbox in the Google Admin Console.

  1. Open Google Admin Console and sign in as an Admin.

    Not the admin yourself? You can copy a message to send them from within TrulyInbox.

  2. Go to Domain-wide Delegation, or navigate there manually:

    Security › Access and data control › API controls › Manage domain-wide delegation

    Click Add new.

  3. Paste the following into the matching fields, then click Authorize:

    Service account ID

    109542662799681888263

    OAuth scopes

    https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.send

Once authorized, move to Step 2. There's no separate consent-link step for Google, since this authorization covers that.

Step 2: Register the workspace

POST/v1/workspaces
View docs

Register your Google Workspace with TrulyInbox using your admin email. This checks that the delegation from Step 1 is actually working. If it isn't, registration won't succeed, so double check Step 1 was completed correctly.

You'll get back a workspace ID in the response. Keep hold of it, since every remaining step refers back to it.

Step 3: Preview the mailboxes

GET/v1/workspaces/{workspaceId}/preview
View docs

Pull a preview of the mailboxes in your workspace that aren't connected to TrulyInbox yet. This also serves as a final check that your credentials genuinely work.

If that check fails, the workspace registration is automatically removed, so there's nothing to clean up manually. Just go back to Step 2 and register again.

Use this preview to decide which mailboxes to connect: all of them, everything in a particular domain, or a specific hand-picked list.

Step 4: Start the connection

POST/v1/workspaces/{workspaceId}/sync
View docs

Once you know which mailboxes to bring in, kick off the connection. At this point you also decide:

  • Whether warmup should be turned on for the mailboxes being connected.
  • Whether to apply a tag to them, so they're easy to identify later.
  • Whether any previously connected mailboxes from this same workspace should be removed as part of this run.

This runs in the background, so you'll get a job reference back to check on next.

Step 5: Check on progress

GET/v1/workspaces/{workspaceId}/sync-status
View docs

Use the job reference from Step 4 to check whether the connection has finished. It will show as still in progress, completed, or failed with a reason if something went wrong.

This status is only available for a limited window after the job finishes, so check back soon after starting the sync.

Google flow at a glance: Authorize domain-wide delegation → Register → Preview → Start connection → Check progress

Connecting a Microsoft 365 Workspace

GET/v1/workspaces/microsoft/consent-url
View docs

Generate a consent link and send it to your tenant admin. Once they open it and approve access in their browser, you're ready to move on.

If you already know your Microsoft domain, include it when generating the link (as a domain query parameter). This points the approval directly at the right tenant, and returns your tenant ID back to you automatically, so you don't need to look it up separately.

Step 2: Register the workspace

POST/v1/workspaces
View docs

Register your Microsoft workspace with TrulyInbox using your tenant ID. This checks that the admin consent from Step 1 has actually gone through. If it hasn't, registration won't succeed, so confirm your admin completed that step before trying again.

You'll get back a workspace ID in the response. Keep hold of it, since every remaining step refers back to it.

Step 3: Preview the mailboxes

GET/v1/workspaces/{workspaceId}/preview
View docs

Pull a preview of the mailboxes in your workspace that aren't connected to TrulyInbox yet. This also serves as a final check that your credentials genuinely work.

If that check fails, the workspace registration is automatically removed, so there's nothing to clean up manually. Go back to Step 1 (if consent needs redoing) or Step 2, and register again.

Use this preview to decide which mailboxes to connect: all of them, everything in a particular domain, or a specific hand-picked list.

Step 4: Start the connection

POST/v1/workspaces/{workspaceId}/sync
View docs

Once you know which mailboxes to bring in, kick off the connection. At this point you also decide:

  • Whether warmup should be turned on for the mailboxes being connected.
  • Apply a tag to them, so they're easy to identify later.
  • Whether any previously connected mailboxes from this same workspace should be removed as part of this run.

This runs in the background, so you'll get a job reference back to check on next.

Step 5: Check on progress

GET/v1/workspaces/{workspaceId}/sync-status
View docs

Use the job reference from Step 4 to check whether the connection has finished. It will show as still in progress, completed, or failed with a reason if something went wrong.

This status is only available for a limited window after the job finishes, so check back soon after starting the sync.

Microsoft flow at a glance: Get admin consent link → Register → Preview → Start connection → Check progress

For the exact request bodies, parameters, and response formats for each endpoint above, refer to the Workspaces API reference.

Previous

Introduction

Next

Health Check

On this page