API de Correos Reportados

¿Para qué sirve?

• Consultar, desde tus propios sistemas, los correos de phishing que tus colaboradores reportaron en Whalemate (botón de reporte, add-in de Outlook/Gmail, etc.) y sus analíticas agregadas.

¿Buscás enviar un reporte, no consultarlo? Esta API es de solo lectura, para leer reportes que ya existen en tu compañía. Para que un sistema externo (SIEM, botón de reporte propio, etc.) envíe un reporte de phishing hacia Whalemate, usá la External Phishing Reports API (api/external/reported-emails), que es un servicio distinto con su propia autenticación.

¿Cómo se implementa?

Base URL: todos los endpoints viven bajo el prefijo {{base_url}}/api/companies/v1.

Para obtener el host de producción (base_url), contacta a tu representante de Whalemate o escríbenos a través del chat de soporte.

Autenticación: header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

Genera o consulta tu clave desde Configuración → Integraciones → tarjeta Claves API → Claves Activas. Detalle en Claves API: cómo generarlas, usarlas y revocarlas.

La compañía se resuelve automáticamente a partir de la API Key: no envías company_id, y cada request opera únicamente sobre los correos reportados de tu compañía.

Endpoints

Listar correos reportados

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

Devuelve todos los correos que matchean los filtros, agrupados por status (no pagina).

Ejemplo Request:

GET {{base_url}}/api/companies/v1/reported-emails?filter[status]=received&filter[from_date]=2026-03-01

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

Los grupos vienen ordenados alfabéticamente por status (in_review, received, resolved), no por relevancia ni fecha. Dentro de cada grupo, los correos mantienen el orden interno de la plataforma (order).

Nota: si un correo todavía no tiene ningún registro de estado o categoría en su historial, el status/category de esa fila individual viene como cadena vacía ("") — a diferencia de la clave del grupo, que en ese caso cae en "received". En la práctica es un caso borde raro (todo reporte nuevo arranca con un estado), pero no asumas que el campo nunca viene vacío.

Analíticas de correos reportados

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

Devuelve un desglose semanal, un resumen y un desglose por estado.

Ejemplo Request:

GET {{base_url}}/api/companies/v1/reported-emails/analytics?filter[from_date]=2026-01-01&filter[to_date]=2026-03-31

Respuesta (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: una entrada por cada semana con al menos un reporte (semana de lunes a domingo), ordenadas de más antigua a más reciente. summary.average_per_week es total_emails / total_weeks, redondeado a 2 decimales. status_breakdown es el total acumulado por estado en todo el período consultado (no por semana).

Errores comunes

Ejemplo cURL

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"

❓ Preguntas frecuentes

• ¿Esta API sirve para enviar un reporte de phishing? No. Este endpoint es de solo lectura. Para enviar reportes desde un sistema externo usá la External Phishing Reports API.

• ¿Viene paginado el listado? No, devuelve todos los correos que matchean el filtro, agrupados por estado.

• ¿En qué zona horaria vienen las fechas? En UTC, igual que el resto de la Company API.

• ¿Qué significa order? Es el orden interno con el que la plataforma lista los reportes dentro de cada estado; no representa prioridad ni antigüedad.

• ¿Dónde consigo mi API Key? En Configuración → Integraciones → tarjeta Claves API → Claves Activas.

¿Tienes feedback o quieres solicitar mejoras? Háznoslo saber en roadmap.whalemate.com/roadmap