Does your organization use Microsoft 365 (Exchange Online)? This guide is not for you. Use the guide "Phishing Report for Microsoft (Outlook)". The installation file for that version does not work on your own Exchange.
Introduction
The Phishing report button for Outlook On-Premise lets users report suspicious emails directly from Outlook in organizations that use their own Exchange Server (on-premise) and not Microsoft 365 or Exchange Online.
When a user reports an email, Whalemate saves it for analysis and, if the organization has security mailboxes set up, sends them a notice.
What is it for?
Let users report suspicious emails directly from Outlook.
Centralize phishing reports within the awareness program.
Make it easier for the security team to analyze incidents.
Connect phishing reporting with internal tools such as SOC or SIEM.
How is it installed?
An Exchange administrator does the installation, once. The button becomes available to the users you choose.
What you need
The file onpromise_manifest.xml: download it here. It is the only file you install. Do not open it or save it with another program.
Exchange Server 2016 or 2019 (it also works on 2013), with the Exchange Admin Center or the Exchange Management Shell.
A user with the Organization Management role.
Users with classic Outlook for desktop 2013 or later, or Outlook on the web (OWA) on the server. The new Outlook for Windows does not support Exchange on-premise mailboxes, so those users do not see the button.
User computers must be able to reach the internet for the domains in the table below.
Domains that must be allowed
Domain | What it is used for |
|---|---|
whalemate-phishing-microsoft.vercel.app | Button screen and its logic |
back.whalemate.com | Receiving the reported emails |
appsforoffice.microsoft.com | Office add-in library |
res-1.cdn.office.net | Office visual styles |
alcdn.msauth.net | Microsoft library that loads the screen |
whalemate-prod-files.s3.us-east-1.amazonaws.com | Button icon |
If a proxy or firewall filters outgoing traffic, these domains must be enabled over HTTPS (port 443). If any of them is blocked, the button does not appear or cannot send the report.
Installing from the Exchange Admin Center
Sign in to the Exchange Admin Center (for example,
https://tu-servidor/ecp) with the administrator user.Go to Organization and then to Add-ins.
Click the + icon and choose Add from file.
Select the file
onpromise_manifest.xmland click Install.When "Reportar Phishing" appears in the list, select it and click Edit.
Check Make this add-in available to users in your organization and choose Mandatory, always enabled. This way users cannot turn it off.
Save the changes.
Menu names may vary a little depending on the Exchange version and language.
Installing from PowerShell
This is an alternative to the previous step. In the Exchange Management Shell, with the file copied to the server:
Install for the whole organization:
New-App -OrganizationApp -FileData ([System.IO.File]::ReadAllBytes("C:\ruta\onpromise_manifest.xml")) -ProvidedTo Everyone -DefaultStateForUser AlwaysEnabledInstall for only some users (useful for a pilot test):
New-App -OrganizationApp -FileData ([System.IO.File]::ReadAllBytes("C:\ruta\onpromise_manifest.xml")) -ProvidedTo SpecificUsers -UserList "[email protected]","[email protected]" -DefaultStateForUser EnabledCheck that it is installed:
Get-App -OrganizationApp | Where-Object {$_.DisplayName -eq "Reportar Phishing"}That same command shows the add-in identifier (AppId). You use it with Set-App or Remove-App if you later need to change who it is assigned to or uninstall it.
Check that it works
With an assigned user, close and reopen Outlook. The button can take a while to appear after installation.
Open any received email. In desktop Outlook, the "Reportar Phishing" add-in appears in the add-in bar above the body of the email. In Outlook on the web, it appears in the message actions menu.
Click Reportar Phishing. The button shows "Reportando..." and then a message.
Tell your Whalemate contact which email you reported, with the time and the user, so they can confirm it arrived in the platform. That confirmation is the proof that counts: today the message the user sees does not always show whether the report arrived (see "Common problems").
What it does and does not do on Exchange on-premise
This version works without Microsoft Graph, which is not available for Exchange Server mailboxes. That is why it does less than the Microsoft 365 version:
What is sent to Whalemate: sender, subject, date, email text and links. The technical headers, the attachments and the full original email are not sent.
Notice to security mailboxes: if the organization has mailboxes set up to receive reports, Whalemate sends them a notice with the data of the reported email, but without the original email attached.
Junk email: the button does not move or delete the reported email. The user has to move it by hand, and the confirmation screen tells them so. It also cannot be deleted from the SIEM.
Phishing simulations: reports of emails from a Whalemate simulation are recorded as reported emails, but they are not added to the campaign results. Also, the message that tells the user it was a simulation does not appear in every campaign.
Messages: the texts the user sees are in Spanish only and do not use the custom texts the organization may have set up in Whalemate.
User identification: the report is identified by the mailbox email, with no sign-in.
Common problems
What happens | What to check |
|---|---|
The button does not appear | That the user is included in the assignment, that they use classic Outlook or Outlook on the web, that some time has passed since installation and that Outlook has been restarted. Also that |
The add-in screen stays blank | That the domains in the requirements table are not blocked by the proxy or the firewall. |
"Error al reportar el correo" appears | There is a known error, already reported, that can make this message appear even if the report arrived fine. Before checking the network, ask your Whalemate contact whether the report is in the platform. If it did not arrive, check that |
Exchange rejects the file when installing it | That |
Compatibility
Platform / Client | On-Premise add-in | Add-in with MSAL (M365) |
|---|---|---|
Outlook Windows 2010 or earlier | ❌ Not compatible | ❌ Not compatible |
Outlook 2013 (SP1) | ✅ Compatible | ❌ Not compatible |
Outlook 2016 | ✅ Compatible | ✅ Compatible |
Outlook 2019 | ✅ Compatible | ✅ Compatible |
Outlook 2021 | ✅ Compatible | ✅ Compatible |
Microsoft 365 classic Outlook (Windows) | ✅ Compatible | ✅ Compatible |
New Outlook for Windows | ❌ Not compatible with on-premise mailboxes | ✅ Compatible (Microsoft 365 mailboxes only) |
Outlook on the Web (OWA) | ✅ Compatible | ✅ Compatible |
Outlook Mac (Office 2016+) | ❌ Not compatible | ✅ Compatible |
Windows Mail / Windows 10-11 Mail | ❌ Not compatible | ❌ Not compatible |
Apple Mail / Generic POP-IMAP clients | ❌ Not compatible | ❌ Not compatible |
Technical information
General architecture
The add-in is a simple client-server architecture, with no dependencies on Microsoft cloud services. There are no intermediate components or third-party services.
Outlook Add-in (client): Office Add-in (MailApp) with Task Pane, built with Office.js, that runs in the Outlook client.
Whalemate backend (server): receives the report over HTTPS.
The add-in is triggered by a manual user action ("Reportar Phishing") on a selected email, and only accesses what Office.context.mailbox.item exposes:
Sender email address and domain
Email address of the reporting user
Date and time of the report and of when the suspicious email was sent
Email body (HTML and plain text)
Links in the body
Because of the on-premise context, the add-in has no access to the full headers or the attachments, and it does not use Microsoft Graph, Azure AD / MSAL or strong identity tokens. That is why it cannot link the report to earlier campaigns based on custom headers.
Receiving endpoint
POST https://back.whalemate.com/api/public/reported-email-microsoft-webhookWhen it receives a report, the backend records the event, stores the email information, shows it in the Whalemate SIEM interface and sends a notice to the security mailboxes set up by the organization.
[Usuario]
|
v
[Outlook On-Prem]
|
| Office Add-in (Office.js)
v
[Botón Report Phishing]
|
| HTTPS POST
v
[Backend Whalemate]
|
+--> SOC / UI
+--> Aviso a casillas configuradasSecurity considerations
The add-in does not run native code on the client.
It does not store information locally.
Communication is done only over HTTPS.
No Microsoft credentials or authentication tokens are used.
Data access is limited to the email the user selected.
❓ Frequently asked questions
What information is sent when a user reports an email?
Sender and their domain, email of the reporting user, date and time of the report and of when it was sent, email body and links. Full headers and attachments are not included, because those functions are not available without Microsoft Graph.
Are reports always linked to a phishing campaign?
No. In this version the button cannot read the email headers, and that is where Whalemate stores the campaign identification. The report is recorded, but it is not associated with the campaign and does not show as "Reported" in its results.
Can the button delete the reported email from the user's inbox?
No. In this version the button cannot run actions on the mailbox: it does not delete emails or move them to junk. That function requires Microsoft Graph or Exchange Online.
