Documentação da API REST

GET/api/email/{domain}/{user}/

Obtenha uma lista paginada dos e-mails de um usuário. As respostas da lista contêm apenas metadados (não body / html_body).

Parâmetro	Localização	Descrição
domain	caminho	Domínio de e-mail, por ex. example.com
user	caminho	Nome de usuário, por ex. testuser
page	consulta, opcional	Número da página (padrão 1)
limit	consulta, opcional	Itens por página (padrão 20, máximo 100)

curl -X GET "https://BASE_URL/api/email/example.com/testuser/?page=1&limit=20"

{
  "emails": [
    {
      "id": 123,
      "subject": "Welcome",
      "sender": "[email protected]",
      "date": "2026-09-30T10:30:00.000Z",
      "has_attachments": false,
      "size": 1234
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "has_more": false
}

GET/api/email/{domain}/{user}/{email_id}

Obtenha todos os detalhes de um e-mail.

curl -X GET "https://BASE_URL/api/email/example.com/testuser/123"

DELETE/api/email/{domain}/{user}/{email_id}

Exclua um e-mail específico.

curl -X DELETE "https://BASE_URL/api/email/example.com/testuser/123"

{ "status": "deleted" }

POST/api/add-domain/{domain}

Adicione um novo domínio ou atualize o status online de um domínio existente. O domínio deve ter um registro MX apontando para o nome do host do sistema para ser aceito (status added, is_online: true).

curl -X POST "https://BASE_URL/api/add-domain/newdomain.com"

// Adicionado com sucesso
{ "status": "added", "domain": "newdomain.com", "is_online": true }

// Domínio existente: atualize seu status
{ "status": "updated", "domain": "newdomain.com", "is_online": false }

GET/api/all-domains/ & /api/random-domains/

Todos os domínios online (privados, token obrigatório):

curl -X GET "https://BASE_URL/api/all-domains/" \
  -H "X-Domain-Token: YOUR_TOKEN"

Domínios online aleatórios (públicos):

curl -X GET "https://BASE_URL/api/random-domains/?limit=10"

{ "domains": ["domain1.com", "domain2.com"], "total": 2 }

GET/api/check-mx/{domain}

Verifique se um domínio possui um registro MX válido apontando para o sistema.

curl -X GET "https://BASE_URL/api/check-mx/example.com"

{ "result": "online" }   // ou "offline"

Tratamento de erros

Código	Significado
200	Sucesso
400	Solicitação inválida (por exemplo, domínio/e-mail malformado)
401	Token ausente ou inválido para um endpoint privado
404	E-mail não encontrado
429	Limite de taxa excedido

{ "detail": "Domain not found" }

Notas importantes

• Os endereços de e-mail devem usar o formato [email protected]
• Somente domínios com registros MX válidos têm status "online"
• E-mails e domínios inativos são excluídos automaticamente após 3 dias
• O serviço apenas recebe email — envio e retransmissão SMTP não são suportados
• A API aplica limites de taxa por IP
• O período de retenção de 3 dias aplica-se ao serviço ativo; os backups podem reter cópias por mais tempo. A exclusão permanente de todas as cópias não é garantida nesse momento.
• As caixas de entrada de domínios personalizados permanecem públicas e podem ser bloqueadas por serviços de terceiros. A aceitação e a entrega não são garantidas.