Docs / 🇧🇷 Documentação Técnic

🇧🇷 External Phishing Reports API

API pública para reportar e-mails de phishing a partir de sistemas externos.

Introdução

Esta API permite integrar o reporte de phishing da Whalemate aos seus próprios sistemas, como:

Botões personalizados em clientes de e-mail
Integrações com SIEM corporativo
Ferramentas internas de segurança
Workflows automatizados

Autenticação

Obter API Key

Acesse sua conta Whalemate
Vá em Configurações → Integrações → API Keys
Clique em Gerar nova API Key
Copie a key (ela é exibida apenas uma vez)

Usar API Key

Inclua a API Key em cada request usando o header:

X-API-KEY: sua_api_key_de_60_caracteres_aqui

⚠️ Importante:
Não compartilhe sua API Key publicamente
Faça a rotação da key periodicamente pela UI
Se a key for comprometida, revogue-a imediatamente

Endpoint

Criar reporte de phishing

POST /api/external/reported-emails

Headers

Header	Valor	Obrigatório
X-API-KEY	Sua API Key	✅ Sim
Content-Type	application/json	✅ Sim
Accept	application/json	✅ Sim

Body (JSON)

Campos obrigatórios

Campo	Tipo	Descrição
reported_by	string (email)	E-mail do usuário que reporta o phishing
email_from	string (email)	E-mail do remetente suspeito
subject	string (máx 500)	Assunto do e-mail reportado
send_date	string (ISO 8601)	Data de envio do e-mail suspeito

Campos opcionais

Campo	Tipo	Descrição
from	string	Nome do remetente. Se não enviado, será usado `email_from`
message_preview	string	Primeiros ~200 caracteres da mensagem
raw_message	string	Mensagem completa em formato RFC822 ou HTML
headers	array	Headers do e-mail
links	array	URLs encontradas no e-mail
attachments	array	Metadados dos anexos

Estrutura de headers

[{
    "name": "Return-Path",
    "value": "<[email protected]>"},{
    "name": "Received",
    "value": "from mail.example.com by mx.google.com..."}]

Estrutura de attachments

[{
    "name": "invoice.pdf",
    "contentType": "application/pdf",
    "size": 12345}]

Nota: O conteúdo do anexo não é enviado, apenas os metadados.

Exemplo completo

{"reported_by": "[email protected]","email_from": "[email protected]","from": "Banco Nacional","subject": "Urgente: Confirme sua conta","send_date": "2026-01-19T10:30:00Z","message_preview": "Prezado cliente, detectamos atividade suspeita...","raw_message": "Content-Type: text/html; charset=UTF-8\n\n<html>...","headers": [
    {
      "name": "Return-Path",
      "value": "<[email protected]>"
    },
    {
      "name": "X-Mailer",
      "value": "PhishMailer 2.0"
    }],"links": [
    "https://suspicious-domain.com/confirm-account?token=abc123",
    "https://evil-tracker.com/pixel.gif"],"attachments": [
    {
      "name": "documento_importante.pdf",
      "contentType": "application/pdf",
      "size": 45678
    }]}

Respostas

Sucesso (201 Created)

{"success": true,"data": {
    "id": 12345,
    "reported_at": "2026-01-19T14:30:00Z",
    "status": "received",
    "category": "unknown",
    "source": "external_api"},"message": "Phishing report successfully registered"}

Erro – API Key ausente (401 Unauthorized)

{ "error": "API Key required" }

Erro – API Key inválida (403 Forbidden)

{ "error": "Invalid API Key" }

Erro – Usuário não existe (422 Unprocessable Entity)

{"success": false,"message": "The reporting user does not exist or does not belong to this company","errors": {
    "reported_by": [
      "The reporting user does not exist or does not belong to this company"
    ]}}

Erro – Validação (422 Unprocessable Entity)

{"message": "The given data was invalid.","errors": {
    "email_from": ["The email from field is required."],
    "subject": ["The subject field is required."],
    "send_date": ["The send date field is required."]}}

Erro – Erro interno do servidor (500 Internal Server Error)

{"success": false,"message": "Internal error processing the report"}

Erro – Rate limit (429 Too Many Requests)

{"message": "Too Many Attempts.","retry_after": 60}

Rate Limiting

Limite: 100 requests por minuto por API Key
Reset: A cada minuto
Header de resposta: X-RateLimit-Remaining

Se o limite for excedido, a API retornará erro 429.
Aguarde o tempo indicado em retry_after (em segundos).

Exemplos de integração

cURL

curl -X POST https://api.whalemate.io/api/external/reported-emails \
  -H "X-API-KEY: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reported_by": "[email protected]",
    "email_from": "[email protected]",
    "subject": "Você ganhou um prêmio",
    "send_date": "2026-01-19T10:30:00Z",
    "links": ["https://phishing-site.com/click"]
  }'

JavaScript (Fetch)

