Utilizzando l'estensione e-mail Trigger

L'estensione Trigger Email ( firestore-send-email ) ti consente di inviare automaticamente email in base ai documenti in una raccolta Cloud Firestore. L'aggiunta di un documento alla raccolta attiva questa estensione per inviare 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 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 normale o HTML).

Ecco una scrittura di documento di esempio 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 e-mail utilizzando i modelli Handlebars .

Configurazione pre-installazione

Prima di installare l'estensione, completare questi passaggi:

  1. Imposta 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 è in genere fornito da un servizio di consegna e-mail come Sendgrid, Mailgun o Mailchimp Transactional Email, ma potrebbe anche essere un server che gestisci tu stesso.

  2. Crea una raccolta di documenti e-mail.

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

  3. Imposta regole di sicurezza per la raccolta dei tuoi documenti e-mail.

    Questa estensione può essere utilizzata per attivare la consegna della posta elettronica direttamente dalle applicazioni client. Tuttavia, dovresti controllare attentamente l'accesso dei clienti alla raccolta per evitare potenziali abusi (non vuoi che gli utenti possano inviare e-mail arbitrarie dall'indirizzo della tua azienda!).

    Le regole di sicurezza variano da applicazione ad applicazione, ma devi sempre assicurarti che le e-mail vengano inviate solo ai destinatari previsti e che il contenuto in formato libero sia ridotto al minimo. I modelli possono aiutare qui: puoi utilizzare le regole di sicurezza per verificare che i dati che vengono popolati nel modello corrispondano alle tue aspettative per ciò che un utente dovrebbe essere autorizzato ad attivare.

  4. Facoltativo: configurare 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. Perché funzioni, la raccolta degli utenti deve soddisfare questi criteri:

    • La raccolta deve essere digitata sugli ID utente. In altre parole, 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 email dell'utente.

  5. Facoltativo: imposta una raccolta di modelli.

    È possibile eseguire il rendering delle e-mail utilizzando i modelli Handlebars . Per fare ciò, avrai bisogno di una raccolta Cloud Firestore che contenga i tuoi modelli.

    Per i dettagli, vedi Utilizzare i modelli Handlebars con l'estensione Trigger Email .

Installa l'estensione

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

  • Console Firebase: fai clic sul seguente pulsante:

    Installa l'estensione Trigger Email

  • CLI: eseguire il seguente comando:

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

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

Usa l'estensione

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

Esempio: inviare un'e-mail

Per inviare un messaggio semplice, aggiungi un documento alla tua raccolta di 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 e-mail del mittente. Se non specificato nel documento, utilizza il parametro configurato "Default FROM address".
  • replyTo: l'indirizzo email di risposta. Se non specificato nel documento, utilizza il parametro configurato "Default REPLY-TO address".
  • a: un singolo indirizzo di posta elettronica del destinatario o un array contenente più indirizzi di posta elettronica del destinatario.
  • toUids: un array contenente gli UID del destinatario.
  • cc: un singolo indirizzo di posta elettronica del destinatario o un array contenente più indirizzi di posta elettronica del destinatario.
  • ccUids: un array contenente gli UID del destinatario CC.
  • bcc: un singolo indirizzo di posta elettronica del destinatario o un array contenente più indirizzi di posta elettronica del destinatario.
  • bccUids: un array contenente gli UID del destinatario 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 recapitano le e-mail in base agli UID utente con chiave agli indirizzi e-mail all'interno di un documento Cloud Firestore. Per utilizzare queste opzioni del destinatario, 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'e-mail. In genere, questo campo dovrebbe essere popolato solo da codice attendibile in esecuzione nei propri server o funzioni cloud (consultare la sezione "Regole di sicurezza e invio di e-mail" di seguito).

Le proprietà disponibili per il campo message sono:

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

Uso avanzato

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