שימוש בתוסף Trigger Email

התוסף Trigger Email (firestore-send-email) מאפשר לשלוח אימיילים באופן אוטומטי על סמך מסמכים באוסף Cloud Firestore. הוספת מסמך לאוסף תגרום לתוסף הזה לשלוח אימייל שנוצר משדות המסמך. בשדות ברמה העליונה במסמך מציינים את השולח ואת הנמענים, כולל האפשרויות to, cc ו-bcc (כל מזהה ייחודי תומך). בשדה message של המסמך מצוינים שאר רכיבי האימייל, כמו שורת הנושא וגוף האימייל (טקסט פשוט או HTML).

זו דוגמה בסיסית לכתיבת מסמך שתפעיל את התוסף הזה:

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

אפשר גם להגדיר את התוסף הזה כך שיציג אימיילים באמצעות תבניות של Handlebars.

הגדרה לפני ההתקנה

לפני שתתקינו את התוסף, עליכם לבצע את השלבים הבאים:

  1. מגדירים את שירות האימייל היוצא.

    כשמתקינים את התוסף Trigger Email (טריגרים), צריך לציין את פרטי החיבור והאימות של שרת SMTP, שבו התוסף משתמש לשליחת אימיילים. בדרך כלל, השרת הזה מסופק על ידי שירות לשליחת אימיילים כמו Sendgrid,‏ Mailgun או Mailchimp Transactional Email, אבל הוא יכול להיות גם שרת שאתם מנהלים בעצמכם.

  2. יצירת אוסף של מסמכי אימייל.

    התוסף Trigger Email מחפש מסמכים חדשים באוסף Cloud Firestore שציינתם. כשהתוסף מוצא מסמך חדש, הוא שולח אימייל על סמך השדות של המסמך. אפשר להשתמש בכל אוסף Cloud Firestore למטרה הזו. בדוגמאות שבדף הזה נעשה שימוש באוסף בשם email.

  3. הגדרת כללי אבטחה לאיסוף מסמכי אימייל.

    אפשר להשתמש בתוסף הזה כדי להפעיל שליחת אימיילים ישירות מאפליקציות לקוח. עם זאת, חשוב לשלוט בקפידה בגישה של הלקוחות לאוסף כדי למנוע ניצול לרעה פוטנציאלי (לא רוצים שמשתמשים יוכלו לשלוח אימיילים שרירותיים מהכתובת של החברה!).

    כללי האבטחה משתנים מאפליקציה לאפליקציה, אבל תמיד חשוב לוודא שהאימיילים נשלחים רק לנמענים המיועדים, ושתוכן בפורמט חופשי מוגבל למינימום. התבניות יכולות לעזור לכם בכך – תוכלו להשתמש בכללי אבטחה כדי לוודא שהנתונים שמאוכלסים בתבנית תואמים לציפיות שלכם לגבי מה שמשתמש צריך לקבל הרשאה להפעיל.

  4. אופציונלי: מגדירים אוסף משתמשים.

    בשימוש בסיסי בתוסף הזה, מציינים את נמעני האימייל על ידי ציון כתובות האימייל שלהם בשדות to,‏ cc ו-bcc במסמך ההודעה. לחלופין, אם יש לכם מסד נתונים של משתמשים ב-Cloud Firestore, תוכלו לציין נמענים באמצעות מזהי UID של המשתמשים. כדי שאפשר יהיה לעשות זאת, אוסף המשתמשים צריך לעמוד בקריטריונים הבאים:

    • האוסף חייב להיות ממוקד במזהי משתמשים. כלומר, מזהה המסמך של כל מסמך משתמש באוסף חייב להיות מזהה ה-UID‏ Firebase Authentication של המשתמש.
    • לכל מסמך משתמש צריך להיות שדה email שמכיל את כתובת האימייל של המשתמש.

  5. אופציונלי: מגדירים אוסף של תבניות.

    אפשר לעבד הודעות אימייל באמצעות תבניות של סרגלי אחיזה. לשם כך, תצטרכו אוסף Cloud Firestore שיכיל את התבניות.

    פרטים נוספים זמינים במאמר שימוש בתבניות Handlebars עם התוסף Trigger Email.

