v1.0

📚 Documentação da API

Integre suas aplicações com a plataforma MailPhishing para verificar e reportar ameaças de phishing em tempo real.

Endpoints 🎮 Playground

Visão Geral

A API do MailPhishing permite que você consulte nossa base de dados de ameaças e reporte novas ameaças de phishing diretamente de suas aplicações.

🔗 URL Base

https://mailphishing.com/api/v1

Características

  • ✅ Sem necessidade de API Key
  • ✅ Consultas em tempo real
  • ✅ Suporte a email, URL e IP
  • ✅ Múltiplas fontes de inteligência
  • ✅ Respostas em JSON

Autenticação

Nossa API pública não requer autenticação. Basta fazer requisições para os endpoints disponíveis.

⚠️ Importante

Todas as requisições estão sujeitas a rate limiting baseado no IP do cliente.

Rate Limiting

Para garantir a estabilidade do serviço, aplicamos limites de requisições:

Endpoint Rate Limiting Window
/api/v1/lookup 20 / min / IP
/api/v1/report 20 / min / IP

Headers de Rate Limit

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1710619200

Endpoints

GET /api/v1/lookup

Verifica se um valor está presente na base de ameaças.

POST /api/v1/lookup

Verifica se um valor está presente na base de ameaças.

POST /api/v1/report

Reporta uma nova ameaça de phishing para análise.

Lookup

Verifica se um valor está presente na base de ameaças.

Parâmetros

Parâmetros Type Required Description
query string Yes Email, URL ou IP a ser consultado
type string No Tipo: email, url ou ip (auto-detectado se omitido)

Exemplo de Requisição

curl "https://mailphishing.com/api/v1/[email protected]"
import requests

response = requests.get(
    'https://mailphishing.com/api/v1/lookup',
    params={'query': '[email protected]'}
)
print(response.json())
const response = await fetch(
    'https://mailphishing.com/api/v1/[email protected]'
);
const data = await response.json();
console.log(data);
$ch = curl_init('https://mailphishing.com/api/v1/[email protected]');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);

Exemplo de Resposta

{
    "success": true,
    "data": {
        "query": "[email protected]",
        "type": "email",
        "found": true,
        "threat": {
            "sources": [
                {
                    "name": "PhishTank",
                    "first_seen": "2024-01-15 10:30:00"
                }
            ],
            "total_sources": 1,
            "first_seen": "2024-01-15 10:30:00"
        }
    },
    "meta": {
        "query_time_ms": 45,
        "timestamp": "2024-03-16T12:00:00+00:00",
        "rate_limit": {
            "limit": 20,
            "remaining": 19,
            "reset_at": "2024-03-16T12:01:00+00:00"
        }
    }
}

Report

Reporta uma nova ameaça de phishing para análise.

Parâmetros (Body JSON)

Parâmetros Type Required Description
type string Yes email, url or ip
value string Yes Value to report
reporter_email string No Reporter email for updates
notes string No Description or additional context

Exemplo de Requisição

curl -X POST "https://mailphishing.com/api/v1/report" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "value": "[email protected]",
    "reporter_email": "[email protected]",
    "notes": "This email is trying to steal bank credentials"
  }'

Exemplo de Resposta

{
    "success": true,
    "data": {
        "id": 123,
        "type": "email",
        "value": "[email protected]",
        "status": "pending",
        "message": "Report submitted successfully. Thank you for contributing to a safer internet."
    },
    "meta": {
        "response_time_ms": 120,
        "timestamp": "2024-03-16T12:00:00+00:00"
    }
}

Códigos de Erro

HTTP Code Description
400 MISSING_QUERY Query parameter not provided
400 INVALID_TYPE Invalid type
400 VALIDATION_ERROR Data validation error
405 METHOD_NOT_ALLOWED HTTP method not allowed
429 RATE_LIMIT_EXCEEDED Rate limit exceeded
500 INTERNAL_ERROR Internal server error
503 SERVICE_UNAVAILABLE Service temporarily unavailable

🎮 Playground

Teste a API diretamente aqui:

Resposta

Teste a API diretamente aqui: