Menggunakan ekstensi Memicu Email

Dengan ekstensi Memicu Email (firestore-send-email), Anda dapat mengirim email secara otomatis berdasarkan dokumen dalam koleksi Cloud Firestore. Menambahkan dokumen ke koleksi akan memicu ekstensi ini untuk mengirim email yang dibuat dari kolom dokumen. Kolom level teratas di dokumen menentukan pengirim dan penerima email, termasuk opsi to, cc, dan bcc (masing-masing mendukung UID). Kolom message di dokumen menentukan elemen lain pada email, seperti baris subjek dan isi email (baik berupa teks biasa maupun HTML).

Berikut contoh dasar penulisan dokumen yang akan memicu ekstensi ini:

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

Anda juga bisa secara opsional mengonfigurasi ekstensi ini untuk merender email menggunakan template Handlebars.

Penyiapan prapenginstalan

Sebelum menginstal ekstensi, selesaikan langkah-langkah berikut:

  1. Siapkan layanan email keluar Anda.

    Saat menginstal ekstensi Memicu Email, Anda harus menentukan detail koneksi dan autentikasi server SMTP, yang digunakan ekstensi untuk mengirim email. Biasanya ini disediakan oleh layanan pengiriman email seperti Sendgrid, Mailgun, atau Mailchimp Transactional Email, tetapi bisa juga merupakan server yang Anda jalankan sendiri.

  2. Buat koleksi dokumen email.

    Ekstensi Memicu Email mendeteksi dokumen baru dalam koleksi Cloud Firestore yang Anda tentukan. Saat menemukan dokumen baru, ekstensi akan mengirimkan email berdasarkan kolom dokumen. Anda dapat menggunakan koleksi Cloud Firestore apa pun untuk tujuan ini; contoh di halaman ini menggunakan koleksi bernama email.

  3. Siapkan aturan keamanan untuk koleksi dokumen email Anda.

    Ekstensi ini dapat digunakan untuk memicu pengiriman email langsung dari aplikasi klien. Namun, Anda harus mengontrol akses klien ke koleksi dengan saksama untuk mencegah potensi penyalahgunaan (jangan sampai pengguna dapat mengirim sembarang email dari alamat perusahaan Anda!).

    Aturan keamanan dapat berbeda dari satu aplikasi ke aplikasi lainnya, tetapi Anda harus selalu memastikan bahwa email dikirim hanya ke penerima yang dituju dan konten format bebas dipertahankan seminimum mungkin. Template dapat membantu di sini—Anda dapat menggunakan aturan keamanan untuk memastikan bahwa data yang diisi ke template sesuai dengan ekspektasi Anda terkait hal yang seharusnya dapat dipicu oleh pengguna.

  4. Opsional: Siapkan koleksi pengguna.

    Dengan penggunaan dasar ekstensi ini, Anda menentukan penerima email dengan menentukan alamat email mereka di kolom to, cc, dan bcc pada dokumen pesan. Sebagai alternatif, jika memiliki database pengguna di Cloud Firestore, Anda dapat menentukan penerima menggunakan UID pengguna. Agar berfungsi, koleksi pengguna Anda harus memenuhi kriteria berikut:

    • Koleksi harus dikuncikan berdasarkan ID pengguna. Artinya, ID dokumen dari setiap dokumen pengguna dalam koleksi harus berupa UID Firebase Authentication pengguna.
    • Setiap dokumen pengguna harus memiliki kolom email yang berisi alamat email pengguna.

  5. Opsional: Siapkan koleksi template.

    Anda dapat merender email menggunakan template Handlebars. Untuk melakukannya, Anda memerlukan koleksi Cloud Firestore untuk memuat template.

    Baca artikel Menggunakan template Handlebars dengan ekstensi Memicu Email untuk mengetahui detailnya.

Menginstal ekstensi

Untuk menginstal ekstensi, ikuti langkah-langkah di halaman Menginstal Firebase Extension kami. Singkatnya, lakukan salah satu langkah berikut:

  • Firebase console: Klik tombol berikut:

    Menginstal ekstensi Memicu Email

  • CLI: Jalankan perintah berikut: 

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

Saat menginstal ekstensi tersebut, Anda akan diminta untuk menentukan informasi koneksi SMTP dan koleksi Cloud Firestore yang Anda siapkan sebelumnya.

Menggunakan ekstensi

Setelah penginstalan, ekstensi ini memantau semua penulisan dokumen ke koleksi yang Anda konfigurasikan. Email dikirimkan berdasarkan konten dari kolom dokumen. Kolom level teratas menentukan pengirim dan penerima email. Kolom message berisi detail email yang akan dikirimkan, termasuk isi email.

Contoh: Mengirim email

Untuk mengirim pesan sederhana, tambahkan dokumen ke koleksi pesan Anda dengan kolom to dan kolom message dengan konten berikut:

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.',
}

Kolom pengirim dan penerima

Kolom level teratas di dokumen menyediakan informasi pengirim dan penerima email. Kolom yang tersedia adalah:

  • from: Alamat email pengirim. Jika tidak ditentukan dalam dokumen, gunakan parameter "Default FROM address" yang telah dikonfigurasi.
  • replyTo: Alamat email balas-ke. Jika tidak ditentukan dalam dokumen, gunakan parameter "Default REPLY-TO address" yang telah dikonfigurasi.
  • to: Satu alamat email penerima atau array yang berisi beberapa alamat email penerima.
  • toUids: Array yang berisi UID penerima.
  • cc: Satu alamat email penerima atau array yang berisi beberapa alamat email penerima.
  • ccUids: Array yang berisi UID penerima CC.
  • bcc: Satu alamat email penerima atau array yang berisi beberapa alamat email penerima.
  • bccUids: Array yang berisi UID penerima BCC.
  • headers: Objek kolom header tambahan (misalnya, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

CATATAN: Opsi toUids, ccUids, dan bccUids mengirimkan email berdasarkan UID pengguna yang dikuncikan ke alamat email dalam dokumen Cloud Firestore. Untuk menggunakan opsi penerima ini, Anda harus menentukan koleksi Cloud Firestore untuk parameter "Users collection" ekstensi. Ekstensi kemudian dapat membaca kolom email untuk setiap UID yang ditentukan di kolom toUids, ccUids, dan/atau bccUids.

Kolom pesan

Kolom message pada dokumen berisi informasi pengiriman mentah untuk email. Kolom ini umumnya hanya akan diisi oleh kode tepercaya yang berjalan di server Anda sendiri atau Cloud Functions (lihat bagian "Aturan keamanan dan mengirim email" di bawah).

Properti yang tersedia untuk kolom message adalah:

  • messageId: Header ID pesan untuk email, jika ada.
  • subject: Subjek email.
  • text: Konten teks biasa pada email.
  • html: Konten HTML pada email.
  • amp: Konten AMP4EMAIL pada email.
  • attachments: Array yang berisi lampiran(-lampiran); Opsi Nodemailer yang didukung: string utf-8, jenis konten kustom, URL, string yang dienkode, URI data, dan node MIME yang telah dibuat sebelumnya (perhatikan bahwa email Anda tidak memiliki akses ke sistem file server cloud).

Penggunaan lanjutan

Pelajari penggunaan lanjutan ekstensi ini: