Tetikleyici E-posta uzantısını kullanma

Tetikleyici E-posta uzantısı (firestore-send-email), Cloud Firestore koleksiyonundaki dokümanlara göre e-postaları otomatik olarak göndermenizi sağlar. Koleksiyona belge eklediğinizde bu uzantı, belgenin alanlarından oluşturulan bir e-posta gönderir. Dokümanın üst düzey alanları, to, cc ve bcc seçenekleri (her biri UID'leri destekler) dahil olmak üzere e-posta gönderenini ve alıcılarını belirtir. Belgenin message alanı, konu satırı ve e-posta gövdesi (düz metin veya HTML) gibi diğer e-posta öğelerini belirtir.

Bu uzantıyı tetikleyecek temel bir belge yazma örneğini aşağıda bulabilirsiniz:

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

İsteğe bağlı olarak bu uzantıyı, e-postaları Handlebars şablonlarını kullanarak oluşturacak şekilde de yapılandırabilirsiniz.

Kurulum öncesi ayarlar

Uzantıyı yüklemeden önce şu adımları tamamlayın:

  1. Giden posta hizmetinizi ayarlayın.

    E-posta Tetikleme uzantısını yüklediğinizde, uzantının e-posta göndermek için kullandığı bir SMTP sunucusunun bağlantı ve kimlik doğrulama ayrıntılarını belirtmeniz gerekir. Bu hizmet genellikle Sendgrid, Mailgun veya Mailchimp Transactional Email gibi bir e-posta teslim hizmeti tarafından sağlanır ancak kendinizin çalıştırdığı bir sunucu da olabilir.

  2. E-posta belgeleri koleksiyonu oluşturun.

    Tetikleyici E-posta uzantısı, belirttiğiniz bir Cloud Firestorekoleksiyondaki yeni dokümanları dinler. Yeni bir doküman bulduğunda uzantı, dokümanın alanlarına göre bir e-posta gönderir. Bu amaçla herhangi bir Cloud Firestore koleksiyonunu kullanabilirsiniz. Bu sayfadaki örneklerde email adlı bir koleksiyon kullanılmaktadır.

  3. E-posta dokümanları koleksiyonunuz için güvenlik kuralları oluşturun.

    Bu uzantı, e-posta teslimini doğrudan istemci uygulamalarından tetiklemek için kullanılabilir. Ancak olası kötüye kullanımı önlemek için istemcilerin koleksiyona erişimini dikkatli bir şekilde kontrol etmeniz gerekir (kullanıcıların şirketinizin adresinden rastgele e-postalar gönderebilmesini istemezsiniz).

    Güvenlik kuralları uygulamadan uygulamaya değişir ancak e-postaların her zaman yalnızca amaçlanan alıcılara gönderildiğinden ve serbest biçimli içeriğin minimum düzeyde tutulduğundan emin olmanız gerekir. Bu noktada şablonlardan yararlanabilirsiniz. Şablona doldurulan verilerin, kullanıcının tetiklemesine izin verilmesi gereken işlemlerle ilgili beklentilerinizi karşıladığını doğrulamak için güvenlik kurallarını kullanabilirsiniz.

  4. İsteğe bağlı: Kullanıcı koleksiyonu oluşturun.

    Bu uzantının temel kullanımı kapsamında, ileti dokümanının to, cc ve bcc alanlarına e-posta adreslerini girerek e-posta alıcılarını belirtirsiniz. Alternatif olarak, Cloud Firestore'da bir kullanıcı veritabanınız varsa kullanıcıların UID'lerini kullanarak alıcıları belirtebilirsiniz. Bu özelliğin çalışması için kullanıcı koleksiyonunuzun aşağıdaki ölçütleri karşılaması gerekir:

    • Toplama işlemi, kullanıcı kimliklerine göre anahtarlanmalıdır. Yani, koleksiyondaki her kullanıcı dokümanının doküman kimliği, kullanıcının Firebase Authentication UID'si olmalıdır.
    • Her kullanıcı dokümanında, kullanıcının e-posta adresini içeren bir email alanı olmalıdır.

  5. İsteğe bağlı: Şablon koleksiyonu oluşturun.

    Handlebars şablonlarını kullanarak e-postaları oluşturabilirsiniz. Bunun için şablonlarınızı içeren bir Cloud Firestore koleksiyonuna ihtiyacınız vardır.

    Ayrıntılar için Handlebars şablonlarını Trigger Email uzantısıyla kullanma başlıklı makaleyi inceleyin.

Uzantıyı yükleme

Uzantıyı yüklemek için Firebase Extension yükleme sayfasındaki adımları uygulayın. Özetle, aşağıdakilerden birini yapın:

  • Firebase console: Aşağıdaki düğmeyi tıklayın:

    Tetikleyici E-posta uzantısını yükleme

  • CLI: Aşağıdaki komutu çalıştırın: 

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

Uzantıyı yüklediğinizde SMTP bağlantı bilgilerinizi ve daha önce oluşturduğunuz Cloud Firestore koleksiyonlarını belirtmeniz istenir.

Uzantıyı kullanma

Bu uzantı, yüklendikten sonra yapılandırdığınız koleksiyona yapılan tüm belge yazma işlemlerini izler. E-posta, belgenin alanlarının içeriğine göre teslim edilir. Üst düzey alanlar, e-postanın gönderenini ve alıcılarını belirtir. message alanı, e-posta gövdesi de dahil olmak üzere, teslim edilecek e-postanın ayrıntılarını içerir.

Örnek: E-posta gönderme

Basit bir mesaj göndermek için mesaj koleksiyonunuza aşağıdaki içeriğe sahip bir to alanı ve bir message alanı içeren bir doküman ekleyin:

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

Gönderen ve alıcı alanları

Dokümanın üst düzey alanları, e-posta göndereni ve alıcısı bilgilerini sağlar. Kullanılabilir alanlar şunlardır:

  • from: Gönderenin e-posta adresi. Belgede belirtilmemişse yapılandırılmış "Varsayılan GÖNDEREN adresi" parametresini kullanır.
  • replyTo: Yanıtlama e-posta adresi. Dokümanda belirtilmemişse yapılandırılmış "Varsayılan YANITLA adresi" parametresini kullanır.
  • to: Tek bir alıcı e-posta adresi veya birden fazla alıcı e-posta adresi içeren bir dizi.
  • toUids: Alıcı kullanıcı kimliklerini içeren bir dizi.
  • cc: Tek bir alıcı e-posta adresi veya birden fazla alıcı e-posta adresi içeren bir dizi.
  • ccUids: CC alıcısının UID'lerini içeren bir dizi.
  • bcc: Tek bir alıcı e-posta adresi veya birden fazla alıcı e-posta adresi içeren bir dizi.
  • bccUids: BCC alıcısının UID'lerini içeren bir dizi.
  • headers: Ek üstbilgi alanlarının nesnesi (örneğin, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

NOT: toUids, ccUids ve bccUids seçenekleri, e-postaları Cloud Firestore dokümanındaki e-posta adresleriyle ilişkilendirilmiş kullanıcı kimliklerine göre gönderir. Bu alıcı seçeneklerini kullanmak için uzantının "Kullanıcı koleksiyonu" parametresi için bir Cloud Firestore koleksiyonu belirtmeniz gerekir. Uzantı daha sonra toUids, ccUids ve/veya bccUids alanlarında belirtilen her UID için email alanını okuyabilir.

Mesaj alanı

Belgenin message alanında, e-postanın ham teslimat bilgileri yer alır. Bu alan genellikle yalnızca kendi sunucularınızda veya Cloud Functions'ta çalışan güvenilir kodlarla doldurulmalıdır (aşağıdaki "Güvenlik kuralları ve e-posta gönderme" bölümüne bakın).

message alanı için kullanılabilir özellikler şunlardır:

  • messageId: E-postanın ileti kimliği üstbilgisi (varsa).
  • subject: E-postanın konusu.
  • text: E-postanın düz metin içeriği.
  • html: E-postanın HTML içeriği.
  • amp: E-postanın AMP4EMAIL içeriği.
  • attachments: Ekleri içeren bir dizi; Nodemailer seçenekleri desteklenir: utf-8 dizesi, özel içerik türü, URL, kodlanmış dize, veri URI'si ve önceden oluşturulmuş MIME düğümü (e-postanızın bulut sunucusunun dosya sistemine erişimi olmadığını unutmayın).

İleri düzey kullanım

Bu uzantının daha gelişmiş kullanımı hakkında bilgi edinin: