Salta ai contenuti
Frontmail Docs

Compatibilità con EmailJS (@frontmail/emailjs-compat)

@frontmail/emailjs-compat espone le stesse funzioni e firme di @emailjs/browser, ma comunica con Frontmail. Il codice esistente continua a funzionare dopo aver cambiato l’import e gli ID.

Finestra del terminale
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: 'Giulia' });
emailjs.sendForm('svc_01J9…', 'tpl_01J9…', '#contact-form');

Cosa è compatibile

Sezione intitolata “Cosa è compatibile”
  • init(publicKey) e init({ publicKey, blockHeadless, blockList, limitRate, storageProvider }), con un secondo argomento facoltativo per l’origine dell’API (predefinita https://api.frontmail.dev).
  • send(serviceID, templateID, templateParams?, options?) e sendForm(serviceID, templateID, form, options?), con options come stringa della chiave pubblica o come oggetto di opzioni.
  • Il valore risolto è un EmailJSResponseStatus con status (200) e text ('OK'), come in EmailJS, più alcuni extra di Frontmail: messageId, deliveryStatus ('queued' o 'held') e statusToken.
  • Gli errori vengono lanciati come oggetti EmailJSResponseStatus con status e text, quindi i gestori catch esistenti funzionano. Il FrontmailError sottostante (con code e docsUrl) si trova in error.error.
  • I percorsi REST /api/v1.0/email/send e /api/v1.0/email/send-form esistono su api.frontmail.dev, con i campi del body di EmailJS service_id, template_id, user_id, template_params, accessToken.

Cosa cambia

Sezione intitolata “Cosa cambia”
  • ID e chiavi sono quelli di Frontmail: svc_…, tpl_…, pk_…, sk_….
  • I modelli usano la sintassi di Frontmail (Handlebars) e parametri tipizzati. La maggior parte dei modelli con {{variable}} funziona senza modifiche; vedi la guida alla migrazione.
  • Frontmail può risolvere con un messaggio in attesa quando hai finito i crediti (è comunque un successo). Il livello di compatibilità lo riporta come status: 200 con deliveryStatus: 'held'; @frontmail/browser restituisce direttamente status: 'held'.
  • Frontmail ripete automaticamente gli errori di rete e i 5xx con una chiave di idempotenza.
  • Le traduzioni dei modelli non sono supportate – EmailJS non ha questo concetto. Il pacchetto di compatibilità e le route /api/v1.0/email/… inviano sempre la lingua predefinita del modello (un locale nel body viene ignorato, un campo del modulo fm_locale è un normale parametro del modello). Usa @frontmail/browser con l’opzione locale per scegliere una lingua.
  • accessToken (una chiave privata) viene rifiutato nel browser: send / sendForm vengono rifiutati con status: 400 ed error.code === 'private_key_in_browser'. Rimuovilo dal codice frontend – vedi la guida alla migrazione. Il codice lato server (Node.js, senza document) può ancora passarlo.
  • sendForm salta i campi password, i campi anti-CSRF dei framework più comuni e i nomi riservati come accessToken (vedi sendForm).
  • blockHeadless, blockList e limitRate vengono eseguiti nel browser e sono una comodità, non un controllo di sicurezza – applica i limiti in Sicurezza nella dashboard.

Quando sei pronto, passare a @frontmail/browser o a un SDK per framework è semplice e ti offre risultati tipizzati, parametri tipizzati e getStatus.