> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.mailreach.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How to connect Google Workspace accounts to MailReach using Domain-Wide Delegation

This guide sets up a server-to-server connection between your Google Workspace and MailReach. You will create a Google Cloud service account, authorize it in Google Workspace Admin, then upload its JSON key to MailReach.

In simple terms, this lets MailReach communicate with Gmail mailboxes in your Workspace without creating an App Password for every user. Domain-Wide Delegation allows the service account to act on behalf of users in your domain within the OAuth scopes listed below. MailReach uses this connection for the mailboxes you choose to connect.

# Choose the right connection method

* **Use the standard App Password method** if you only need to connect one or a few mailboxes and can create an App Password for each one. Follow our [App Password guide](https://help.mailreach.co/en/article/how-to-connect-a-gmail-google-workspace-account-to-mailreach-with-an-app-password-ulwj00/).
* **Use Domain-Wide Delegation** if you need to connect multiple mailboxes from the same Google Workspace, want centralized admin control, or cannot manage App Passwords mailbox by mailbox.

This method is for Google Workspace accounts managed by an organization. It is not for personal `@gmail.com` accounts.

# Before you start

You will use three screens: **MailReach**, the **Google Cloud Console**, and the **Google Workspace Admin Console**.

Make sure you have:

* A **Google Workspace Super Admin** account for the Workspace that contains the mailboxes you want to connect. Google requires a Super Admin to authorize Domain-Wide Delegation.
* Permission in Google Cloud to create or select a project, enable APIs, create a service account, and create a service account key.
* Access to the mailboxes you want to connect, all inside that same Google Workspace.
* MailReach open at the connection screen so you can return to it at the end.

If your organization blocks service account key creation, you will also need help from a Google Cloud Organization Policy Administrator. The troubleshooting section explains this.

**Estimated time:** about 10 to 15 minutes if you already know Google Cloud and have all permissions. Allow 30 to 60 minutes for a first setup or if your organization blocks service account keys.

# Step 1: Open Domain-Wide Delegation in MailReach

## For email warming

1. In MailReach, open **Email Warmer**.
2. Click **Connect Mailbox**.
3. Select **Google Workspace / Gmail**.
4. Under **Step 1 - Turn on 2-Step Verification**, click **I don't want to use an app password**.

## For automated Spam Tests only

1. In MailReach, open **Spam Checker**.
2. Under **New Spam Test**, click **Automated**.
3. Click **Create an automated test**.
4. Select **Google Workspace / Gmail**.
5. Under **Sign in with the app password**, click **I don't want to use an app password**.

Keep this MailReach tab open. You will return to it in Step 5.

# Step 2: Create a Google Cloud project and enable the Gmail API

1. Open the [Google Cloud Console](https://console.cloud.google.com/) and sign in with the Google account that has access to your organization's Google Cloud resources.
2. Use the project selector at the top of the page. Select an existing dedicated project, or click **New Project** and create one. A clear name such as `MailReach Workspace Connection` will make it easier to identify later.
3. Make sure the new project is selected in the project selector.
4. Open **APIs & Services** > **Library**.
5. Search for **Gmail API**, open it, then click **Enable**.

# Step 3: Create the service account and download its JSON key

1. In the Google Cloud Console, open **IAM & Admin** > **Service Accounts**.
2. Click **Create service account**.
3. Enter a recognizable name, such as `MailReach`. The service account ID is generated automatically.
4. Click **Create and continue**.
5. You do not need to grant this service account a Google Cloud project role for this setup. Leave the optional role step empty, click **Continue**, then click **Done**.
6. In the service account list, click the email address of the service account you just created.
7. Open **Advanced settings**. Under **Domain-wide delegation**, copy the numeric **Client ID**. Google may also call this the **Unique ID**. Keep it available for Step 4.
8. Open the **Keys** tab.
9. Click **Add key** > **Create new key**.
10. Select **JSON**, then click **Create**. Google downloads the JSON key file to your computer.

**Security:** the JSON file contains a private credential. Do not email it, paste it into chat, or share it with anyone. Upload it only through the MailReach connection screen.

# Step 4: Authorize the service account in Google Workspace Admin

1. Open the [Google Workspace Admin Console](https://admin.google.com/) in a new tab.
2. Confirm that you are signed in as a **Super Admin** of the same Workspace that contains the mailboxes you want to connect.
3. Open **Security** > **Access and data control** > **API controls**.
4. In the **Domain-wide delegation** section, click **Manage Domain Wide Delegation**.
5. Click **Add new**.
6. In **Client ID**, paste the numeric Client ID copied in Step 3. Do not paste the service account email address.
7. In **OAuth scopes**, paste this exact comma-separated list:

https://mail.google.com/,https://www.googleapis.com/auth/userinfo.profile,https://www.googleapis.com/auth/gmail.imap_admin

8. Click **Authorize**.
9. Confirm that the new Client ID appears in the Domain-Wide Delegation list and that all three scopes are shown.

If your organization uses Google's multi-party approval for sensitive actions, another Super Admin must approve this change before it becomes active.

Google states that authorization changes can take up to 24 hours, although they usually apply much sooner.

# Step 5: Return to MailReach and connect the mailboxes

1. Return to the MailReach tab you kept open.
2. Upload the JSON key file downloaded in Step 3.
3. Click **Next**.
4. Select or enter the Google Workspace mailboxes you want to connect, then follow the on-screen confirmation steps.
5. Confirm that each selected mailbox appears as connected in MailReach.

# Troubleshooting

## "Service account key creation is disabled"

Your Google Cloud organization is enforcing the policy named **Disable service account key creation** (`constraints/iam.disableServiceAccountKeyCreation`). Google enables this restriction by default for many organizations created on or after May 3, 2024.

Do not restart the setup with a personal Gmail account. That account is not the Google Workspace you need to authorize.

1. Ask your Google Cloud Organization Policy Administrator or security team to review the policy for the dedicated project used in this guide.
2. If your organization's security rules allow it, they can create a narrow exception so service account key creation is permitted for this setup.
3. Make sure the person creating the key has the **Service Account Key Admin** role, or equivalent permissions, on the project or service account.
4. Return to **IAM & Admin** > **Service Accounts** > your service account > **Keys**, then retry **Add key** > **Create new key** > **JSON**.

If your organization does not permit external service account keys, use the standard App Password method instead, if your Workspace policy allows App Passwords.

## "Unauthorized client", "invalid client", or authentication error

* Confirm that you authorized the service account in the same Google Workspace as the mailboxes you are connecting.
* Confirm that you pasted the numeric Client ID, not the service account email address.
* Open the Domain-Wide Delegation entry and verify that all three OAuth scopes are present exactly as shown in Step 4.
* If multi-party approval is enabled, confirm that the request was approved by the second Super Admin.
* If everything is correct, wait and retry later. Google says changes can take up to 24 hours to propagate.

## The Google Cloud project or organization is missing

* Click your profile picture in the Google Cloud Console and confirm that you are using the intended work account, not a personal Google account.
* Use the project selector at the top of the page and confirm that the dedicated project is selected.
* Google Workspace Super Admin access and Google Cloud IAM permissions are separate. Ask your Google Cloud administrator for the missing project permissions if needed.

## The JSON file is rejected in MailReach

* Make sure you selected the JSON file downloaded from the exact service account authorized in Step 4.
* Do not edit the JSON file.
* If the file is damaged or belongs to another service account, create a new JSON key from **IAM & Admin** > **Service Accounts** > your service account > **Keys**.

## You are still blocked

Contact us in the MailReach chat with the exact error message, the step where it appears, and a screenshot with sensitive values hidden. Never send us the JSON file or its private key in chat.