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.
• 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 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 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.

Updated on: 02/09/2026