Reported Mail API

Para que serve?

• Consultar, a partir dos seus próprios sistemas, os e-mails de phishing que seus colaboradores reportaram no Whalemate (botão de reporte, add-in do Outlook/Gmail, etc.) e suas analíticas agregadas.

Você quer enviar um reporte, não consultá-lo? Esta API é somente leitura, para ler reportes que já existem na sua empresa. Para que um sistema externo (SIEM, botão de reporte próprio, etc.) envie um reporte de phishing para o Whalemate, use a External Phishing Reports API (api/external/reported-emails), que é um serviço distinto com sua própria autenticação.

Como se implementa?

Base URL: todos os endpoints vivem sob o prefixo {{base_url}}/api/companies/v1.

Para obter o host de produção (base_url), entre em contato com seu representante do Whalemate ou escreva para nós através do chat de suporte.

Autenticação: header X-API-KEY.

X-API-KEY: tu_api_key_de_empresa

Gere ou consulte sua chave em Configuração → Integrações → cartão Claves API → Claves Activas. Detalhes em Claves API: cómo generarlas, usarlas y revocarlas.

A empresa é resolvida automaticamente a partir da API Key: você não envia company_id, e cada request opera apenas sobre os e-mails reportados da sua empresa.

Endpoints

Listar e-mails reportados

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

Retorna todos os e-mails que correspondem aos filtros, agrupados por status (não pagina).

Exemplo Request:

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

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

Os grupos vêm ordenados alfabeticamente por status (in_review, received, resolved), não por relevância nem data. Dentro de cada grupo, os e-mails mantêm a ordem interna da plataforma (order).

Nota: se um e-mail ainda não tem nenhum registro de status ou categoria em seu histórico, o status/category dessa linha individual vem como string vazia (""), diferente da chave do grupo, que nesse caso cai em "received". Na prática é um caso extremo raro (todo reporte novo começa com um status), mas não assuma que o campo nunca vem vazio.

Analíticas de e-mails reportados

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

Retorna um detalhamento semanal, um resumo e um detalhamento por status.

Exemplo Request:

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

Resposta (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: uma entrada para cada semana com pelo menos um reporte (semana de segunda a domingo), ordenadas da mais antiga para a mais recente. summary.average_per_week é total_emails / total_weeks, arredondado a 2 casas decimais. status_breakdown é o total acumulado por status em todo o período consultado (não por semana).

Erros comuns

Exemplo 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"

❓ Perguntas frequentes

• Esta API serve para enviar um reporte de phishing? Não. Este endpoint é somente leitura. Para enviar reportes de um sistema externo use a External Phishing Reports API.

• A listagem vem paginada? Não, retorna todos os e-mails que correspondem ao filtro, agrupados por status.

• Em qual fuso horário vêm as datas? Em UTC, igual ao restante da Company API.

• O que significa order? É a ordem interna com a qual a plataforma lista os reportes dentro de cada status; não representa prioridade nem antiguidade.

• Onde consigo minha API Key? Em Configuração → Integrações → cartão Claves API → Claves Activas.

Tem feedback ou quer solicitar melhorias? Nos avise em roadmap.whalemate.com/roadmap