Google Workspace Connector

The Google Workspace connector sends email from Business Central through the Gmail API as a Google Workspace user. A service account with domain-wide delegation impersonates the sender — no user login is involved.

How It Works

You create a Google Cloud service account, enable the Gmail API, and grant the service account domain-wide delegation for the gmail.send scope. Business Central imports the service account's JSON key, then signs its own tokens and sends mail as (impersonating) the Workspace user you specify.

Prerequisites

A Google Cloud project and access to the Google Admin console as a super admin (required for

the domain-wide delegation step).

A real Google Workspace user in your domain to send as, with Gmail enabled in its license.

Aliases, groups, and consumer Gmail accounts cannot be impersonated.

The Allow HttpClient Requests setting enabled for the ToolBox extension.

Step 1 — Create a Google Cloud Project and Enable the Gmail API

Go to console.cloud.google.com and create (or pick) a

project.

Open APIs & Services → Library, search for Gmail API, and click Enable.

Step 2 — Create a Service Account and Download Its Key

IAM & Admin → Service Accounts → Create service account. No project roles are

needed.

Open the new service account → Keys tab → Add key → Create new key → JSON. The

key file downloads once — store it safely.

On the Details tab, copy the numeric Unique ID (also called client ID) — you need it in

the next step.

Step 3 — Grant Domain-Wide Delegation

In the Google Admin console (admin.google.com, requires a super

admin): Security → Access and data control → API controls → Domain-wide delegation → Add new.

Enter the service account client ID from Step 2 and exactly this scope:

https://www.googleapis.com/auth/gmail.send

Pitfall — the scope must match exactly. A broader scope (such as https://mail.google.com/) does not cover a request for gmail.send — the delegation check compares literal scope strings, and the token request fails with unauthorized_client.

Step 4 — Register the Account in Business Central

Search for Email Accounts → Add an email account → choose *Google Workspace

(ToolBox)*.

Fill in the account card:

Field	Description
Account Name	A name to identify this account in Business Central.
Sender Email Address	The Workspace user the service account impersonates and sends as. Must be a real user in your domain.
Service Account Email	Filled in automatically when you upload the key file (read-only).
Enabled	The send mode — see the Enabled modes.
Redirect Email Address	Only used when Enabled (Redirect) is selected.

Click Upload Key File and pick the JSON file from Step 2. The Service Account Email

fills in automatically, and the private key is converted and stored securely — the file content never lands in the database.

Step 5 — Verify the Setup

Test Connection exchanges a signed token with Google. This single call validates the key,

the domain-wide delegation, and the impersonated user — if it succeeds, the plumbing works.

Send Test Email sends a message from the sender to itself through the Gmail API.

Troubleshooting

Error	Cause	Fix
`unauthorized_client`	Domain-wide delegation is missing, uses the wrong client ID, or the scope does not literally match `gmail.send`.	Redo Step 3. Delegation changes usually apply within minutes but can take up to 24 hours.
`invalid_grant` (invalid email / user)	The sender email address is not a user in the Workspace domain the delegation was granted in.	Use a real Workspace user (aliases and groups cannot be impersonated).
`failedPrecondition` (400) when sending	The impersonated address is a consumer Gmail account or a mailbox without Gmail service enabled.	Use a Workspace user with Gmail enabled in its license.
The key file is rejected on upload	Not a service account JSON key (for example, an OAuth client file) or a password-protected key.	Download a fresh JSON key for the service account (Step 2).

Key rotation: create a new JSON key in the Google console, upload it on the account card, then delete the old key in Google. Uploading replaces the stored key in place.

Security: anyone with the key file can send as any delegated user. Limit the delegation scope to gmail.send only (done in Step 3), keep the JSON file out of shared storage, and delete downloaded copies after uploading.

Test environments: use the Enabled setting on the account card — Enabled (No Sending) swallows all mail, Enabled (Redirect) reroutes everything to a single address.