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

התוסף Trigger Email (firestore-send-email) מאפשר לשלוח אימיילים באופן אוטומטי על סמך מסמכים באוסף Cloud Firestore. הוספת מסמך לאוסף תגרום לתוסף הזה לשלוח אימייל שנוצר משדות המסמך. השדות ברמה העליונה של המסמך מציינים את השולח ואת הנמענים של האימייל, כולל האפשרויות to,‏ cc ו-bcc (כל אחת תומכת במזהי UID). השדה 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 שנוצר מראש (חשוב לזכור שלאימייל שלכם אין גישה למערכת הקבצים של שרת הענן).

שימוש מתקדם

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