Solución de problemas

Empieza por el código de error: cada error de la API incluye code y docs_url, y en Códigos de error se explica cada uno. Historial muestra cada mensaje aceptado con su cronología, la respuesta del proveedor y el contenido renderizado.

La solicitud falla

403 origin_not_allowed: añade el dominio de tu sitio en Seguridad → Sitios web permitidos (y localhost para desarrollo). Comprueba el host exacto, incluido www.. Con details.reason: "no_origin", la solicitud no llevaba Origin en absoluto (app nativa, script de servidor): activa Permitir apps móviles para las apps y usa una clave privada en los servidores. Consulta Orígenes permitidos.

403 private_key_in_browser: se ha usado una clave privada desde una página web. Usa la clave pública en el navegador y deja la clave privada en tu servidor. Consulta Claves.

403 captcha_required / captcha_failed: la plantilla exige Turnstile. Muestra el widget dentro del formulario o pasa turnstileToken; reinicia el widget después de cada intento, porque los tokens son de un solo uso. captcha_failed con hostname_mismatch significa que el widget se resolvió en un host que no es el origen de la solicitud: añade todos los hosts de tu sitio a tu widget de Turnstile. Consulta Turnstile.

403 captcha_not_configured: la plantilla exige la CAPTCHA, pero tu organización no ha añadido sus propias claves de Turnstile. Crea un widget gratuito en Cloudflare y pega su clave de sitio y su clave secreta en Seguridad → Protección contra bots (Turnstile), o desactiva la CAPTCHA en la plantilla.

422 invalid_template_params: mira details.issues; cada problema indica el param y la regla. Causas habituales: un campo obligatorio está vacío, un parámetro email ha recibido un nombre, un parámetro number ha recibido "12 uds." o un parámetro list ha recibido una cadena que no es JSON.

403 dynamic_recipient_not_allowed: el To/CC/BCC de la plantilla usa un parámetro. Usa una respuesta automática para las confirmaciones o activa Permitir destinatario dinámico en Ajustes → Protección de la plantilla.

429 rate_limited: has superado el límite de frecuencia del plan, de la IP o de la clave. El SDK ya ha esperado y reintentado. Para envíos masivos desde un servidor, usa los envíos por lotes.

Error de CORS en la consola del navegador: normalmente es otro error disfrazado: la solicitud la ha bloqueado una Content-Security-Policy (connect-src) o un bloqueador de anuncios, o se ha enviado a un apiUrl incorrecto. La API de Frontmail envía cabeceras CORS para todos los orígenes; el acceso se controla con los orígenes permitidos.

La solicitud funciona, pero no llega ningún correo

1. Busca el mensaje en Historial.
   • held: te has quedado sin créditos. Compra un paquete (Comprar créditos) o espera a la renovación; se enviará automáticamente. También aparece en Correos retenidos. Consulta Cola de correos retenidos.
   • held_service_error: las credenciales de tu servicio han dejado de funcionar. Abre Servicios de correo y corrige o vuelve a conectar el servicio; después, los correos retenidos se envían automáticamente.
   • failed: abre el mensaje; el error del proveedor aparece en la cronología. Las causas típicas son un dominio de remitente sin verificar o un destinatario no válido.
   • sent: el proveedor lo ha aceptado. Sigue leyendo.
2. Revisa la carpeta de spam. Si está ahí, configura SPF, DKIM y DMARC para el dominio de tu remitente como se explica en la guía de tu proveedor y usa una dirección From de ese dominio (no una dirección @gmail.com a través de un proveedor transaccional).
3. Revisa la lista de supresión. Los envíos a direcciones suprimidas fallan con 451, pero si quitaste la dirección de la lista tras un rebote, puede que el buzón siga sin existir.
4. Configura los webhooks para ver los eventos delivered / bounced en lugar de adivinar.

El servicio vuelve a quedar en mal estado una y otra vez

• Gmail: Google revoca los refresh tokens cuando cambia la contraseña, cuando el usuario retira el acceso a la app o tras 6 meses sin uso. Vuelve a conectar el servicio.
• Proveedores con API: se ha rotado la clave o se han reducido sus permisos. Crea una clave con permiso de envío y actualiza el servicio.
• SMTP: ha cambiado la contraseña del buzón, o el proveedor exige una contraseña de aplicación cuando la 2FA está activada.

Añade un servicio de respaldo para que un servicio averiado no detenga tus formularios mientras lo arreglas.

Los correos se ven mal

• Faltan estilos en Gmail u Outlook → activa Incrustar CSS al guardar en los Ajustes de la plantilla.
• El texto se corta con «Ver mensaje completo» → el correo supera los ~100 kB; quita imágenes incrustadas o estilos grandes.
• Aparece <b> literal en el correo → el valor se ha escapado. Usa un parámetro html si de verdad necesitas marcado (consulta el escapado).
• Fechas en el idioma o la zona horaria equivocados → configura el idioma de la plantilla y la zona horaria de tu organización, o pasa timeZone= a formatDate.

¿Sigues atascado?

Escribe a support@frontmail.dev con el message_id (o el code y la hora del error). Nunca incluyas tu clave privada.