Utilizzo dell'estensione Trigger Email

L'estensione Invia email (firestore-send-email) ti consente di inviare automaticamente email in base ai documenti di una raccolta Cloud Firestore. L'aggiunta di un documento alla raccolta attiva questa estensione per inviare un'email creata dai campi del documento. I campi di primo livello del documento specificano il mittente e i destinatari email, incluse le opzioni to, cc e bcc (ciascuna supporta gli UID). Il campo message del documento specifica gli altri elementi dell'email, come la riga dell'oggetto e il corpo dell'email (in testo normale o HTML).

Ecco un esempio di scrittura di un documento di base che attiverebbe questa estensione:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

Facoltativamente, puoi configurare questa estensione per eseguire il rendering delle email utilizzando i modelli Handlebars.

Configurazione di preinstallazione

Prima di installare l'estensione, completa i seguenti passaggi:

  1. Configura il servizio di posta in uscita.

    Quando installi l'estensione Attiva email, devi specificare i dettagli di connessione e autenticazione di un server SMTP, che l'estensione utilizza per inviare le email. In genere viene fornito da un servizio di invio email come Sendgrid, Mailgun o Mailchimp Transactional Email, ma potrebbe anche essere un server che gestisci autonomamente.

  2. Crea una raccolta di documenti email.

    L'estensione Attiva email ascolta i nuovi documenti in una Cloud Firestore collezione specificata. Quando trova un nuovo documento, l'estensione invia un'email in base ai campi del documento. A questo scopo puoi utilizzare qualsiasi raccolta Cloud Firestore. Gli esempi in questa pagina utilizzano una raccolta denominata email.

  3. Configura le regole di sicurezza per la raccolta dei documenti email.

    Questa estensione può essere utilizzata per attivare l'invio di email direttamente dalle applicazioni client. Tuttavia, devi controllare attentamente l'accesso dei client alla raccolta per evitare potenziali abusi (non vuoi che gli utenti possano inviare email arbitrarie dall'indirizzo della tua azienda).

    Le regole di sicurezza variano da un'applicazione all'altra, ma devi sempre assicurarti che le email vengano inviate solo ai destinatari previsti e che i contenuti in formato libero siano ridotti al minimo. I modelli possono essere utili in questo caso: puoi utilizzare le regole di sicurezza per verificare che i dati inseriti nel modello corrispondano alle tue aspettative in merito a ciò che un utente può attivare.

  4. (Facoltativo) Configura una raccolta di utenti.

    Nell'utilizzo di base di questa estensione, specifichi i destinatari di un'email indicando i relativi indirizzi email nei campi to, cc e bcc del documento del messaggio. In alternativa, se hai un database utente in Cloud Firestore, puoi specificare i destinatari utilizzando gli UID degli utenti. Affinché questo funzioni, la raccolta degli utenti deve soddisfare i seguenti criteri:

    • La raccolta deve essere codificata sugli ID utente. In altre parole, l'ID documento di ogni documento utente nella raccolta deve essere l'UID Firebase Authentication dell'utente.
    • Ogni documento utente deve avere un campo email contenente l'indirizzo email dell'utente.

  5. (Facoltativo) Configura una raccolta di modelli.

    Puoi visualizzare le email utilizzando i modelli Handlebars. Per farlo, devi disporre di una raccolta Cloud Firestore contenente i tuoi modelli.

    Per maggiori dettagli, consulta la sezione Utilizzare i modelli Handlebars con l'estensione Trigger Email.

Installa l'estensione

Per installare l'estensione, segui i passaggi nella pagina Installare un Firebase Extension. In sintesi, esegui una delle seguenti operazioni:

  • Console Firebase: fai clic sul seguente pulsante:

    Installa l'estensione Trigger Email

  • Interfaccia a riga di comando: esegui questo comando: 

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

Quando installi l'estensione, ti verrà chiesto di specificare i dati di connessione SMTP e le raccolte Cloud Firestore che hai configurato in precedenza.

Utilizzare l'estensione

Dopo l'installazione, questa estensione monitora tutte le scritture dei documenti nella raccolta configurata. L'email viene recapitata in base ai contenuti dei campi del documento. I campi di primo livello specificano il mittente e i destinatari dell'email. Il campo message contiene i dettagli dell'email da recapitare, incluso il corpo dell'email.

Esempio: inviare un'email

Per inviare un messaggio semplice, aggiungi un documento alla raccolta di messaggi con un campo to e un campo message con i seguenti contenuti:

to: ['someone@example.com'],
message: {
  subject: 'Hello from Firebase!',
  text: 'This is the plaintext section of the email body.',
  html: 'This is the <code>HTML</code> section of the email body.',
}

Campi mittente e destinatario

I campi di primo livello del documento forniscono le informazioni sul mittente e sul destinatario dell'email. I campi disponibili sono:

  • from: l'indirizzo email del mittente. Se non specificato nel documento, viene utilizzato il parametro "Default FROM address" configurato.
  • replyTo: l'indirizzo email di risposta. Se non specificato nel documento, viene utilizzato il parametro "Indirizzo REPLY-TO predefinito" configurato.
  • to: un singolo indirizzo email del destinatario o un array contenente più indirizzi email del destinatario.
  • toUids: un array contenente gli UID dei destinatari.
  • cc: un singolo indirizzo email del destinatario o un array contenente più indirizzi email del destinatario.
  • ccUids: un array contenente gli UID dei destinatari in Cc.
  • bcc: un singolo indirizzo email del destinatario o un array contenente più indirizzi email del destinatario.
  • bccUids: un array contenente gli UID dei destinatari Ccn.
  • headers: un oggetto di campi di intestazione aggiuntivi (ad esempio {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

NOTA: le opzioni toUids, ccUids e bccUids inviano le email in base agli UID utente associati agli indirizzi email all'interno di un documento Cloud Firestore. Per utilizzare queste opzioni per i destinatari, devi specificare una raccolta Cloud Firestore per il parametro "Raccolta utenti " dell'estensione. L'estensione può quindi leggere il email campo per ogni UID specificato nei campi toUids, ccUids e/o bccUids.

Campo Messaggio

Il campo message del documento contiene informazioni di recapito non elaborate dell'email. In genere questo campo deve essere compilato solo dal codice attendibile in esecuzione nei tuoi server o da Cloud Functions (fai riferimento alla sezione "Regole di sicurezza e invio di email" di seguito).

Le proprietà disponibili per il campo message sono:

  • messageId: un'intestazione ID messaggio per l'email, se presente.
  • subject: l'oggetto dell'email.
  • text: il testo non elaborato dell'email.
  • html: i contenuti HTML dell'email.
  • amp: i contenuti AMP4EMAIL dell'email.
  • attachments: un array contenente gli allegati; opzioni Nodemailer supportate: stringa UTF-8, tipo di contenuto personalizzato, URL, stringa codificata, URI dati e nodo MIME pregenerato (tieni presente che la tua email non ha accesso al file system del server cloud).

Utilizzo avanzato

Scopri di più sull'utilizzo più avanzato di questa estensione: