Reported Mail API

What is it for?

• Query, from your own systems, the phishing emails that your collaborators reported in Whalemate (report button, Outlook/Gmail add-in, etc.) and their aggregated analytics.

Looking to send a report, not query it? 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 send a phishing report to Whalemate, use the External Phishing Reports API (api/external/reported-emails), which is a different service with its own authentication.

How is it implemented?

Base URL: all endpoints live under the prefix {{base_url}}/api/companies/v1.

To get the production host (base_url), contact your Whalemate representative or write to us through the support chat.

Authentication: header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

Generate or check your key from Configuración → Integraciones → Claves API card → Claves Activas. Details in Claves API: cómo generarlas, usarlas y revocarlas.

The company is resolved automatically from the API Key: you don't send company_id, and each request operates only on your company's reported emails.

Endpoints

List reported emails

GET {{base_url}}/api/companies/v1/reported-emails

Returns all emails that match the filters, grouped by status (not paginated).

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": []
    }
  ]
}

The groups come sorted alphabetically by status (in_review, received, resolved), not by relevance or date. Within each group, the emails keep the platform's internal order (order).

Note: if an email doesn't yet have any status or category record in its history, the status/category of that individual row comes as an empty string (""), unlike the group key, which in that case falls into "received". In practice this is a rare edge case (every new report starts with a status), but don't assume the field never comes empty.

Reported emails analytics

GET {{base_url}}/api/companies/v1/reported-emails/analytics

Returns a weekly breakdown, a summary, and a breakdown by status.

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 most recent. summary.average_per_week is total_emails / total_weeks, rounded to 2 decimals. status_breakdown is the accumulated total by status across the entire queried period (not per week).

Common errors

cURL example

curl -X GET "https://api.whalemate.io/api/companies/v1/reported-emails?filter[status]=received" \
  -H "X-API-KEY: tu_api_key_aqui" -H "Accept: application/json"

❓ Frequently asked questions

• Does this API let me send a phishing report? No. This endpoint is read-only. To send reports from an external system use the External Phishing Reports API.

• Is the listing paginated? No, it returns all emails that match the filter, grouped by status.

• What time zone are the dates in? UTC, same as the rest of the Company API.

• What does order mean? It's 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