Tovanix
Tovanix

API de correo SMTP

Una API de envío para correo transaccional (verificación de registro, notificaciones de órdenes, restablecimiento de contraseñas) disponible tanto por SMTP estándar como por API HTTP.

  • Dos formas de entrar: conserva tu cliente SMTP actual sin cambiar código, o pásate a la API HTTP para obtener acuses más detallados
  • Plantillas: administra las plantillas de forma centralizada y envía solo las variables al momento de enviar
  • Envío en lote: muchos destinatarios por solicitud, cada uno con su propio acuse
  • Webhooks de entrega y rebote: eventos en tiempo real de entregado / rebotado / queja para proteger la reputación del remitente

POST / GET /api/v1/smtp/*

Resumen

La API de agregación SMTP ofrece capacidad de envío de correo. Agrega tus cuentas de correo SMTP y envía a través de una API unificada. Admite rotación inteligente entre varias cuentas, conmutación automática ante fallos y gestión de cuotas.

Comprar suscripción -> Agregar cuentas SMTP -> Crear clave API -> Llamar a la API de envío

Autenticación

La API SMTP usa claves específicas del módulo (prefijo smk_) para autenticarse y admite dos métodos:

Inicia sesión en la consola de usuario -> API de agregación SMTP -> Gestión de claves API. Guarda la clave justo después de crearla; la clave completa no puede verse de nuevo tras cerrar el cuadro.

Enviar correo

POST /api/v1/smtp/send

Envía un correo. El sistema selecciona automáticamente la cuenta SMTP óptima (según prioridad, uso y estado de salud).

Campos de la respuesta

Envía un encabezado Idempotency-Key para reintentar con seguridad: el primer resultado exitoso se guarda en caché y las solicitudes repetidas con la misma clave devuelven el resultado original sin reenviar ni cobrar dos veces la cuota.

Respuesta de envío programado

Con un send_at futuro, el correo no se envía de inmediato; se crea una tarea programada y se devuelve la siguiente estructura (la cuota se cobra en el momento real del envío):

Devuelve code: 429 cuando se supera el límite diario o mensual. Mejora el plan o espera al restablecimiento de la cuota.

Envío en lote

POST /api/v1/smtp/send/batch

Campos de la respuesta

Tope de destinatarios por solicitud = el max_batch_size de tu plan (por defecto 10); si lo superas, falla de inmediato. La cuota diaria/mensual se cobra por correo, no por solicitud; los destinatarios en la lista de bajas se marcan como fallidos. Los lotes grandes tardan y la solicitud puede agotar el tiempo antes de responder: envía el encabezado Idempotency-Key; al reintentar con el mismo valor obtienes el primer resultado en lugar de reenviar todo el lote.

Envío con plantilla

POST /api/v1/smtp/send/template

Campos de la respuesta

El envío con plantilla admite idempotencia duradera: agrega Idempotency-Key: <unique-string> a los encabezados de la solicitud. La intención se registra y persiste por (usuario + clave API + key) y sobrevive a un reinicio del proceso o a la pérdida de Redis. Reglas: (1) un reintento con la misma key y el mismo cuerpo devuelve el resultado original sin volver a entregar ni a cobrar cuota; (2) la misma key con un cuerpo distinto devuelve conflicto 409: usa una key nueva; (3) mientras la primera solicitud sigue en curso (pending), un reintento devuelve 409: reintenta más tarde con la misma key; (4) una intención fallida no puede reabrirse y devuelve 409: empieza de nuevo con una key nueva. Omitir el encabezado desactiva la idempotencia (se trata como un envío normal).

Consultar cuota

GET /api/v1/smtp/quota

Consulta la cuota de envío restante de la suscripción actual.

Consultar estado de envío

GET /api/v1/smtp/status/:message_id

Consulta el estado de envío del correo por el message_id devuelto por la API de envío.

Reporte de rebotes/quejas

POST /api/v1/smtp/inbound

Reporta un evento de rebote o queja: la dirección se agrega automáticamente a la lista de supresión y el registro de envío correspondiente se marca; los envíos futuros la omiten para proteger tu reputación como remitente. Indica al menos uno de email / message_id.

Preguntas frecuentes

Ya usamos SMTP, ¿tenemos que reescribir algo?

No. Apunta tu cliente SMTP actual al host, puerto y credenciales que te da Tovanix y listo. Pásate a la API HTTP solo cuando quieras acuses de entrega y rebote más detallados.

¿Cómo se deben gestionar los rebotes y las quejas?

Ambos se te envían en tiempo real mediante webhooks. Agrega la dirección a tu lista de supresión y deja de enviarle de inmediato: eso es lo que mantiene tu dominio de envío fuera de la carpeta de spam.

Páginas relacionadas: API de agregación SMTP · Documentación de la API · Verificación por SMS

Cargando…