Ir al contenido
Frontmail Docs

Compatibilidad con EmailJS (@frontmail/emailjs-compat)

@frontmail/emailjs-compat expone las mismas funciones y firmas que @emailjs/browser, pero se comunica con Frontmail. El código existente sigue funcionando después de cambiar el import y los ID.

Ventana de terminal
npm uninstall @emailjs/browser
npm install @frontmail/emailjs-compat
import emailjs from '@emailjs/browser';
import emailjs from '@frontmail/emailjs-compat';


emailjs.init({ publicKey: 'pk_4f2a…' });
emailjs.send('svc_01J9…', 'tpl_01J9…', { name: 'Jana' });
emailjs.sendForm('svc_01J9…', 'tpl_01J9…', '#contact-form');

Qué es compatible

Sección titulada «Qué es compatible»
  • init(publicKey) e init({ publicKey, blockHeadless, blockList, limitRate, storageProvider }), con un segundo argumento opcional para el origen de la API (por defecto https://api.frontmail.dev).
  • send(serviceID, templateID, templateParams?, options?) y sendForm(serviceID, templateID, form, options?), con options como cadena de clave pública o como objeto de opciones.
  • El valor resuelto es un EmailJSResponseStatus con status (200) y text ('OK'), como en EmailJS, más los extras de Frontmail: messageId, deliveryStatus ('queued' o 'held') y statusToken.
  • Los errores se lanzan como objetos EmailJSResponseStatus con status y text, así que los manejadores catch existentes siguen funcionando. El FrontmailError subyacente (con code y docsUrl) está en error.error.
  • Las rutas REST /api/v1.0/email/send y /api/v1.0/email/send-form existen en api.frontmail.dev, con los campos del cuerpo de EmailJS service_id, template_id, user_id, template_params, accessToken.

Qué cambia

Sección titulada «Qué cambia»
  • Los ID y las claves son los de Frontmail: svc_…, tpl_…, pk_…, sk_….
  • Las plantillas usan la sintaxis de Frontmail (Handlebars) y parámetros tipados. La mayoría de las plantillas con {{variable}} funcionan sin cambios; consulta la guía de migración.
  • Frontmail puede resolver con un mensaje retenido cuando te quedas sin créditos (sigue siendo un éxito). La capa de compatibilidad lo indica como status: 200 con deliveryStatus: 'held'; @frontmail/browser devuelve directamente status: 'held'.
  • Frontmail reintenta automáticamente los errores de red y los 5xx con una clave de idempotencia.
  • Las traducciones de plantillas no son compatibles: EmailJS no tiene ese concepto. El paquete compat y las rutas /api/v1.0/email/… envían siempre el idioma predeterminado de la plantilla (un locale en el cuerpo se ignora y un campo de formulario fm_locale es un parámetro normal de la plantilla). Usa @frontmail/browser con la opción locale para elegir un idioma.
  • accessToken (una clave privada) se rechaza en el navegador: send / sendForm se rechazan con status: 400 y error.code === 'private_key_in_browser'. Quítalo del código frontend: consulta la guía de migración. El código de servidor (Node.js, sin document) todavía puede pasarlo.
  • sendForm omite los campos de contraseña, los campos anti-CSRF de los frameworks habituales y los nombres reservados como accessToken (consulta sendForm).
  • blockHeadless, blockList y limitRate se ejecutan en el navegador y son una comodidad, no un control de seguridad: aplica los límites en Seguridad en el panel.

Cuando estés listo, pasar a @frontmail/browser o a un SDK de framework es sencillo y te da resultados tipados, parámetros tipados y getStatus.