שימוש בתוסף 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. אופציונלי: מגדירים אוסף של תבניות.

    אפשר להציג הודעות אימייל באמצעות תבניות Handlebars. לשם כך, תצטרכו אוסף 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 שנוצר מראש (חשוב לזכור שלאימייל שלכם אין גישה למערכת הקבצים של שרת הענן).

שימוש מתקדם

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