Utilizzando l'estensione Trigger Email

L'estensione Trigger Email ( firestore-send-email ) ti consente di inviare automaticamente e-mail in base ai documenti in una raccolta Cloud Firestore. L'aggiunta di un documento alla raccolta fa sì che questa estensione invii un'e-mail creata dai campi del documento. I campi di livello superiore del documento specificano il mittente e i destinatari dell'e-mail, incluse le opzioni to , cc e bcc (ognuna delle quali supporta gli UID). Il campo message del documento specifica gli altri elementi dell'e-mail, come la riga dell'oggetto e il corpo dell'e-mail (testo semplice 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 anche configurare questa estensione per eseguire il rendering delle email utilizzando i modelli Handlebars .

Configurazione pre-installazione

Prima di installare l'estensione, completa questi passaggi:

  1. Configura il tuo servizio di posta in uscita.

    Quando installi l'estensione Trigger Email, dovrai specificare i dettagli di connessione e autenticazione di un server SMTP, che l'estensione utilizza per inviare e-mail. Questo viene in genere fornito da un servizio di consegna di posta elettronica come Sendgrid, Mailgun o Mailchimp Transactional Email, ma potrebbe anche essere un server gestito da te.

  2. Crea una raccolta di documenti email.

    L'estensione Trigger Email ascolta i nuovi documenti in una raccolta Cloud Firestore specificata. Quando trova un nuovo documento, l'estensione invia un'e-mail in base ai campi del documento. Puoi utilizzare qualsiasi raccolta Cloud Firestore a questo scopo; gli esempi in questa pagina utilizzano una raccolta denominata email .

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

    Questa estensione può essere utilizzata per attivare la consegna della posta elettronica direttamente dalle applicazioni client. Tuttavia, dovresti 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 dovresti 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 aiutarti in questo caso: puoi utilizzare le regole di sicurezza per verificare che i dati inseriti nel modello corrispondano alle tue aspettative su ciò che un utente dovrebbe essere autorizzato a attivare.

  4. Facoltativo: impostare una raccolta di utenti.

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

    • La raccolta deve essere codificata in base agli ID utente. Ciò significa che l'ID documento di ciascun documento utente nella raccolta deve essere l'UID di autenticazione Firebase dell'utente.
    • Ogni documento utente deve avere un campo email contenente l'indirizzo e-mail dell'utente.
  5. Facoltativo: configura una raccolta di modelli.

    Puoi eseguire il rendering delle email utilizzando i modelli Handlebars . Per fare ciò, avrai bisogno di una raccolta Cloud Firestore per contenere i tuoi modelli.

    Consulta Utilizzare i modelli Handlebars con l'estensione Trigger Email per i dettagli.

Installa l'estensione

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

  • Console Firebase: fai clic sul pulsante seguente:

    Installa l'estensione Trigger Email

  • CLI: eseguire il comando seguente:

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

Quando installi l'estensione, ti verrà richiesto di specificare le informazioni sulla connessione SMTP e le raccolte Cloud Firestore configurate in precedenza.

Utilizza l'estensione

Dopo l'installazione, questa estensione monitora tutte le scritture di documenti nella raccolta configurata. L'e-mail viene consegnata in base al contenuto dei campi del documento. I campi di livello superiore specificano il mittente e i destinatari dell'e-mail. Il campo message contiene i dettagli dell'e-mail da recapitare, compreso il corpo dell'e-mail.

Esempio: inviare un'e-mail

Per inviare un messaggio semplice, aggiungi un documento alla raccolta dei messaggi con un campo to e un campo message con il seguente contenuto:

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 livello superiore del documento forniscono le informazioni sul mittente e sul destinatario dell'e-mail. I campi disponibili sono:

  • da: l'indirizzo email del mittente. Se non specificato nel documento, utilizza il parametro configurato "Default FROM address".
  • AnswerTo: l'indirizzo email di risposta. Se non specificato nel documento, utilizza il parametro configurato "Indirizzo REPLY-TO predefinito".
  • a: un indirizzo e-mail di un singolo destinatario o un array contenente più indirizzi e-mail di destinatari.
  • toUids: un array contenente gli UID del destinatario.
  • cc: un indirizzo e-mail di un singolo destinatario o un array contenente più indirizzi e-mail di destinatari.
  • ccUids: un array contenente gli UID dei destinatari CC.
  • bcc: un indirizzo e-mail di un singolo destinatario o un array contenente più indirizzi e-mail di destinatari.
  • bccUids: un array contenente gli UID dei destinatari BCC.
  • intestazioni: 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 e-mail in base agli UID utente digitati negli indirizzi e-mail all'interno di un documento Cloud Firestore. Per utilizzare queste opzioni destinatario, devi specificare una raccolta Cloud Firestore per il parametro "Raccolta Utenti" dell'estensione. L'estensione può quindi leggere il campo email per ciascun UID specificato nei campi toUids , ccUids e/o bccUids .

Campo messaggio

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

Le proprietà disponibili per il campo message sono:

  • messageId: un'intestazione ID messaggio per l'e-mail, se presente.
  • oggetto: l'oggetto dell'e-mail.
  • testo: il contenuto in testo normale dell'e-mail.
  • html: il contenuto HTML dell'e-mail.
  • amp: il contenuto AMP4EMAIL dell'e-mail.
  • allegati: un array contenente 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 posta elettronica non ha accesso al file system del server cloud).

Utilizzo avanzato

Ulteriori informazioni sull'uso più avanzato di questa estensione: