Google - How to Set Up Simulation Sending via DMI (Direct Message Injection)

This article explains how to configure Direct Message Injection (DMI) through Google in SMARTFENSE by creating a project in Google Cloud, enabling the required APIs, generating one or more service accounts, and uploading them to the platform. It is possible to configure multiple DMI accounts within the same project and distribute sending among them, increasing sending capacity and resilience against failures or quota limits.

The DMI setup ensures that simulation emails reach users' inboxes and prevents the gray Google warning banner from appearing: "This message was not sent to SPAM according to your organization's settings."

You can find this guide within the SMARTFENSE platform under Settings > Simulations > Delivery Method, selecting: Direct Message Injection via Google.

Prerequisites

Before starting the configuration, make sure you meet the following:

• The administrator performing the setup in Google must have the role of super administrator in Google Workspace.
• You must also have an administrator user in SMARTFENSE. This is necessary because the configuration validation is done via the Send me a test button, and only users belonging to the configured domain can successfully complete this check. The administrator will receive the validation email in their inbox.

DMI Configuration Guide via Google

1. Create a project in Google Cloud

1. Go to the following URL to create a project in Google Cloud: https://console.cloud.google.com/projectcreate
2. Enter a representative name in "Project Name", for example: SMARTFENSE-DMI.
3. Once created, the project's dashboard will appear.

2. Enable required APIs

4. From the APIs panel, click "Go to APIs overview".
5. Click "Enable APIs AND Services".
6. Search for and enable the "Gmail API".
7. Search for and enable the "Admin SDK API".

3. Create credentials and Service Account

8. Click on "APIs & Services > Credentials" in the side menu.
9. Locate the "Service Accounts" panel and click "Manage service accounts".
10. Click "Create Service Account".
11. Fill out the form with a name and description. For example:
    • Name: SMARTFENSE-DMI
    • Description: Direct message injection for SMARTFENSE simulation emails
12. Click "Continue".
13. Click "Done".

4. Generate the Service Account Key (JSON)

14. Once the "Service Account" is created, enter again to add a new "Key". To re-enter, click "APIs & Services > Credentials" in the side menu and then on the created service account.
15. Click "Create new key".
16. Select the JSON option and create the "key".
17. When finished, a file with the extension ".json" will be automatically downloaded. Save this file securely.

Warning: The JSON file content includes sensitive credentials. Limit its access to the responsible administrator and avoid sharing it through insecure channels.

5. Configure delegation in Google Admin

18. Access admin.google.com
19. Go to the "API Controls" menu.                                                   
20. Click "Manage domain-wide delegation".
21. Click "Add new" and enter the Client ID corresponding to the created "Service Account".                                             
22. In the OAuth scopes, copy the following:
    • https://www.googleapis.com/auth/admin.directory.user
    • https://www.googleapis.com/auth/gmail.insert
    • https://www.googleapis.com/auth/gmail.readonly

Important: SMARTFENSE does not use the granted permissions for any purpose other than those specified here in this guide.

6. Upload the account in SMARTFENSE

23. In the SMARTFENSE platform, click "+ Add account", fill in the following fields:
    • Label: enter a descriptive name to identify the account (for example, Main Account).
    • Service Account Email: the email address of the "Service Account" created in step 3. Create credentials and Service Account.
    • JSON Private Key: paste the content of the downloaded JSON file.
    • 
    • Assign a Distribution Weight, see: Distribution Weights
    • Leave selected: Active
24. In the Recipient for test. field, enter an email address belonging to the domain configured in the Service Account. By default, your own email is used. 
25. To validate the configuration, click Send test next to the account you want to validate individually, or click Send tests. to validate all configured accounts at once. If a configuration error is detected, a notification will be displayed with the details. 
26. Once the test is successful, click Save. The button remains disabled until the validation is completed successfully.

Note: Validation with Send me a test will only succeed if the user performing the test belongs to the domain configured in the Service Account.

Configuring Multiple DMI Accounts

It is possible to add several DMI accounts within the same sending method. This allows distributing the sends among the configured accounts and improving the capacity and resilience of simulation sending.

There is no maximum limit on configurable accounts. The only restriction is that there must be at least one active account to use DMI; if all are deactivated, the platform validates this when saving the configuration.

How many accounts should you configure?

The recommendation is based on two independent factors: volume and resilience.

By volume

The Gmail API has a daily insertion limit per Service Account. When that limit is reached, the platform puts the account on cooldown for 60 seconds and retries sending with other available accounts. If no other account is available, those messages will not be delivered that day.

The practical criterion is the number of users receiving simulations in the same day:

• Up to ~1,000 users/day: one account is sufficient in most cases.
• Between 1,000 and 3,000 users/day: it is advisable to have 2 accounts, especially if campaigns are concentrated in short time windows.
• More than 3,000 users/day: 3 or more accounts with uniform weight to distribute the load evenly.

The clearest sign that more accounts should be added is detecting daily quota errors in the logs or noticing that some users do not receive the simulation on the expected day.

By resilience

Although authentication failures are rare, having at least 2 accounts protects against this type of error: if one account's credentials become invalid (for example, expired JSON key or revoked permissions in Google Admin), the other account absorbs all sends without interruption. With only one account configured, this type of failure stops DMI sending until manually corrected.

Summary of the recommendation

• 2 accounts are recommended for any client using DMI productively.
• 3 or more accounts are justified by high volume or campaigns with very narrow delivery windows.

How to add additional accounts

1. Repeat steps 3 to 6 (Create Service Account, generate the Key, configure delegation in Google Admin, and upload the account in SMARTFENSE) within the same Google Cloud project for each additional account.
2. In SMARTFENSE, go to the Direct Message Injection via Google Accounts section and click + Add account.
3. Enter all required data: Label, Service Account Email, and JSON Private Key. Assign a distribution weight to each active account.

Distribution Weights

The distribution weight defines the proportion of sends assigned to each account. Three main schemes are supported:

• Uniform weight: all accounts with weight 1. Distributes sends evenly.
• Proportional weight: if one account has a higher quota or better performance, assign it a higher weight (for example, Account A = 3, Account B = 1).
• Backup weight: assign weight 1 to the backup account and higher weights (for example, 3 or 5) to the main accounts. This reduces the proportion of sends the backup account receives without reaching zero.

Example distribution with 3 accounts:

Behavior on Failures

When an account encounters an error during sending, SMARTFENSE automatically retries with another available account (up to 2 retries per message), applying intelligent redistribution depending on the error type:

• Sending limit reached (rate limit or daily quota exhausted): the account enters a 60-second cooldown period, and the message is retried with another account.
• Authentication error (invalid credentials): the account is excluded for the remainder of the sending session, and the message is passed to another account.
• Transient Google server error: the message is retried with another account without penalizing the original account.

These cooldowns and exclusions apply only during the current sending session, do not change the account's status in the platform, nor mark it as inactive.

💡 Best Practices

• Verify that the administrator performing the setup has the role of super administrator in Google Workspace and is an administrator user in SMARTFENSE before starting the process.
• Use Send test on each account when loading it, or Send tests. to validate all accounts at once, before saving the configuration.
• Create all additional accounts within the same Google Cloud project to simplify management and auditing.
• Store each ".json" file in a secure repository (for example, a secrets manager) and define an internal access process for the responsible administrator.
• Ensure that the delegation in "Manage domain-wide delegation" includes exactly the indicated permissions to avoid injection errors and reduce risks.
• Keep documented the Service Account Email and Label of each account to facilitate auditing and technical support.
• If working with multiple accounts, periodically review the distribution weights to align them with the available quota and the actual behavior of each account.