התקנת התוסף

כדי להתקין את התוסף, פועלים לפי השלבים שבדף התקנת Firebase Extension. לסיכום, יש לבצע אחת מהפעולות הבאות:

  • מסוף Firebase: לוחצים על הלחצן הבא:

    התקנת התוסף Trigger Email

  • CLI: מריצים את הפקודה הבאה: 

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

כשמתקינים את התוסף, צריך לציין את פרטי החיבור ל-SMTP ואת האוספים של Cloud Firestore שהגדרתם קודם.

שימוש בתוסף

אחרי ההתקנה, התוסף הזה עוקב אחרי כל הכתיבה של מסמכים באוסף שהגדרתם. האימייל נשלח על סמך התוכן של השדות במסמך. בשדות ברמה העליונה מציינים את השולח והנמענים של האימייל. השדה message מכיל את פרטי האימייל שרוצים לשלוח, כולל גוף האימייל.

לדוגמה: שליחת אימייל

כדי לשלוח הודעה פשוטה, מוסיפים אוסף הודעות למסמך עם שדה to ושדה message עם התוכן הבא:

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

השדות של השולח והנמען

השדות ברמה העליונה של המסמך מספקים את הפרטים של השולח והנמען של האימייל. השדות הזמינים הם:

  • from: כתובת האימייל של השולח. אם לא צוין במסמך, המערכת תשתמש בפרמטר 'כתובת ברירת המחדל של השולח' שהוגדרה.
  • replyTo: כתובת האימייל לשליחת תשובות. אם לא צוין במסמך, המערכת תשתמש בפרמטר 'כתובת ברירת המחדל של REPLY-TO' שהוגדרה.
  • to: כתובת אימייל אחת של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • toUids: מערך שמכיל את מזהי ה-UID של הנמענים.
  • cc: כתובת אימייל אחת של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • ccUids: מערך שמכיל את מזהי ה-UID של הנמענים לעותק.
  • bcc: כתובת אימייל אחת של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • bccUids: מערך שמכיל את מזהי ה-UID של הנמענים בעותקים מוסתרים.
  • headers: אובייקט של שדות כותרת נוספים (לדוגמה, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

הערה: האפשרויות toUids,‏ ccUids ו-bccUids שולחות אימיילים על סמך מזהי משתמש (UID) שמקושרים לכתובות אימייל במסמך ב-Cloud Firestore. כדי להשתמש באפשרויות הנמענים האלה, צריך לציין קולקציה של Cloud Firestore לפרמטר 'Users collection' של התוסף. לאחר מכן התוסף יכול לקרוא את השדה email לכל UID שצוין בשדות toUids, ccUids ו/או bccUids.

שדה הודעה

השדה message במסמך מכיל את פרטי המסירה הגולמיים של האימייל. באופן כללי, צריך לאכלס את השדה הזה רק בקוד מהימן שפועל בשרתים שלכם או ב-Cloud Functions (ראו את הקטע 'כללי אבטחה ושליחת אימייל' בהמשך).

המאפיינים הזמינים לשדה message הם:

  • messageId: כותרת של מזהה הודעה באימייל, אם יש כזו.
  • subject: הנושא של האימייל.
  • text: תוכן האימייל בטקסט ללא הצפנה.
  • html: תוכן ה-HTML של האימייל.
  • amp: תוכן ה-AMP4EMAIL של האימייל.
  • attachments: מערך שמכיל קבצים מצורפים. אפשרויות Nodemailer נתמכות: מחרוזת UTF-8, סוג תוכן בהתאמה אישית, כתובת URL, מחרוזת מקודדת, URI של נתונים וצומת MIME שנוצר מראש (חשוב לזכור שלאימייל שלכם אין גישה למערכת הקבצים של שרת הענן).

שימוש מתקדם

מידע נוסף על שימוש מתקדם יותר בתוסף הזה: