Zum Inhalt springen
Frontmail Docs

EmailJS-Kompatibilität (@frontmail/emailjs-compat)

@frontmail/emailjs-compat bietet dieselben Funktionen und Signaturen wie @emailjs/browser, spricht aber mit Frontmail. Bestehender Code funktioniert weiter, sobald Sie den Import und die IDs geändert haben.

Terminal-Fenster
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');

Was kompatibel ist

Abschnitt betitelt „Was kompatibel ist“
  • init(publicKey) und init({ publicKey, blockHeadless, blockList, limitRate, storageProvider }), mit optionalem zweitem Argument für den API-Origin (Standard https://api.frontmail.dev).
  • send(serviceID, templateID, templateParams?, options?) und sendForm(serviceID, templateID, form, options?), wobei options ein öffentlicher Schlüssel als String oder ein Optionsobjekt sein kann.
  • Der aufgelöste Wert ist ein EmailJSResponseStatus mit status (200) und text ('OK') wie bei EmailJS, dazu Frontmail-Extras: messageId, deliveryStatus ('queued' oder 'held') und statusToken.
  • Fehler werden als EmailJSResponseStatus-Objekte mit status und text geworfen, sodass bestehende catch-Handler funktionieren. Der zugrunde liegende FrontmailError (mit code und docsUrl) steht in error.error.
  • Die REST-Pfade /api/v1.0/email/send und /api/v1.0/email/send-form gibt es auf api.frontmail.dev, mit den EmailJS-Body-Feldern service_id, template_id, user_id, template_params, accessToken.

Was anders ist

Abschnitt betitelt „Was anders ist“
  • IDs und Schlüssel sind die von Frontmail: svc_…, tpl_…, pk_…, sk_….
  • Vorlagen verwenden die Frontmail-Syntax (Handlebars) und typisierte Parameter. Die meisten Vorlagen mit {{variable}} funktionieren unverändert; siehe den Migrationsleitfaden.
  • Wenn Ihre Credits aufgebraucht sind, kann Frontmail mit einer zurückgehaltenen Nachricht antworten (trotzdem ein Erfolg). Die Kompatibilitätsschicht meldet das als status: 200 mit deliveryStatus: 'held'; @frontmail/browser liefert direkt status: 'held'.
  • Frontmail wiederholt Netzwerkfehler und 5xx automatisch mit einem Idempotenzschlüssel.
  • Übersetzungen von Vorlagen werden nicht unterstützt – EmailJS kennt so etwas nicht. Das Kompatibilitätspaket und die Routen /api/v1.0/email/… senden immer die Standardsprache der Vorlage (ein locale im Body wird ignoriert, ein Formularfeld fm_locale ist ein gewöhnlicher Vorlagenparameter). Verwenden Sie @frontmail/browser mit der Option locale, um eine Sprache zu wählen.
  • accessToken (ein privater Schlüssel) wird im Browser abgelehnt: send / sendForm schlagen mit status: 400 und error.code === 'private_key_in_browser' fehl. Entfernen Sie ihn aus dem Frontend-Code – siehe den Migrationsleitfaden. Serverseitiger Code (Node.js, ohne document) darf ihn weiterhin übergeben.
  • sendForm überspringt Passwortfelder, Anti-CSRF-Felder gängiger Frameworks und reservierte Namen wie accessToken (siehe sendForm).
  • blockHeadless, blockList und limitRate laufen im Browser und sind eine Komfortfunktion, kein Sicherheitsmechanismus – setzen Sie Limits im Dashboard unter Sicherheit durch.

Wenn Sie so weit sind, ist der Umstieg auf @frontmail/browser oder ein Framework-SDK unkompliziert und bringt Ihnen typisierte Ergebnisse, typisierte Parameter und getStatus.