Whole-domain mailbox connects

A workspace can connect every mailbox on a Google Workspace domain or a Microsoft 365 organization through one administrator's approval, with no password and no sign-in per mailbox. In the dashboard these are Add account > Google > Whole Workspace domain and Add account > Microsoft > Whole organization, and both are the recommended way to connect those mailboxes. The customer side is in connect a whole Google Workspace domain and connect a whole Microsoft 365 organization.

This page is the operator side: what the instance needs before either option works. Both are off until you set them up, and a self-hosted instance shows them switched off in the dashboard, naming the settings still unset. GET /emails/grants/config reports the same as google_missing and microsoft_missing.

Everything here is read by the backend only. It mints every token for these mailboxes itself and hands a short-lived one to a worker each time it needs one, so workers and consumers need nothing from this page.

Google Workspace

A Google Workspace domain is connected through domain-wide delegation to a Google Cloud service account that belongs to your instance. You create the service account once and load its key into the backend. Each customer's Workspace super admin then authorizes that service account in their own Admin console, and nothing on your side changes per customer.

Set up the service account

services:
  backend:
    volumes:
      - ./secrets/google-workspace-delegation.json:/run/secrets/google-workspace-delegation.json:ro

# .env
GOOGLE_WORKSPACE_DELEGATION_KEY_FILE=/run/secrets/google-workspace-delegation.json

Proving the domain

The Client ID belongs to your instance, not to any one workspace, so a customer's authorization says nothing about which workspace asked for it. A Google grant is therefore recorded only for the workspace that proves it controls the domain, and only when the domain's directory lists the administrator's address as a super administrator. The proof is one of:

• The administrator's Google sign-in. It goes through the dashboard's own Google sign-in client (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) and returns to its existing redirect URI (GOOGLE_REDIRECT_URI, or API_PUBLIC_URL plus /v1/auth/google/callback), asking only for openid and email. The callback recognizes an administrator's proof and hands it back to the dashboard window that opened it; it signs nobody in. No redirect URI needs registering beyond the one sign-in already uses. When that client is not configured, the BOX_GOOGLE_* mailbox client is used the same way, through its own redirect URI (/addresses/google/callback) and again with openid and email only.
• A DNS record. A TXT record at _warmbly.<domain> holding a warmbly-verify= value unique to the workspace and domain, keyed by AUTH_SECRET. Always offered, and the only proof on an instance with neither Google client.

Customer administrators sign in to that client from their own organizations, so its OAuth consent screen has to be External. An Internal consent screen admits only accounts in your own Google organization, and every other administrator is refused and has to use the DNS record.

Key custody and rotation

The key can mint a token for any address on any domain that has authorized its Client ID. It is the one credential behind every such mailbox on the instance, so it lives on the backend and nowhere else: workers receive a short-lived access token per use and never the key, and no token for these mailboxes is stored.

To rotate the key:

1. On the service account's Keys tab, create a new JSON key.
2. Replace the file (or the inline value) and restart the backend.
3. Confirm the grants still pass, for example with Check again on one of them or POST /emails/grants/:id/check.
4. Delete the old key on the Keys tab.

Customers change nothing: the Client ID they authorized belongs to the service account, not the key.

Google app verification

Google treats domain-wide delegation as authorized by the customer's administrator, in their own Admin console. There is no OAuth consent screen for Google to review on that path, so the service account needs no Google app verification and no CASA security assessment for the Gmail scopes. Google's rules change, so confirm against Google's current help page on exceptions to verification requirements before relying on this. The sign-in client used for the domain proof asks only for openid and email, which are not sensitive scopes.

The per-mailbox Sign in with Google path is the one that needs Google's verification, and a security assessment, for its restricted Gmail scopes. It runs on the BOX_GOOGLE_* client, and it is being retired in favor of the whole-domain connect and app passwords. See moving existing mailboxes.

What the customer does

1. A super admin of the Workspace opens admin.google.com and goes to Security > Access and data control > API controls > Manage domain-wide delegation.

