> 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

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="/files/F3gSHMAeyjCUJBH11TUD" 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 — Herd polls each user's mailbox via the appropriate integration based on their domain.

* [**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.

## How report detection works (in brief)

After Herd sends a phishing simulation, it periodically checks each recipient's mailbox via the provider API to see what happened to that specific message. When the user clicks **Report phishing** (or **Report spam** / **Report Junk**), the mail provider moves the message out of the inbox. Herd detects that move on its next polling cycle — typically within 5 minutes — and marks the simulation as **Reported** for that user.

A few things common to both providers:

* **Read-only.** Herd reads message metadata (labels/folder placement and a small set of forwarding-related headers) on the specific messages it sent. It never reads general message bodies, sends mail, modifies messages, or deletes anything.
* **Recent campaigns only.** Herd polls mailboxes for simulations sent in the last 30 days. Older campaigns are not re-checked.
* **Reports require user action.** A simulation is only credited as reported when *the user* moves it out of the inbox. Auto-classification by the provider's spam filter (where the user never saw the message) does **not** count.
* **Backfill is automatic.** Once you turn polling on, every simulation in the last-30-day window becomes pollable on the next cycle — including reports users had already filed before you enabled this.
* **Recipients must be in your domain/tenant.** Polling is scoped to the domain (Gmail) or tenant (Outlook) you connected. External recipients are not polled.

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.

## Provider Security Alerts (Beta)

Beyond crediting phishing-simulation reports, Herd can also poll your mail provider's **security alerts** so real-world threats your provider flags become visible in Herd. This is a beta capability that you enable per provider.

* **Gmail (Google Workspace)** — Herd polls the Google Workspace **Alert Center** for security alerts.
* **Outlook (Microsoft 365)** — Herd polls **Microsoft 365 Defender** alerts via the Microsoft Graph `alerts_v2` API. This requires the tenant to consent to the `SecurityAlert.Read.All` application permission.

{% hint style="info" %}
Provider Security Alerts is in **beta**. Enable alert polling per provider from the **Security Alert Automations** card under **Settings → Integrations**, and let your Herd contact know if you'd like it turned on for your organization.
{% endhint %}