שימוש בתוסף 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.',
  },
})

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

הגדרה מראש להתקנה

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

  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 שיכיל את התבניות שלך.

    ראה שימוש בתבניות כידון עם תוסף Trigger Email לפרטים.

התקן את ההרחבה

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

  • מסוף 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.',
}

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

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

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

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

שדה הודעה

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

המאפיינים הזמינים עבור שדה message הם:

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

שימוש מתקדם

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