What is it for?
Query, from your own systems, the phishing emails your employees reported in Whalemate (report button, Outlook/Gmail add-in, etc.) and their aggregated analytics.
Get the full detail of each report, including headers, attachments, links and the original message, to analyze it with your own tools (sandbox, SIEM, automations).
Looking to submit a report, not read one? This API is read-only, for reading reports that already exist in your company. For an external system (SIEM, your own report button, etc.) to submit a phishing report to Whalemate, use the External Phishing Reports API (
api/external/reported-emails), which is a separate service with its own authentication.
How is it implemented?
Base URL: the endpoints live under {{base_url}}/api/companies/v2 (paginated list and detail) and {{base_url}}/api/companies/v1 (grouped list, deprecated, and analytics).
To get the production host (
base_url), contact your Whalemate representative or write to us through the support chat.
Authentication: X-API-KEY header.
X-API-KEY: tu_api_key_de_empresa
Generate or look up your key from Configuración → Integraciones → Claves API card → Claves Activas. Details in API Keys: how to generate, use and revoke them.
The company is resolved automatically from the API Key: you don't send company_id, and each request only operates on your company's reported emails.
Header | Value | Required |
|---|---|---|
| Your company API Key | ✅ Yes |
|
| ✅ Yes |
List filters
Both lists (v2 and v1) accept the same filters. Filters that accept several values take them separated by commas.
Param | Type | Description |
|---|---|---|
| string |
|
| string |
|
| string | Exact email(s) of the reporter |
| string | Exact email(s) of the suspicious sender ( |
| string | Partial match in the subject |
| string | Partial match in the full message ( |
| date (YYYY-MM-DD) |
|
| date (YYYY-MM-DD) |
|
Endpoints
List reported emails, paginated (v2)
GET {{base_url}}/api/companies/v2/reported-emails
The reports that match the filters, as a flat paginated list. This is the recommended list.
Param | Type | Default | Description |
|---|---|---|---|
| integer |
| Results per page, from |
| integer |
| Page number |
The order is the same as the v1 groups, so that going through the pages gives the same sequence: first by status (in_review, received, resolved; reports with no status count as received), then by order, then by id.
Example request:
GET {{base_url}}/api/companies/v2/reported-emails?filter[status]=received,in_review&per_page=50
Response (200 OK):
{
"data": [
{
"id": 501,
"from": "Banco Nacional",
"email_from": "[email protected]",
"subject": "Urgente: confirma tu cuenta",
"status": "in_review",
"reported_at": "2026-03-10 09:15:00",
"reported_by": "[email protected]",
"category": "unknown",
"order": 3
}
],
"links": [ ... ],
"meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 120 }
}meta also has the page URLs, which keep the request's filters.
Detail of a reported email (v2)
GET {{base_url}}/api/companies/v2/reported-emails/{id}
Returns one report from your company with everything the list doesn't include: headers, attachments, links and the original message. Attachments weigh whatever the file weighs, so they are requested one report at a time.
Param | Type | Description |
|---|---|---|
| integer | Report ID (path param), the same |
Suggested flow to process new reports:
GET /api/companies/v2/reported-emails?filter[from_date]=<fecha de tu última consulta>, going through the pages.For each new
id,GET /api/companies/v2/reported-emails/{id}.
Response (200 OK):
{
"id": 5412,
"from": "Mesa de Ayuda",
"email_from": "[email protected]",
"subject": "Factura pendiente",
"status": "received",
"category": "unknown",
"reported_at": "2026-10-05 10:00:00",
"reported_by": "[email protected]",
"send_date": "2026-10-05 09:58:12",
"headers": [
{ "name": "Received", "value": "from mail.dominio-falso.com ..." },
{ "name": "Subject", "value": "Factura pendiente" },
{ "name": "Received", "value": "from relay.example ..." }
],
"attachments": [
{ "name": "factura.pdf", "contentType": "application/pdf", "content": "JVBERi0xLjQK..." }
],
"links": ["https://dominio-falso.com/pago"],
"raw_message": "Received: from mail.dominio-falso.com ...\r\n..."
}Field | Type | Description |
|---|---|---|
| - | Same as in the list |
| string | Current status; |
| string | Current category; |
| string | Date of the report ( |
| string | null | Email of the reporter |
| string | null | Send date of the original email |
| array of | Email headers, in order. Repeated ones (like |
| array | Attachments as they were received. Empty list if there are none. Their shape depends on the report source (see below) |
| array | null | Links found in the email |
| string | null | The original message as it was received |
What attachments and raw_message contain, depending on how the email was reported:
Report source |
| Includes the file? |
|
|---|---|---|---|
Gmail button |
| ✅ Yes | The full message (RFC 822 format), with all its headers |
Outlook button | one text string per attachment, with its name and type | ❌ No | The email body |
External Phishing Reports API |
| ❌ No | What your integration sent |
In reports made with the Gmail button, headers that take more than one line (
Received,DKIM-Signature,Authentication-Results) may come truncated inheaders.raw_messagehas them complete: to analyze headers, it is the most faithful source.
An id that doesn't exist and one from another company get the same response, 404.
List reported emails, grouped by status (v1, deprecated)
GET {{base_url}}/api/companies/v1/reported-emails
Deprecated. Replaced by the paginated list in v2. It still responds as it always has; once it has a retirement date, each response announces it in the
DeprecationandSunsetheaders, along with aLinkheader that points to the replacement. If you are building a new integration, use v2.
Returns all the emails that match the filters, grouped by status. It doesn't paginate: it ignores page and per_page.
Example request:
GET {{base_url}}/api/companies/v1/reported-emails?filter[status]=received&filter[from_date]=2026-03-01
Response (200 OK):
{
"data": [
{
"status": "in_review",
"reported_emails": [
{
"id": 501,
"from": "Banco Nacional",
"email_from": "[email protected]",
"subject": "Urgente: confirma tu cuenta",
"status": "in_review",
"reported_at": "2026-03-10 09:15:00",
"reported_by": "[email protected]",
"category": "unknown",
"order": 3
}
]
},
{
"status": "received",
"reported_emails": []
},
{
"status": "resolved",
"reported_emails": []
}
]
}Groups come sorted alphabetically by status (in_review, received, resolved), not by relevance or date. Within each group, emails keep the platform's internal order (order).
Note: if an email has no status or category record yet in its history, the
status/categoryof that individual row comes as an empty string (""). The group key is different: in that case it falls under"received". In practice this is a rare edge case (every new report starts with a status), but don't assume the field is never empty.
Reported emails analytics
GET {{base_url}}/api/companies/v1/reported-emails/analytics
Returns a weekly breakdown, a summary and a breakdown by status. It doesn't paginate and it isn't deprecated.
Param | Type | Description |
|---|---|---|
| date (YYYY-MM-DD) |
|
| date (YYYY-MM-DD) |
|
Example request:
GET {{base_url}}/api/companies/v1/reported-emails/analytics?filter[from_date]=2026-01-01&filter[to_date]=2026-03-31
Response (200 OK):
{
"data": [
{
"week_start": "2026-03-02",
"week_end": "2026-03-08",
"total_emails": 12,
"total_received": 5,
"total_in_review": 3,
"total_resolved": 4,
"categories": { "unknown": 6, "spam": 4, "threat": 2 },
"statuses": { "received": 5, "in_review": 3, "resolved": 4 }
}
],
"summary": {
"total_weeks": 8,
"total_emails": 96,
"average_per_week": 12.0
},
"status_breakdown": { "received": 20, "in_review": 30, "resolved": 46 }
}data: one entry for each week with at least one report (week from Monday to Sunday), sorted from oldest to newest. summary.average_per_week is total_emails / total_weeks, rounded to 2 decimals. status_breakdown is the accumulated total by status over the whole queried period (not per week).
Common errors
Code | Cause | Body |
|---|---|---|
| Missing |
|
| Nonexistent/revoked API Key |
|
| The detail |
|
|
|
|
cURL example
curl -X GET "https://api.whalemate.io/api/companies/v2/reported-emails?filter[status]=received&per_page=50" \
-H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"curl -X GET "https://api.whalemate.io/api/companies/v2/reported-emails/5412" \
-H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"❓ Frequently asked questions
Can this API be used to submit a phishing report? No. This endpoint is read-only. To submit reports from an external system, use the External Phishing Reports API.
Is the list paginated? The v2 one is (20 per page by default, up to 100). The v1 one isn't: it returns everything grouped by status, and it is deprecated.
Why doesn't the list include attachments or headers? Because attachments weigh whatever the file weighs and would make the list unmanageable. Request the detail of each report with
GET /api/companies/v2/reported-emails/{id}.I requested the detail and the attachment doesn't include the file. It depends on how the email was reported: the full file only comes in reports made with the Gmail button. In those from the Outlook button and from the External Phishing Reports API, you get the name and type of the attachment.
A
Receivedheader appears cut off. This happens in Gmail button reports with multi-line headers. Read it fromraw_message, which has it complete.What time zone are the dates in? UTC, like the rest of the Company API.
What does
ordermean? It is the internal order the platform uses to list reports within each status. It doesn't represent priority or age.Where do I get my API Key? In
Configuración → Integraciones→ Claves API card → Claves Activas.
Have feedback or want to request improvements? Let us know at roadmap.whalemate.com/roadmap
