> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cimento.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Mailbox permissions for direct delivery
> Every mailbox permission Cimento uses to place phishing simulations directly in Google Workspace and Microsoft 365 inboxes: what each one allows, what Cimento does with it, and how to narrow or revoke it.
With direct delivery, also called direct mailbox injection (DMI), Cimento writes each simulation straight into the employee's mailbox through the Gmail API or Microsoft Graph instead of sending it over SMTP. The message never crosses your mail gateway, so there is nothing to allowlist, and it looks exactly like a real attack would. In Cimento these integrations are **Google Workspace Email** and **Microsoft 365 Direct Inject**, under **Admin → Integrations → Phishing**.
Placing a message in someone's mailbox takes a mailbox permission that an administrator grants once. This page lists each permission, what it allows, what Cimento does with it, and how to narrow or revoke it, so you can hand it to whoever reviews third-party access. For step-by-step setup, follow the [Google Workspace](/integrations/google-workspace#deliver-phishing-simulations) or [Microsoft 365](/integrations/microsoft-365) guide.
## At a glance
| | Google Workspace | Microsoft 365 |
| - | - | - |
| How Cimento is authorized | Domain-wide delegation to a Google Cloud service account that Cimento creates for your organization | Admin consent to Cimento's Microsoft Entra application, **Cimento M365 DMI** |
| What you grant | Gmail API scopes `gmail.insert`, `gmail.readonly` and `gmail.modify` | Microsoft Graph `Mail.ReadWrite` as an application permission, plus `openid` for the consent sign-in |
| Who grants it | A Super Admin | A Global Administrator or Privileged Role Administrator, then an Exchange administrator to narrow it |
| Which mailboxes it reaches | Every user in your domain. Google can't limit delegation to specific users. | Every mailbox until you apply an Application Access Policy, then only the group you choose |
| Credentials you create or share | None | None |
## What Cimento does in a mailbox
Apart from the connection test, Cimento only works in the mailboxes of employees a campaign targets, one mailbox at a time, and only with the simulations it placed there and the threads they start. This is everything direct delivery does in a mailbox:
| When | What Cimento does |
| - | - |
| A simulation is due | Places the simulation in the employee's Inbox, unread |
| Until the simulation is opened | Checks whether that one message has been read |
| After delivery, on Google Workspace | Asks Gmail to report Inbox changes, and rereads the simulation's own thread to see whether the employee replied |
| The employee replies to a multi-turn simulation | Places the "attacker's" next message in the same thread |
| You click **Test connection** | Confirms that access works, without reading any messages |
The exact calls are listed under [Gmail API calls](#gmail-api-calls) and [Microsoft Graph calls](#microsoft-graph-calls).
Every simulation Cimento places carries an `X-Cimento` header. Cimento also uses that header to recognize its own simulations when an employee reports one.
### What direct delivery never does
* **Send email as your employees.** Simulations are placed in the mailbox, not sent, so they never leave the employee's account. Direct delivery makes no Gmail send or Microsoft Graph `sendMail` calls.
* **Search or read other mail.** Every read targets a simulation Cimento placed or the thread it started, either by ID or by a marker Cimento stamps on its own messages.
* **Change or remove messages.** Cimento doesn't edit, move, relabel or delete anything after delivery, including its own simulations.
* **Change mailbox settings.** Cimento doesn't touch forwarding, filters, rules, signatures or delegates.
Google's and Microsoft's descriptions of these permissions are broader than this list. The permission tables below say what each grant would allow; the list above is what Cimento actually does with it. Where a permission allows more than Cimento needs, the sections below explain why no narrower option exists.
## Replies in multi-turn simulations
A multi-turn simulation continues the conversation when an employee replies. This is the only time Cimento reads anything an employee wrote.
* Every simulation sets its Reply-To to an address whose mail Cimento receives, so a reply goes to Cimento rather than to the spoofed sender or any other third party.
* **Google Workspace:** Cimento also reads the simulation's thread in the mailbox, for up to 14 days after delivery. It reads the headers, labels and text of the messages in that thread to find the one the employee sent.
* **Microsoft 365:** Cimento reads the reply only from the copy sent to that Reply-To address. It doesn't read replies from the mailbox.
* Cimento keeps the reply's text, cut to 4,000 characters and encrypted with your tenant's key. It uses it to record how the employee responded and to write the next message.
## Google Workspace
### How Cimento is authorized
Cimento creates a Google Cloud service account for your organization in its own Google Cloud project, and the wizard shows its client ID. A Super Admin authorizes that client ID under **Security › Access and data control › API controls › Manage Domain Wide Delegation**, with the scopes below.
To act on a mailbox, Cimento signs a request with the service account's key and receives a token for that one mailbox, valid for an hour. The key never leaves Cimento. It is encrypted with a key unique to your tenant and replaced every 90 days.
Domain-wide delegation covers every user in your domain. Google has no setting to limit it to specific users, groups or organizational units: scopes limit the kind of data, not whose data. Cimento only opens the mailboxes of employees your campaigns target, plus the administrator account the connection test uses.
### If you already connected your Google directory
Your [employee directory](/getting-started/employee-directory) and direct delivery use the same service account, so both wizards show the same client ID. Google keeps one list of scopes per client ID. If the client ID is already listed under **Manage Domain Wide Delegation**, point to it, click **View details**, then **Edit**, and add the Gmail scopes next to the directory scopes that are already there. Replacing the entry with only one set of scopes turns off the other integration.
### Scopes and what each is used for
Each scope's full name starts with `https://www.googleapis.com/auth/`, for example `https://www.googleapis.com/auth/gmail.insert`.
| Scope | What Google says it allows | What Cimento uses it for |
| - | - | - |
| `gmail.insert` | Adding messages to a mailbox. It can't read, send or delete. | Placing each simulation in the Inbox, and placing multi-turn follow-ups in the simulation's thread |
| `gmail.readonly` | Reading all messages and settings | Checking whether a simulation was opened, asking Gmail to report Inbox changes, reading the simulation's thread to find a reply, and the connection test |
| `gmail.modify` | Reading, composing, sending and relabeling messages. It can't delete permanently. | Not used by direct delivery. The Phish Alert Button for Gmail uses it through the same service account: when an employee reports a message, Cimento reads it, sends a copy to your reporting inbox from that employee's account, and moves the original to Trash. |
Google matches each scope Cimento requests against this list exactly, so every scope has to be listed; a broader scope doesn't stand in for a narrower one.
Reply detection needs the text of the employee's reply, which the narrower `gmail.metadata` scope can't read. That is why direct delivery uses `gmail.readonly`.
### Gmail API calls
| What Cimento does | Call |
| - | - |
| Place a simulation | `users.messages.insert`, with the `INBOX`, `UNREAD` and `IMPORTANT` labels |
| Hear about Inbox changes | `users.watch` on the `INBOX` label. Each notification carries only the mailbox address and a change number. |
| Check whether a simulation was opened | `users.messages.get` by the simulation's ID. Only its labels are used. |
| Look for a reply | `users.threads.get` by the simulation's thread ID |
| Place a multi-turn follow-up | `users.messages.insert` into the simulation's thread, with the `INBOX` and `UNREAD` labels |
| Test connection | `users.getProfile` for the administrator account on file |
### What the connection test checks
**Test connection** requests a token with `gmail.readonly` only, for the administrator account on file for your organization, and reads that account's Gmail profile: its address and message counts. A pass shows that the delegation is in place and includes `gmail.readonly`. The test doesn't use `gmail.insert`, so before your first campaign, confirm under **View details** that every scope is listed.
Google can take up to 24 hours to apply a delegation change. If the test fails right after you authorized Cimento, wait and try again.
### Revoke access
* **To remove all of Cimento's Google access,** open **Manage Domain Wide Delegation**, point to Cimento's client ID and click **Delete**. Google says apps that depend on it stop working immediately. This also stops your directory sync if it uses the same client ID.
* **To remove only direct delivery,** edit the entry and delete the Gmail scopes, keeping the directory scopes.
* **Disconnecting in Cimento** stops deliveries. It doesn't change the delegation in Google, so remove that too.
## Microsoft 365
### How Cimento is authorized
Cimento runs one Microsoft Entra application, **Cimento M365 DMI**, that each customer consents to. When a Global Administrator or Privileged Role Administrator clicks **Grant admin consent** in the wizard, Microsoft adds the application to your tenant as an enterprise application and grants it the permissions below.
After that, Cimento requests tokens for your tenant with the OAuth client credentials flow, so nobody signs in. Cimento never stores a Microsoft password or user token. The application's secret stays with Cimento and is replaced every 180 days.
Other Cimento integrations that use Microsoft Entra have their own applications, so consenting to one never grants another's permissions.
On Microsoft's consent screen, select **Consent on behalf of your organization** before you click **Accept**. Without it, `Mail.ReadWrite` isn't granted and the connection test fails.
When Microsoft returns you to Cimento, it reports the integration as connected, but setup isn't finished. Go back to **Admin → Integrations → Phishing** to narrow access and test the connection.
### Permissions
| Permission | Type | What Microsoft says it allows | What Cimento uses it for |
| - | - | - | - |
| `Mail.ReadWrite` | Application | Creating, reading, updating and deleting mail in every mailbox, with no signed-in user. It doesn't include sending. The consent screen lists it as "Read and write all user mailboxes". | Placing simulations and multi-turn follow-ups in the Inbox, checking whether a simulation was read, and the connection test |
| `openid` | Delegated | Signing in | Used once, during consent: the sign-in tells Cimento your tenant ID, which it needs to request tokens for your tenant |
Why `Mail.ReadWrite` and not something narrower:
* It's the narrowest Microsoft Graph permission that can create a message in another user's mailbox. `Mail.Read` and `Mail.ReadBasic` can't write.
* `Mail.Send` would route simulations through Exchange mail flow, where your filters treat them like any inbound email, and it would let Cimento send as any user. Cimento doesn't request it.
* A delegated permission only reaches the signed-in user's own mailbox, so reaching each target takes an application permission.
* Checking whether a simulation was read only needs read access, but consent is granted per application, so one permission covers both.
### Microsoft Graph calls
| What Cimento does | Call |
| - | - |
| Place a simulation | `POST /users/{id}/mailFolders/inbox/messages` |
| Check whether a simulation was opened | `GET /users/{id}/messages/{messageId}`. Only `isRead` is used. |
| Place a multi-turn follow-up | `GET /users/{id}/messages`, filtered on a marker Cimento stamps on its own follow-ups so a retry never places the same message twice, then `POST /users/{id}/mailFolders/inbox/messages` |
| Test connection | `GET /users/{id}/mailFolders/inbox` for the mailbox you name |
### Narrow access to your simulation targets
Admin consent grants `Mail.ReadWrite` on every mailbox in your tenant, and Cimento treats the integration as connected as soon as consent completes. Until you apply the Application Access Policy below, Cimento can reach every mailbox. Apply it before you launch a campaign.
Add every employee you plan to target. Application Access Policies only accept security principals, so distribution lists and Microsoft 365 groups don't work.
The wizard shows it as **Application (client) ID**. You can also find it in the Microsoft Entra admin center: open **Enterprise applications**, search for **Cimento M365 DMI** and copy its **Application ID**.
In PowerShell with the ExchangeOnlineManagement module, signed in as an Exchange Administrator or Global Administrator, run:
```powershell theme={null}
Connect-ExchangeOnline
New-ApplicationAccessPolicy -AppId -PolicyScopeGroupId -AccessRight RestrictAccess -Description "Cimento simulation targets"
```
Test one mailbox inside the group and one outside it:
```powershell theme={null}
Test-ApplicationAccessPolicy -Identity -AppId
Test-ApplicationAccessPolicy -Identity -AppId
```
`AccessCheckResult` should read `Granted` for the first and `Denied` for the second. Only the `Denied` result proves the policy restricts Cimento.
Name a mailbox that belongs to the group and click **Test connection**. Policy changes can take up to 30 minutes to reach Microsoft Graph, so if the test fails right after you ran the commands, wait and try again.
Employees you add to the group later become reachable once the change applies. Simulations to employees outside the group fail, because Microsoft refuses the delivery.
Microsoft now recommends [RBAC for Applications](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac) for scoping mailbox access, and advises against creating new Application Access Policies. It doesn't work for this grant. RBAC for Applications assignments are added to permissions granted through Entra admin consent rather than restricting them, and Microsoft documents Application Access Policies as the only way to constrain an Entra-consented permission. A scoped role assignment on top of Cimento's consent adds a second grant and narrows nothing. If your organization requires RBAC for Applications, talk to your Cimento contact before you connect.
### What the connection test checks
**Test connection** requests a token for your tenant and reads the Inbox folder of the mailbox you named: folder details only, no messages. A pass means consent is in effect and Cimento can reach that mailbox. It can't show that other mailboxes are blocked; only `Test-ApplicationAccessPolicy` against a mailbox outside the group shows that. Cimento keeps the address so you can run the test again later.
### Revoke access
* **Remove the application.** In the Microsoft Entra admin center, open **Enterprise applications**, select **Cimento M365 DMI**, then **Properties** and **Delete**. This removes its permissions from your tenant. A token Cimento already holds keeps working until it expires, within 90 minutes.
* **Don't rely on removing the policy.** Removing the Application Access Policy on its own widens access: with no policy, Microsoft lets the application reach every mailbox again. Remove the application first.
* **Disconnecting in Cimento** stops deliveries. It doesn't remove the consent or the policy from your tenant.
## Related permissions that aren't part of direct delivery
* **Phish Alert Button for Gmail.** Uses `gmail.modify` on the same delegation, as described in the [scope table](#scopes-and-what-each-is-used-for).
* **Phish Alert Button for Outlook.** The add-in uses its own Entra application with delegated permissions, and acts only in the mailbox of the employee who clicks it. It is unrelated to `Mail.ReadWrite` and the Application Access Policy above.
* **Google Workspace employee directory.** Directory sync uses read-only Admin SDK scopes on the same Google service account. See [Employee directory](/getting-started/employee-directory).