Documentación de la API REST

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

Obtenga una lista paginada de los correos electrónicos de un usuario. Las respuestas de lista contienen solo metadatos (no body / html_body).

Parámetro	Ubicación	Descripción
domain	camino	Dominio de correo electrónico, p. example.com
user	camino	Nombre de usuario, p.e. testuser
page	consulta, opcional	Número de página (predeterminado 1)
limit	consulta, opcional	Elementos por página (predeterminado 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}

Obtenga los detalles completos de un correo electrónico.

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

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

Eliminar un correo electrónico específico.

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

{ "status": "deleted" }

POST/api/add-domain/{domain}

Agregue un nuevo dominio o actualice el estado en línea de un dominio existente. El dominio debe tener un registro MX que apunte al nombre de host del sistema para ser aceptado (estado added, is_online: true).

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

// Agregado exitosamente
{ "status": "added", "domain": "newdomain.com", "is_online": true }

// Dominio existente: actualizar su estado
{ "status": "updated", "domain": "newdomain.com", "is_online": false }

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

Todos los dominios en línea (privados, se requiere token):

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

Dominios en línea aleatorios (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 si un dominio tiene un registro MX válido que apunte al sistema.

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

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

Manejo de errores

Código	Significado
200	Éxito
400	Solicitud no válida (por ejemplo, dominio/correo electrónico con formato incorrecto)
401	Token faltante o no válido para un punto final privado
404	Correo electrónico no encontrado
429	Límite de tarifa excedido

{ "detail": "Domain not found" }

Notas importantes

• Las direcciones de correo electrónico deben utilizar el formato [email protected]
• Sólo los dominios con registros MX válidos tienen estado "en línea"
• Los correos electrónicos y dominios inactivos se eliminan automáticamente después 3 días
• el servicio solo recibe correo electrónico: el envío y la retransmisión SMTP no son compatibles
• La API aplica límites de velocidad por IP
• El período de retención de 3 días se aplica al servicio en vivo; las copias de seguridad pueden conservar las copias por más tiempo. No se garantiza la eliminación permanente de todas las copias en ese momento.
• Las bandejas de entrada de dominios personalizados siguen siendo públicas y pueden ser bloqueadas por servicios de terceros. La aceptación y entrega no están garantizadas.