> 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 under **Settings → Integrations → Email Providers** in the Herd admin console.
Settings → Integrations → Email Providers
## 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 under **Settings → Integrations → Email Providers**, and let your Herd contact know if you'd like it turned on for your organization.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://herd-security.gitbook.io/herd-security-docs/email-providers/email-providers.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.