This guide is for Google Workspace Super Administrators. It should take approximately 15–20 minutes to complete. If you need assistance at any point, please contact your MetaCompliance Support representative.

Overview

MetaCompliance Phish can deliver phishing simulation emails directly into your users' Gmail inboxes using Google's Direct Message Injection method. This bypasses email filters, ensuring that simulation emails are delivered reliably and that your phishing reports reflect genuine user behaviour only.

To enable this, MetaCompliance requires your Google Workspace Super Administrator to authorise our service account to insert messages into your users' mailboxes. This is a one-time setup performed in your Google Admin Console.

What you will need

• Super Administrator access to your Google Workspace Admin Console
• The MetaCompliance service account Client ID (provided by your MetaCompliance Support representative)
• If your organisation has multi-party approval enabled for administrative actions, a second Super Administrator will need to be available to confirm the authorisation

What MetaCompliance can and cannot access

MetaCompliance's service account is granted only the gmail.insert scope. This means it can only insert messages into your users' inboxes. It cannot read, modify, delete, or send emails on behalf of your users, and it has no access to any other Google Workspace data. No other scopes are granted.

Step 1 - Sign in to your Google Admin Console

Go to admin.google.com and sign in with your Super Administrator account.

Step 2 - Navigate to Domain-wide Delegation

From the Admin Console home page:

1. Click the main menu (☰) in the top left
2. Go to Security
3. Select Access and data control
4. Select API controls
5. Under the Domain-wide delegation section, click Manage Domain-wide Delegation

Step 3 - Add MetaCompliance's service account

1. Click Add new
2. In the Client ID field, enter the Client ID provided by your MetaCompliance Support representative
3. In the OAuth Scopes field, enter exactly the following:
   https://www.googleapis.com/auth/gmail.insert 
4. Click Authorise

Note: If your organisation has multi-party approval enabled, you will see a pending approval notification rather than an immediate confirmation. A second Super Administrator will need to log in to the Admin Console and approve the request before the authorisation takes effect.

Step 4 - Confirm the authorisation

Once authorised, the MetaCompliance service account will appear in your Domain-wide Delegation list. You can verify the entry at any time by returning to Security → Access and data control → API controls → Manage Domain-wide Delegation.

Please allow up to 60 minutes for the authorisation to propagate across your Google Workspace environment before MetaCompliance begins sending simulations via Direct Message Injection.

Step 5 - Notify your MetaCompliance Support representative

Once you have completed the authorisation, please notify your MetaCompliance Support representative. They will:

• Update your account configuration to enable Direct Message Injection delivery
• Run a test injection to verify the setup is working correctly before your first live simulation

 Removing access

If you wish to remove MetaCompliance's access at any time, return to Security → Access and data control → API controls → Manage Domain-wide Delegation, find the MetaCompliance entry, and click Delete. Please notify your MetaCompliance Support representative if you do this, as phishing simulations for your organisation will not fall back to standard SMTP delivery automatically. 

Frequently asked questions

Do I need to create a GCP project or service account?
No. MetaCompliance manages the GCP project and service account on our side. You only need to authorise our existing service account within your Google Workspace Admin Console.

Why does MetaCompliance need domain-wide delegation?
Domain-wide delegation allows MetaCompliance's service account to insert simulation emails into individual users' inboxes without requiring each user to grant consent individually. This is the standard mechanism Google provides for enterprise applications that need to act on behalf of users within a Workspace domain.

Will this give MetaCompliance access to our users' emails?
No. The gmail.insert scope permits only the insertion of new messages. MetaCompliance cannot read, search, modify, or delete any existing emails in your users' mailboxes.

We have multi-party approval enabled — what does this mean for setup?
When multi-party approval is active in your organisation, any new domain-wide delegation authorisation requires a second Super Administrator to approve the request before it takes effect. Please ensure a second Super Administrator is available when completing Step 3, or allow additional time for the approval to be completed.