Utilizzo dell'estensione Trigger Email

L'estensione Trigger 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 a partire dai campi del documento. I campi di primo livello del documento specificano il mittente e i destinatari dell'email, incluse le opzioni to, cc e bcc (ognuna supporta gli UID). Il campo message del documento specifica gli altri elementi dell'email, come l'oggetto e il corpo (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.',
  },
})

Puoi anche configurare facoltativamente questa estensione per il rendering delle email utilizzando i modelli Handlebars.

Configurazione preinstallazione

Prima di installare l'estensione, completa questi passaggi:

  1. Configura il servizio di posta in uscita.

    Quando installi l'estensione Trigger Email, devi specificare i dettagli di connessione e autenticazione di un server SMTP, che l'estensione utilizza per inviare 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 personalmente.

  2. Crea una raccolta di documenti email.

    L'estensione Attiva email rileva i nuovi documenti in una Cloud Firestore raccolta 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 la consegna delle 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 applicazione ad applicazione, 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 dovrebbe essere autorizzato ad attivare.

  4. (Facoltativo) Configura una raccolta di utenti.

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

    • La raccolta deve essere basata sugli ID utente. ovvero 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 eseguire il rendering delle email utilizzando i modelli Handlebars. Per farlo, avrai bisogno di una raccolta Cloud Firestore che contenga i tuoi modelli.

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

Installare l'estensione

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

  • Console Firebase:fai clic sul seguente pulsante:

    Installare l'estensione Trigger Email

  • CLI: esegui questo comando: 

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

Quando installi l'estensione, ti viene 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 di documenti nella raccolta che hai configurato. L'email viene inviata 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 inviare, 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, utilizza il parametro "Indirizzo FROM predefinito" configurato.
  • replyTo: l'indirizzo email di risposta. Se non specificato nel documento, utilizza il parametro "Indirizzo REPLY-TO predefinito" configurato.
  • to:un singolo indirizzo email destinatario o un array contenente più indirizzi email destinatari.
  • toUids: un array contenente gli UID dei destinatari.
  • cc:un singolo indirizzo email destinatario o un array contenente più indirizzi email destinatario.
  • ccUids: un array contenente gli UID dei destinatari in Cc.
  • ccn: un singolo indirizzo email del destinatario o un array contenente più indirizzi email del destinatario.
  • bccUids: un array contenente gli UID dei destinatari in 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 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 campo email per ogni UID specificato nei campi toUids, ccUids e/o bccUids.

Campo Messaggio

Il campo message del documento contiene informazioni di consegna non elaborate per l'email. Questo campo in genere deve essere compilato solo da codice attendibile in esecuzione sui tuoi server o 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: i contenuti in formato testo normale dell'email.
  • html: i contenuti HTML dell'email.
  • amp: i contenuti AMP4EMAIL dell'email.
  • allegati:un array contenente uno o più allegati; opzioni Nodemailer supportate: stringa UTF-8, tipo di contenuti 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 avanzato di questa estensione: