Salta ai contenuti
Frontmail Docs

Panoramica e concetti

Frontmail ti permette di inviare email direttamente dal frontend – un modulo di contatto, una richiesta di prenotazione, una conferma d’ordine – senza gestire un tuo backend. Colleghi il provider email che usi già, crei nella dashboard un modello HTML con parametri tipizzati e chiami una sola funzione:

import { init, send } from '@frontmail/browser';


init({ publicKey: 'pk_4f2a…' });
await send('svc_01J9…', 'tpl_01J9…', { name: 'Giulia', message: 'Ciao!' });

La richiesta arriva all’API di Frontmail, che la controlla (origin, protezione dai bot, rate limit, validazione dei parametri), riserva un credito e mette l’email in coda. Un sender genera poi il modello e lo consegna tramite il tuo provider. Gli eventi di consegna (recapitata, non recapitata, aperta…) tornano indietro tramite i webhook del provider e finiscono nella cronologia e nelle statistiche.

Gli elementi di base

Sezione intitolata “Gli elementi di base”

Organizzazione

Sezione intitolata “Organizzazione”

Tutto – chiavi, servizi, modelli, crediti, membri – appartiene a un’organizzazione. Un utente può essere membro di più organizzazioni e passare dall’una all’altra. Ogni organizzazione ha il suo piano e il suo saldo di crediti.

Chiave pubblica e chiave privata

Sezione intitolata “Chiave pubblica e chiave privata”
Chiave pubblica pk_… Chiave privata sk_…
Dove si trova Nel codice del frontend – non è un segreto Solo sul tuo server – trattala come una password
Come si invia user_id nel corpo o header X-Frontmail-Public-Key Authorization: Bearer sk_… (oppure accessToken nel corpo) – mai dal browser: le richieste con header Origin vengono rifiutate
Protetta da Domini consentiti, Turnstile, rate limit, protezione dai bot La sua segretezza – salta i controlli di origin e CAPTCHA
Cosa può fare send, send-form, upload, stato dei propri messaggi Tutto quanto sopra più send-batch, history, templates

Dato che la chiave pubblica è visibile a chiunque apra la tua pagina, Frontmail non si fida mai solo di lei. Prima di andare in produzione leggi Chiavi pubbliche e private.

Servizi

Sezione intitolata “Servizi”

Un servizio è una connessione a un provider email: SMTP (Seznam, Zoho, il tuo server), Mailgun, Amazon SES, Postmark, Mailjet, Brevo, Resend, Gmail oppure Outlook / Microsoft 365. Le credenziali sono cifrate con AWS KMS. Frontmail controlla ogni servizio una volta al giorno e subito dopo un errore di autenticazione, e un modello può avere un servizio di riserva che subentra quando quello principale non funziona. Vedi Panoramica dei servizi.

Modelli

Sezione intitolata “Modelli”

Un modello è un’email HTML completa (con una versione in testo semplice generata) più oggetto, destinatari (To, CC, BCC, Reply-To, From) e uno schema dei parametri. I parametri sono tipizzati (string, email, number, date, list…) e vengono validati a ogni invio; il corpo usa Handlebars per condizioni, cicli e helper di formattazione. Vedi Modelli HTML e Parametri e tipi.

Crediti

Sezione intitolata “Crediti”

Un’email accettata = un credito. I crediti arrivano dai grant:

  • subscription – la quota mensile del tuo piano (non si accumula al mese successivo),
  • pack – pacchetti di crediti prepagati validi da 3 a 12 mesi, disponibili con ogni piano, Free compreso,
  • bonus – crediti aggiunti dal supporto di Frontmail,
  • overdraft – uno scoperto del 10 % sui piani a pagamento, addebitato nella fattura successiva.

I crediti vengono presi sempre dal grant che scade per primo, lo scoperto per ultimo. Gli invii di prova dall’editor dei modelli sono gratuiti. Se un invio fallisce in modo definitivo, il credito viene rimborsato. Vedi Ordine di consumo.

Nessuna email va persa in silenzio

Sezione intitolata “Nessuna email va persa in silenzio”

Quando finisci i crediti, Frontmail non butta via la tua email. Nella modalità predefinita hold accetta la richiesta con 202 { "status": "held" }, salva il messaggio e lo invia automaticamente appena i crediti tornano disponibili – dopo l’acquisto di un pacchetto, una ricarica automatica, un upgrade o l’inizio del periodo di fatturazione successivo. Leggi Coda dei messaggi in attesa.

Il ciclo di vita di un messaggio

Sezione intitolata “Il ciclo di vita di un messaggio”
accepted ─┬─► queued ─► sending ─► sent ─┬─► delivered
          │                              ├─► bounced
          │                              └─► complained
          ├─► held (no credits) ─► queued …   or ─► discarded (hold expired / manual)
          └─► (on provider auth error) held_service_error ─► queued … after the service is fixed
                                     failed (permanent error, credit refunded)

Tutti gli stati sono spiegati in Stati dei messaggi.

Prossimi passi

Sezione intitolata “Prossimi passi”