Cola de correos retenidos

Ningún correo se pierde en silencio. Cuando Frontmail no puede enviar un mensaje en ese momento (porque tu organización se ha quedado sin créditos o porque tu servicio de correo rechazó sus credenciales), el mensaje se acepta, se guarda de forma segura en la cola de correos retenidos (Correos retenidos en el panel) y se envía automáticamente en cuanto se resuelve el problema.

Cuándo se retienen los mensajes

Motivo	Estado	Se activa cuando
Sin créditos	held	No queda ninguna asignación con créditos (cuota, paquetes y sobregiro agotados) y la organización usa el modo `hold`
Error del servicio	held_service_error	El proveedor rechazó las credenciales (error de autenticación) y la plantilla no tiene un servicio de respaldo que funcione

Cuando la retención se debe a los créditos, la API responde al instante:

HTTP/1.1 202 Accepted

{ "message_id": "msg_01J9Z3K7Q2", "status": "held", "status_token": "…" }

Los SDK devuelven status: 'held': es un éxito, no un error. Muestra a tu visitante una confirmación normal; el correo saldrá en cuanto haya créditos disponibles.

Las retenciones por error del servicio ocurren más tarde, en el remitente: el mensaje se aceptó como queued, el proveedor rechazó las credenciales, se devolvió el crédito y el mensaje pasó a held_service_error.

Cuánto tiempo se retienen los mensajes

Plan	Duración de la retención
Free	3 días
Starter, Pro, Business	14 días

La duración se cuenta desde el momento en que se retuvo el mensaje, según el plan que tengas en ese momento. Cuando hay correos retenidos que caducarán en las próximas 24 horas, el propietario, los administradores y los miembros de facturación reciben un correo de aviso de que los correos retenidos van a caducar pronto (como mucho una vez al día). Los mensajes que llegan al final de la retención se descartan (estado discarded) y esas mismas personas reciben un correo con la lista y un enlace para descargarla completa en CSV. Un mensaje retenido nunca se descarta sin avisar a nadie.

Límite de la cola de correos retenidos

Una organización puede tener retenido como máximo el 10 % de la cuota mensual de su plan, con un mínimo de 1000 y un máximo de 10 000 mensajes (Free, Starter, Pro: 1000; Business 50k: 5000; Business 100k y 200k: 10 000). Cuando la cola está llena, las nuevas solicitudes sin crédito se rechazan con 402 insufficient_credits y details.reason: "hold_queue_full" en lugar de retenerse. Así, quien haya copiado tu clave pública no puede llenar la cola de basura que, al liberarse empezando por lo más antiguo, se comería todos los créditos nuevos antes que tus mensajes reales. Para hacer sitio, libera o descarta correos retenidos, o compra créditos.

Liberación automática

Frontmail libera la cola automáticamente siempre que aparecen créditos:

compras un paquete de créditos,
se completa una recarga automática,
mejoras tu plan,
empieza un nuevo periodo de facturación (renovación de la suscripción; Free: nuevo mes natural),
el soporte de Frontmail añade créditos de bonificación.

…y, en el caso de los mensajes held_service_error, cuando el servicio vuelve a funcionar (credenciales actualizadas, OAuth reconectado o una comprobación de estado correcta).

La liberación procesa los correos retenidos empezando por los más antiguos. Para cada mensaje reserva un crédito, lo devuelve a queued y se lo pasa al remitente. Se detiene en el primer mensaje para el que no hay crédito: el resto sigue retenido, en el mismo orden. La liberación se puede ejecutar de forma concurrente sin riesgo; un mensaje nunca se envía dos veces.

Los mensajes enviados con la clave pública solo se liberan automáticamente con créditos que no sean del sobregiro, salvo que permitas que el tráfico con clave pública lo use en Facturación → Comprar créditos → Gasto del tráfico con clave pública. Si solo queda sobregiro, esos mensajes siguen retenidos mientras se liberan los demás. Una liberación manual desde el panel sí puede usar el sobregiro para ellos.

Los correos retenidos se renderizan con la versión de la plantilla que estaba vigente cuando se aceptaron.

Liberar y descartar manualmente

Correos retenidos en el panel muestra todos los correos retenidos, empezando por los más antiguos, con las columnas Retenido desde, plantilla (con el asunto), destinatario, Motivo y Caduca. Las filas que caducan en menos de 24 horas aparecen resaltadas. Puedes filtrar por motivo con Todos / Sin créditos / Error del servicio. Los propietarios, administradores y desarrolladores pueden:

Liberar N: libera los mensajes seleccionados. Útil después de arreglar un servicio o para enviar primero los mensajes más importantes cuando solo te quedan unos pocos créditos. Los mensajes se liberan empezando por los más antiguos mientras haya créditos; el resto sigue retenido y el panel te lo indica.
Liberar todos: libera todos los correos retenidos, empezando por los más antiguos, hasta donde alcancen los créditos.
Descartar N: descarta los mensajes seleccionados tras una confirmación. No se envían nunca y no consumen créditos. No se puede deshacer.

Los propietarios y los miembros de facturación también ven un botón Comprar créditos en la página. Si tu organización usa el modo reject, la página muestra un aviso de que las nuevas solicitudes se rechazan en lugar de retenerse.

La barra superior del panel muestra siempre cuántos créditos quedan (Quedan N solicitudes). Haz clic en ella para ver el desglose por origen (suscripción, paquetes de créditos, bonificación, sobregiro) y la próxima caducidad. Cuando hay correos retenidos, aparece a su lado una insignia roja con su número que enlaza a Correos retenidos.

Modo `hold` o `reject`

Cada organización elige qué pasa cuando no hay créditos en Seguridad → Cuando te quedes sin créditos (propietarios y administradores):

Modo	Respuesta	Úsalo cuando
Retener los correos (`hold`, predeterminado y recomendado)	`202` con `status: "held"`; el mensaje se guarda y se envía más tarde	Prefieres entregar tarde a no entregar: formularios de contacto, pedidos, reservas
Rechazar las solicitudes (`reject`)	`402` `insufficient_credits`; no se guarda nada	Una entrega tardía es peor que ninguna (códigos de un solo uso, alertas urgentes) y tu código gestiona el error

En el modo reject, los SDK lanzan un InsufficientCreditsError. Las retenciones por error del servicio (held_service_error) se producen en ambos modos, porque la solicitud ya se había aceptado.

Notificaciones

Correo	Cuándo	Destinatarios
Hay correos esperando: te has quedado sin créditos	La primera vez que se retiene un mensaje en un mes natural	propietario, administradores, facturación
Los correos retenidos caducan pronto	Como mucho una vez al día mientras haya correos retenidos que caduquen en 24 horas	propietario, administradores, facturación
Correos retenidos descartados	Tras la caducidad, con la lista de mensajes descartados y un enlace al CSV	propietario, administradores, facturación
El servicio no funciona / vuelve a funcionar	Cuando un servicio falla la autenticación / se recupera	propietario, administradores

Consulta Notificaciones para ver todos los correos.

Comprobar el estado desde el código

const res = await send('svc_01J9…', 'tpl_order', params);
if (res.status === 'held') {
  // Aceptado y a salvo: se enviará automáticamente.
}

// Más tarde (los clientes con clave pública necesitan el status token del resultado del envío):
const status = await getStatus(res.messageId, { token: res.statusToken });
console.log(status.status); // "held" → "queued" → "sent" …