Google Workspace Directory and Mailbox Access

mxHERO reads your Google Workspace directory and Gmail mailboxes through a Google service account with domain-wide delegation. A Workspace super administrator grants this once, for the whole domain. This page covers the directory source (users, aliases, groups and domains) and Gmail access for User Mailboxes rules.

For Google Drive storage, see Connecting Google Drive. For mail routing, see Google Workspace configuration.

Before you begin

• You need a Google Workspace super administrator account.
• You need the Owner or Administrator role in the Admin Dashboard.
• The Admin SDK API must not be blocked for third-party apps in your Workspace. See Google's Control which third-party & internal apps access Google Workspace data.

Scopes mxHERO needs

Domain-wide delegation lets the mxHERO service account act as users in your domain, limited to these OAuth scopes.

Google Drive storage needs further Drive scopes, which the Marketplace app requests.

Note: If the domain scope is missing (older installs), the sync still imports users and groups but can't read your domains. Add the domains by hand in Settings › Organization and domains.

Grant access to mxHERO

Install the mxHERO app for your domain from the Google Workspace Marketplace. Installing it domain-wide grants the delegation.

1. In the Admin Dashboard, open Settings › Integrations and select the Applications tab.

2. On the Google Apps for Organization card, click Verify. If the app is not installed yet, the dashboard explains the steps and opens the Marketplace listing: https://workspace.google.com/marketplace/app/mxhero_mail2cloud/197328540342.

   

3. In the Marketplace, sign in as a super administrator, click Domain Install , and accept the requested access for everyone in your organization.

4. Back in the dashboard, click Verify on the Google Apps for Organization card and enter a super administrator's email address.

5. Check the user, organization name and Google Customer ID shown, and click Confirm.

The card then shows that the connection is verified.

To check the grant in Google, open the Google Admin console at Security › Access and data control › API controls › Manage Domain Wide Delegation. The mxHERO client should list the scopes above.

Using your own Google Cloud project

Some organizations don't allow Marketplace apps. mxHERO can instead use a service account in your own Google Cloud project. This needs mxHERO support to load your credentials. Contact support before you start; see Getting support.

In outline: create a project, enable the Admin SDK API and Gmail API (and Google Drive API for Drive), create a service account, and in the Admin console add its client ID under Manage Domain Wide Delegation with all six scopes in the table above.

Connect the Google directory

1. Open Settings › Accounts and Groups.

2. In Directory Sources, click Add Source › Google Apps.

3. In Email Address, enter a super administrator's address. mxHERO acts as this user to read the directory ("We need a domain administrator account to collect the accounts and groups").

   

4. Optional: turn on Schedule Daily Synchronization to run the sync at a fixed hour.

5. Optional: expand Advanced Filters to limit the import:

   • Users filter: an Admin SDK user query, for example email:admin*. See Google's Search for users.
   • Groups filter: an Admin SDK group query, for example email:support*. See Google's Search for groups.
   • Only import email accounts that belong to a filtered group: available after you enter a groups filter.
   • Exclude domains: accounts and groups in these domains are not imported.

6. Click Add Source.

What gets imported

• Users: each user's primary address, plus aliases and non-editable aliases that are in your mxHERO domains.
• Groups: each group with its aliases and its user members.
• Domains: your Workspace domains are added to Settings › Organization and domains. A domain that belongs to another mxHERO organization is skipped with a warning.

Important: Google groups nested inside other groups are not expanded. A user who is a member only through a nested group is not a member of the parent group in mxHERO. Add users to the parent group directly, or target the nested group in rules.

Accounts that leave the directory, or your filters, are deleted from mxHERO at the next sync.

Use Gmail mailboxes in rules

After the app is installed, User Mailboxes rules can use the provider Organization: Google™ Apps. No further setup is needed. mxHERO watches for new mail itself for continuously updating rules.

If the app is not installed when you pick this provider, the dashboard opens the Marketplace listing.

What mailbox rules do in Gmail:

• They skip the DRAFT, SPAM, CHAT and TRASH labels.
• Mark email as processed adds a Gmail label (default mxHERO).
• Move Emails moves messages to the trash by default.

To connect one Gmail account with the user's own sign-in instead, see IMAP and individual mailboxes.

Verify

1. In Settings › Accounts and Groups, the Google Apps source shows a recent synchronization with no errors.
2. Search for a few users and groups.
3. For mailbox access, create a test Copy Emails rule with the User Mailboxes target, the Organization: Google™ Apps provider and one test account, for a short date range. Watch it in Rules › Rules List and check the files in storage.

Troubleshooting

Related pages

• Accounts and directory overview
• Groups
• Connecting Google Drive
• Rule targets
• Copy Emails