התוסף 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.
הגדרה לפני ההתקנה
לפני שתתקינו את התוסף, עליכם לבצע את השלבים הבאים:
מגדירים את שירות האימייל היוצא.
כשמתקינים את התוסף Trigger Email, צריך לציין את פרטי החיבור והאימות של שרת ה-SMTP שבו התוסף משתמש כדי לשלוח אימיילים. בדרך כלל, השרת הזה מסופק על ידי שירות לשליחת אימיילים כמו Sendgrid, Mailgun או Mailchimp Transactional Email, אבל הוא יכול להיות גם שרת שאתם מנהלים בעצמכם.
יצירת אוסף של מסמכים באימייל.
התוסף Trigger Email מחפש מסמכים חדשים באוסף Cloud Firestore שציינתם. כשהתוסף מוצא מסמך חדש, הוא שולח אימייל על סמך השדות של המסמך. אפשר להשתמש בכל אוסף Cloud Firestore למטרה הזו. בדוגמאות שבדף הזה נעשה שימוש באוסף בשם
email
.הגדרת כללי אבטחה לאוסף המסמכים באימייל.
אפשר להשתמש בתוסף הזה כדי להפעיל שליחת אימיילים ישירות מאפליקציות לקוח. עם זאת, חשוב לשלוט בקפידה בגישה של הלקוחות לאוסף כדי למנוע ניצול לרעה פוטנציאלי (לא רוצים שמשתמשים יוכלו לשלוח אימיילים שרירותיים מהכתובת של החברה!).
כללי האבטחה משתנים מאפליקציה לאפליקציה, אבל תמיד חשוב לוודא שהאימיילים נשלחים רק לנמענים המיועדים, ושתוכן בפורמט חופשי מוגבל למינימום. תבניות יכולות לעזור כאן – תוכלו להשתמש בכללי אבטחה כדי לוודא שהנתונים שמאוכלסים בתבנית תואמים לציפיות שלכם לגבי מה שמשתמש צריך לקבל הרשאה להפעיל.
אופציונלי: מגדירים אוסף משתמשים.
בשימוש בסיסי בתוסף הזה, מציינים את נמעני האימייל על ידי ציון כתובות האימייל שלהם בשדות
to
,cc
ו-bcc
במסמך ההודעה. לחלופין, אם יש לכם מסד נתונים של משתמשים ב-Cloud Firestore, תוכלו לציין נמענים באמצעות מזהי ה-UID של המשתמשים. כדי שאפשר יהיה לעשות זאת, אוסף המשתמשים צריך לעמוד בקריטריונים הבאים:- האוסף חייב להיות ממוקד במזהי משתמשים. כלומר, מזהה המסמך של כל מסמך משתמש באוסף חייב להיות מזהה ה-UID של המשתמש Firebase Authentication.
- לכל מסמך משתמש צריך להיות שדה
email
שמכיל את כתובת האימייל של המשתמש.
אופציונלי: מגדירים אוסף של תבניות.
אפשר להציג הודעות אימייל באמצעות תבניות Handlebars. לשם כך, תצטרכו אוסף Cloud Firestore שיכיל את התבניות.
פרטים נוספים זמינים במאמר שימוש בתבניות Handlebars עם התוסף Trigger Email.
התקנת התוסף
כדי להתקין את התוסף, פועלים לפי השלבים שמפורטים בדף התקנת Firebase Extension. לסיכום, מבצעים אחת מהפעולות הבאות:
מסוף Firebase: לוחצים על הלחצן הבא:
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 שנוצר מראש (חשוב לזכור שלאימייל שלכם אין גישה למערכת הקבצים של שרת הענן).
שימוש מתקדם
מידע נוסף על שימוש מתקדם יותר בתוסף הזה: