Referencia

API HTTP

Referencia completa de la API HTTP local, incluidos filtros y formatos de respuesta.

Mantenido por colaboradoresÚltima actualización 23 de julio de 2026

La API HTTP local devuelve JSON y está disponible en http://localhost:8025 por defecto.

Convenciones de las peticiones

Los valores de los parámetros de consulta deben estar codificados para URL. Las peticiones de listado, último mensaje y espera aceptan estos filtros:

Parámetro de consulta	Significado
`to`	Coincide con cualquier dirección de destinatario, sin distinguir mayúsculas
`subject`	Subcadena del asunto, sin distinguir mayúsculas
`subjectPattern`	Fuente de expresión regular de JavaScript para el asunto
`subjectFlags`	Modificadores usados con `subjectPattern`
`afterId`	Devuelve solo mensajes recibidos después de este mensaje almacenado

La ruta de listado admite limit, cuyo valor debe estar entre 1 y 100. La ruta de espera admite timeoutMs, cuyo valor debe estar entre 1 y 60 000. Los errores devuelven { "error": "..." } con un estado apropiado.

Estado del servicio

GET/health

Devuelve las direcciones SMTP y HTTP enlazadas más el dominio de destinatarios.

{
  "ok": true,
  "api": { "host": "localhost", "port": 8025 },
  "smtp": { "host": "localhost", "port": 1025 },
  "domain": "local.test"
}

Listar correos

GET/api/emails

Devuelve los mensajes coincidentes en orden de recepción. La respuesta es { "emails": CapturedEmail[] }.

curl "http://localhost:8025/api/emails?to=signup%40local.test&limit=10"

Último correo

GET/api/emails/latest

Devuelve { "email": CapturedEmail } para el mensaje coincidente más reciente. Devuelve 404 cuando no existe ninguna coincidencia.

curl "http://localhost:8025/api/emails/latest?subject=verify"

Esperar un correo

GET/api/emails/wait

Mantiene un sondeo prolongado hasta que haya un mensaje coincidente disponible. La espera predeterminada es de 10 segundos y el máximo de 60 segundos. Devuelve { "email": CapturedEmail } si tiene éxito o 408 si se agota el tiempo de espera.

curl "http://localhost:8025/api/emails/wait?to=signup%40local.test&timeoutMs=30000"

Obtener por ID

GET/api/emails/:id

Devuelve { "email": CapturedEmail } para un identificador almacenado, o 404 cuando no está presente.

Limpiar correos

DELETE/api/emails

Borra todos los mensajes almacenados y devuelve { "deleted": number }. Añade un parámetro de consulta to para borrar solo los mensajes dirigidos a un destinatario.

curl -X DELETE "http://localhost:8025/api/emails?to=signup%40local.test"