קבלת אימייל באמצעות Mail API

במדריך הזה מוסבר איך להשתמש ב-Mail API כדי לקבל אימייל.

הודעות אימייל שנשלחות לאפליקציה שלכם מיושמות כבקשות HTTP שמכילות נתוני MIME. כדי לעבד הודעות אימייל נכנסות, אתם משייכים כתובות אימייל ל-handlers של סקריפטים בהגדרת האפליקציה, ואז כוללים את ה-handlers בקוד של האפליקציה.

אימייל נכנס יוצר בקשות HTTP, שמועברות לסקריפטים המתאימים. הסקריפטים שמטפלים באימייל הנכנס צריכים להיות בשירות ברירת המחדל.

מידע נוסף על שירות הדואר זמין במאמר סקירה כללית על Mail API.

לפני שמתחילים

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

הגדרת האפליקציה לקבלת אימייל

כשיוצרים אפליקציה חדשה, אימיילים נכנסים מושבתים כברירת מחדל. כדי להפעיל את האימייל הנכנס, צריך לשנות את קובץ app.yaml בשירות ברירת המחדל.

  1. מוסיפים קטע inbound_services שמאפשר את שירות האימייל הנכנס. לדוגמה:

    inbound_services:
- mail

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

  2. מוסיפים מיפויים שמשייכים כתובות אימייל שממופות לכתובות URL ל-handlers של סקריפטים.

    בשירות ברירת המחדל, כתובת האימייל לקבלת אימייל היא בפורמט הבא:

    [STRING]@[Google Cloud project ID].appspotmail.com

    בשירותים שאינם ברירת מחדל, כתובת האימייל היא בפורמט הבא:

    [STRING]@[servicename]-dot-[Google Cloud project ID].appspotmail.com

    הודעות אימייל נשלחות לאפליקציה שלכם כבקשות HTTP POST באמצעות כתובת ה-URL הבאה, כאשר [ADDRESS] היא כתובת אימייל מלאה, כולל שם הדומיין:

    /_ah/mail/[ADDRESS]

    כדי לטפל באימייל נכנס באפליקציה, צריך למפות כתובות URL של אימייל ל-handlers בקובץ app.yaml:

    - url: /_ah/mail/.+
  script: handle_incoming_email.app
  login: admin

    בדוגמה שלמעלה, /_ah/mail/.+ תואם לכל כתובות האימייל שמופנות לאפליקציה. אם רוצים, אפשר להגדיר כמה פונקציות לטיפול בבקשות לכתובות אימייל שונות, כמו בדוגמה הבאה:

    - url: /_ah/mail/owner@.*your_app_id\.appspotmail\.com
  script: handle_owner.app
  login: admin
- url: /_ah/mail/support@.*your_app_id\.appspotmail\.com
  script: handle_support.app
  login: admin
- url: /_ah/mail/.+
  script: handle_catchall.app
  login: admin

    כתובות ה-URL של הודעות אימייל נכנסות מותאמות לרשימה הזו מההתחלה ועד הסוף, כך שאם כתובת URL של הודעת אימייל תואמת ליותר מתבנית אחת, המטפל הראשון שתואם יהיה זה שיופעל. כך אפשר לכלול את ה-handler של catchall כמפוי האחרון. ה-handlers פועלים במודול ברירת המחדל (או בגרסת האפליקציה).

טיפול באימייל נכנס

כשמשתמשים ב-frameworks של Python לאינטרנט, הקונסטרוקטור InboundEmailMessage מקבל את הבייטים של גוף בקשת ה-HTTP. יש כמה דרכים ליצור את האובייקט InboundEmailMessage ב-Python. ב-Flask, ‏ request.get_data() מחזיר את הבייטים של הבקשה. אובייקט InboundEmailMessage מכיל את הודעת האימייל. השיטה bodies() מחזירה את גופי ההודעות. אם קוראים לפונקציה bodies() בלי ארגומנטים, היא מחזירה איטרטור שמניב קוד HTML, ואז טקסט פשוט. אם רוצים רק HTML או רק טקסט פשוט, אפשר להעביר ארגומנט ל-bodies():

@app.route("/_ah/mail/<path>", methods=["POST"])
def receive_mail(path):
    message = mail.InboundEmailMessage(request.get_data())

    # Do something with the message
    print(
        f"Received greeting for {escape(message.to)} at {escape(message.date)} from {escape(message.sender)}"
    )
    for content_type, payload in message.bodies("text/plain"):
        print(f"Text/plain body: {payload.decode()}")
        break

    return "OK", 200

אובייקט InboundEmailMessage כולל מאפיינים לגישה לשדות אחרים של ההודעה:

  • ‫subject מכיל את נושא ההודעה.
  • ‫sender היא הכתובת של השולח, למשל "Nobody <nobody@example.com>".
  • ‫to היא רשימה מופרדת בפסיקים של הנמענים הראשיים של ההודעה, למשל "Joe <joe@example.com>, Bill <bill@example.com>".
  • ‫cc: רשימה מופרדת בפסיקים של הנמענים שיועתקו, לדוגמה: "Joe <joe@example.com>, Bill <bill@example.com>".
  • ‫date מחזירה את תאריך ההודעה.
  • ‫attachments היא רשימה של Attachment אובייקטים, שיכולה להיות ריקה.
  • ‫original היא ההודעה המלאה, כולל נתונים שלא מוצגים בשדות האחרים, כמו כותרות אימייל, כ-Python‏ email.message.Message.

הדמיה של הודעות נכנסות באמצעות שרת הפיתוח המקומי

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

  1. כדי לגשת לשרת הפיתוח כאדמין, עוברים אל http://localhost:8080/console ובוחרים באפשרות Sign in as administrator (כניסה כאדמין).
  2. בשרת הפיתוח, לוחצים על Inbound Mail (אימייל נכנס) בניווט.

  3. ממלאים את הטופס שמופיע ולוחצים על שליחת אימייל.

    כדי להפעיל את שרת הפיתוח, אפשר לעיין במאמר בנושא שרת פיתוח מקומי.

מידע נוסף על שיקולים להעברה של Mail API זמין במדריך Mail handlers.