Aller au contenu
Frontmail Docs

Compatibilité EmailJS (@frontmail/emailjs-compat)

@frontmail/emailjs-compat expose les mêmes fonctions et signatures que @emailjs/browser, mais communique avec Frontmail. Le code existant continue de fonctionner une fois l’import et les identifiants changés.

Fenêtre 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');

Ce qui est compatible

Section intitulée « Ce qui est compatible »
  • init(publicKey) et init({ publicKey, blockHeadless, blockList, limitRate, storageProvider }), avec un second argument facultatif pour l’origine de l’API (par défaut https://api.frontmail.dev).
  • send(serviceID, templateID, templateParams?, options?) et sendForm(serviceID, templateID, form, options?), avec options sous forme de chaîne de clé publique ou d’objet d’options.
  • La valeur résolue est un EmailJSResponseStatus avec status (200) et text ('OK'), comme dans EmailJS, plus des champs propres à Frontmail : messageId, deliveryStatus ('queued' ou 'held') et statusToken.
  • Les erreurs sont levées sous forme d’objets EmailJSResponseStatus avec status et text : vos gestionnaires catch existants fonctionnent donc. La FrontmailError sous-jacente (avec code et docsUrl) se trouve dans error.error.
  • Les chemins REST /api/v1.0/email/send et /api/v1.0/email/send-form existent sur api.frontmail.dev, avec les champs de corps EmailJS service_id, template_id, user_id, template_params, accessToken.

Ce qui diffère

Section intitulée « Ce qui diffère »
  • Les identifiants et les clés sont ceux de Frontmail : svc_…, tpl_…, pk_…, sk_….
  • Les modèles utilisent la syntaxe Frontmail (Handlebars) et des paramètres typés. La plupart des modèles {{variable}} fonctionnent sans modification ; voir le guide de migration.
  • Frontmail peut répondre avec un message retenu (held) lorsque vous n’avez plus de crédits (c’est quand même un succès). La couche de compatibilité le signale par status: 200 avec deliveryStatus: 'held' ; @frontmail/browser renvoie directement status: 'held'.
  • Frontmail relance automatiquement les erreurs réseau et les 5xx avec une clé d’idempotence.
  • Les traductions de modèles ne sont pas prises en charge – EmailJS ne connaît pas ce concept. Le paquet de compatibilité et les routes /api/v1.0/email/… envoient toujours la langue par défaut du modèle (une locale dans le corps est ignorée, un champ de formulaire fm_locale est un paramètre de modèle ordinaire). Utilisez @frontmail/browser avec l’option locale pour choisir une langue.
  • accessToken (une clé privée) est refusé dans le navigateur : send / sendForm sont rejetés avec status: 400 et error.code === 'private_key_in_browser'. Retirez-le du code frontend – voir le guide de migration. Le code côté serveur (Node.js, sans document) peut toujours le transmettre.
  • sendForm ignore les champs de mot de passe, les champs anti-CSRF des frameworks courants et les noms réservés comme accessToken (voir sendForm).
  • blockHeadless, blockList et limitRate s’exécutent dans le navigateur et sont un confort, pas un contrôle de sécurité – appliquez les limites dans Sécurité du tableau de bord.

Quand vous serez prêt, passer à @frontmail/browser ou à un SDK pour framework est simple et vous apporte des résultats typés, des paramètres typés et getStatus.