2. Chooses Add new, pastes the Client ID the dashboard shows, and enters exactly these three scopes, comma separated:

   https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.settings.basic,https://www.googleapis.com/auth/admin.directory.user.readonly

3. Chooses Authorize, and waits a few minutes: the Admin console takes a while to apply the change.

4. In Warmbly, proves the domain (the administrator's sign-in or the DNS record), then picks the mailboxes to connect.

The authorization comes before the proof, because Warmbly checks it straight away. The full walkthrough is in connect a whole Google Workspace domain.

When Google refuses

google_delegation_unauthorized means Google did not accept the delegation, or accepted it and refused a call. In the order they come up:

• Not applied yet. An Admin console change usually applies within minutes and occasionally takes longer. Wait, then try again or use Check again
• The wrong ID. The entry holds an OAuth client ID (...apps.googleusercontent.com) instead of the service account's numeric Client ID
• The scopes differ. The entry has to hold all three scopes above, exactly. A missing scope, a typo, or a different Gmail scope in its place is refused
• Not a super admin. The address entered in Warmbly is not a super administrator of the domain, so the directory cannot be read with it
• APIs off. The Gmail API or the Admin SDK API is not enabled on your service account's project (your side, not the customer's)

A grant that worked and later fails its hourly check shows as invalid and its mailboxes stop; they restart on their own once a check passes again. See google_delegation_unauthorized.

Microsoft 365

A Microsoft 365 organization is connected through admin consent to the Outlook app the instance already uses for single-mailbox Microsoft sign-in (BOX_OUTLOOK_CLIENT_ID, BOX_OUTLOOK_CLIENT_SECRET). There is no second app and no new setting: the option is on whenever those two are set. The app registration needs three additions.

Set up the app registration

Nothing needs a restart when only the app registration changes. GET /emails/grants/config answers microsoft_enabled: true whenever both BOX_OUTLOOK_* values are set.

Application permissions reach every mailbox in a consenting organization. We recommend that each organization scope the app to the mailboxes Warmbly should use with an Exchange Online application access policy (or RBAC for Applications); a mailbox outside the policy is refused when it connects. The commands are in connect a whole Microsoft 365 organization.

What the customer does

A Global Administrator of the organization chooses Add account > Microsoft > Whole organization, signs in, and chooses Accept on Microsoft's consent screen once. The organization recorded is the one the administrator signed in to, as Microsoft reports it, never a value from the request, and the grant is recorded only when that sign-in holds the Global Administrator or Privileged Role Administrator role in it. Then a member picks the mailboxes to connect.

When Microsoft refuses

microsoft_consent_missing means Microsoft did not issue a token for the organization, or issued one and refused the call:

• Not consented. The organization has not approved the app, or the consent screen was closed before Accept. A Global Administrator connects it again
• Not an administrator. Admin consent for application permissions needs a Global Administrator. An ordinary user's sign-in cannot give it
• Permissions missing. The app registration lacks one of the three application permissions, or they were added after the organization consented. A consent covers only the permissions the app had at the time, so the administrator has to consent again after a change
• Single tenant. The app registration is not multitenant, so other organizations cannot find it
• Unknown organization. Microsoft does not know the tenant the consent named

mailbox_grant_proof_missing from the Microsoft consent means the person who signed in does not hold the Global Administrator or Privileged Role Administrator role in the organization. Sign in with an account that does.

See microsoft_consent_missing.

Moving existing mailboxes

Per-mailbox Sign in with Google is being retired. Mailboxes connected that way keep working and there is no cutoff date, but the dashboard marks them and offers to move each one without losing its history, campaigns or warmup:

• A Google Workspace mailbox moves onto the domain's administrator grant. Connecting its address through the grant converts the mailbox in place
• A personal Gmail mailbox (or any Google mailbox) moves to an app password, checked against Gmail before anything is stored

Per-mailbox Microsoft sign-in is not being retired, but a mailbox on it can move onto an organization's grant the same way. The customer's side is in moving off per-mailbox Google sign-in. Keep the BOX_GOOGLE_* client configured while any mailbox still uses it: it is what refreshes their tokens.