> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/email-providers/email-providers.md).

# Email Providers

Connect Herd to your organization's mail provider so that when users report a phishing simulation, Herd credits them with the report in your campaign results.

When users report a Herd phishing simulation using their mail client's built-in **Report phishing** button, Herd can detect that report and credit them in your campaign results. This is configured per provider in the Herd admin console under **Settings → Integrations** — the **Gmail** and **Microsoft Outlook** cards in the **Email** section are separate tiles, each with its own setup and its own **Connected** badge.

<figure><img src="https://2286452423-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNdsHrfHsFuaMzCbOD5q%2Fuploads%2Fgit-blob-de2a25ec42d6c576180a30e67024971bf638b844%2Femail-providers.jpeg?alt=media" alt="The Email Providers section in Herd Settings, showing the Gmail (Google Workspace) tile expanded with an Enable polling button."><figcaption><p>Settings → Email Providers</p></figcaption></figure>

## Choose your provider

Both providers can be enabled side by side.

* [**Detecting Phishing Reports From Gmail**](/herd-security-docs/email-providers/email-providers/gmail.md) — for Google Workspace organizations. Reuses the service account from your existing [Google Workspace](/herd-security-docs/google-workspace/google-workspace.md) directory-sync setup; you grant one additional read-only Gmail scope.
* [**Detecting Phishing Reports From Outlook (Microsoft 365)**](/herd-security-docs/email-providers/email-providers/outlook.md) — for Microsoft 365 organizations. A tenant administrator consents to Herd's existing Azure application once; there is no Azure portal configuration on your side. Herd reads the reports users make with Outlook's **Report** button from Microsoft Defender, and never reads mailboxes.

## How report detection works (in brief)

The two providers detect reports differently:

* **Gmail** — after Herd sends a simulation, it checks each recipient's mailbox through the Gmail API. When the user clicks **Report phishing** (or **Report spam**), Gmail moves the message out of the inbox, and Herd marks the simulation as **Reported** on its next polling cycle, typically within 5 minutes. Herd reads only labels and a small set of forwarding-related headers on the messages it sent, and only for simulations sent in the last 30 days.
* **Outlook (Microsoft 365)** — when the user clicks **Report**, Microsoft Defender records a user submission. Every 5 minutes Herd reads those submissions, matches them to its simulations (by the reporting mailbox and subject, or the Message-ID when Microsoft includes it), and marks the simulation as **Reported**. Herd reads submission metadata only, not mailboxes.

Common to both:

* **Read-only.** Herd never sends mail, modifies messages, or deletes anything.
* **Reports require user action.** A simulation is credited only when *the user* reports it. Auto-classification by the provider's spam filter (where the user never saw the message) does **not** count.

Provider-specific setup steps, exact permission scopes, and troubleshooting live on the [Gmail](/herd-security-docs/email-providers/email-providers/gmail.md) and [Outlook](/herd-security-docs/email-providers/email-providers/outlook.md) pages.

## Security Alert Automations (Beta)

Everything above is about *your Herd simulations*. Separately, Herd can poll your provider's **real** security alerts — including the ones raised when an employee reports a genuine suspicious email — and act on them: notify the people you choose, auto-assign a training, and turn a real attack into a follow-up simulation.

* **Gmail (Google Workspace)** — Herd polls the Google Workspace **Alert Center**, using the `apps.alerts` domain-wide delegation scope.
* **Outlook (Microsoft 365)** — Herd polls **Microsoft 365 Defender** alerts via the Microsoft Graph `alerts_v2` API, using the `SecurityAlert.Read.All` application permission.

This is self-serve and entirely opt-in: alert polling, notifications and automations are each off until you turn them on, from the **Security Alert Automations** card under **Settings → Integrations**.

* [**Security Alert Automations**](/herd-security-docs/email-providers/email-providers/security-alert-automations.md) — permissions, setup, alert types, and what Herd does with a reported phishing email.