const reportPhishing = async (emailData) => {
  const response = await fetch(
    'https://api.whalemate.io/api/external/reported-emails',
    {
      method: 'POST',
      headers: {
        'X-API-KEY': 'sua_api_key_aqui',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify({
        reported_by: emailData.userEmail,
        email_from: emailData.senderEmail,
        subject: emailData.subject,
        send_date: emailData.date,
        raw_message: emailData.fullMessage,
        links: emailData.extractedLinks
      })
    }
  );

  const result = await response.json();

  if (response.ok) {
    console.log('Reporte enviado:', result.data.id);
  } else {
    console.error('Erro:', result.message);
  }
};

Python (requests)

import requests
from datetime import datetime

def report_phishing(user_email, sender_email, subject, send_date, **kwargs):
    url = 'https://api.whalemate.io/api/external/reported-emails'
    headers = {
        'X-API-KEY': 'tu_api_key_aqui',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }

payload = {
    'reported_by': user_email,
    'email_from': sender_email,
    'subject': subject,
    'send_date': send_date.isoformat(),
    **kwargs  # message_preview, links, etc.
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 201:
    data = response.json()
    print(f"Reporte creado: ID {data['data']['id']}")
    return data['data']['id']
else:
    print(f"Error: {response.json()}")
    return None

# Uso
report_phishing(
    user_email='[email protected]',
    sender_email='[email protected]',
    subject='Email sospechoso',
    send_date=datetime.now(),
    links=['https://phishing.com/click']
)

PHP

<?php

function reportPhishing($apiKey, $reportedBy, $emailFrom, $subject, $sendDate, $options = []) {
    $url = 'https://api.whalemate.io/api/external/reported-emails';

    $data = array_merge([
        'reported_by' => $reportedBy,
        'email_from' => $emailFrom,
        'subject' => $subject,
        'send_date' => $sendDate,
    ], $options);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-KEY: ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $result = json_decode($response, true);

    if ($httpCode === 201) {
        echo "Reporte creado: ID " . $result['data']['id'] . "\n";
        return $result['data']['id'];
    } else {
        echo "Error: " . $result['message'] . "\n";
        return null;
    }
}

// UsoreportPhishing(
    'tu_api_key_aqui',
    '[email protected]',
    '[email protected]',
    'Email sospechoso',
    date('c'),
    ['links' => ['https://phishing.com/click']]
);

❓ Perguntas frequentes

O que acontece se o usuário que reporta não existir no Whalemate?

O endpoint retornará erro 422.
O usuário deve estar previamente registrado na sua organização dentro do Whalemate.

Posso enviar o conteúdo completo dos anexos?

Atualmente, apenas metadados são aceitos (nome, tipo e tamanho).
O conteúdo completo do anexo não pode ser enviado por motivos de segurança e tamanho do payload.

Como sei se meu reporte foi processado corretamente?

A resposta 201 com o id do reporte confirma que ele foi processado com sucesso.
Além disso, você pode:

Verificar na UI do Whalemate (seção Email SIEM)
Os analistas da sua organização receberão uma notificação por e-mail

Os reportes externos são processados da mesma forma que os add-ins nativos?

Sim. Os reportes enviados pela API seguem o mesmo fluxo:

Status inicial: received
Categoria inicial: unknown
Notificações enviadas para os e-mails configurados
Analistas podem classificá-los normalmente
Os reportes aparecem nos analytics

A única diferença é o campo source, que indica a origem (external_api).

Posso usar a mesma API Key para múltiplos sistemas?

Sim, porém recomendamos gerar uma API Key diferente por sistema, para:

Melhor rastreabilidade
Revogação granular em caso de comprometimento
Métricas separadas por origem

A API Key expira?

Não. As API Keys não expiram automaticamente.
No entanto, recomendamos rotacioná-las a cada 90 dias como boa prática de segurança.

Qual formato de data devo usar para send_date?

Utilize o formato ISO 8601 (RFC 3339). Exemplos válidos:

2026-01-19T10:30:00Z (UTC)
2026-01-19T10:30:00-05:00 (com timezone)
2026-01-19T10:30:00.123Z (com milissegundos)

Existe limite para o tamanho do payload?

Sim. O tamanho máximo do request é 2MB.
Para e-mails muito grandes, considere enviar apenas o message_preview em vez do raw_message completo.

✨Melhores práticas

Segurança

Nunca exponha a API Key em código cliente
Use sempre HTTPS
Armazene a API Key de forma segura
Implemente retry com backoff exponencial
Monitore o uso da API Key

Performance

Implemente rate limiting do lado do cliente
Use processamento em batch
Cache validações sempre que possível
Processe reportes de forma assíncrona

Tratamento de erros

async function reportWithRetry(emailData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await reportPhishing(emailData);
      return response;
    } catch (error) {
      if (error.status === 422) {
        // Erro de validação, não tentar novamente
        throw error;
      }

      if (error.status === 429) {
        // Rate limit atingido, aguardar e tentar novamente
        const retryAfter = error.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }

      if (attempt === maxRetries) {
        throw error;
      }

      // Backoff exponencial para outros erros
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

Coleção do Postman

Disponibilizamos uma coleção oficial do Postman para facilitar testes e integrações com a API de Reporte Externo de Phishing.

Devido a limitações na distribuição de arquivos, a coleção é fornecida sob solicitação.

Por favor, entre em contato com o time de suporte da Whalemate para obter a versão mais atualizada.

Prev🇧🇷 Botão de Reporte de Phishing – Microsoft Outlook On-Premise

Next🇪🇸 Contenido de la Academia

Was this helpful?

⌘J

🇧🇷 External Phishing Reports API - Whalemate Docs | Productlane