הגדרת לקוח דואר באמצעות API ו-MCP

TrekMail חושף דרך REST ו-MCP את אותם נתוני חיבור של אפליקציות ומכשירים שבהם משתמש לוח הבקרה. שני הממשקים לקריאה בלבד ודורשים גישת קריאה לתיבת הדואר.

הממשקים לעולם אינם מחזירים את סיסמת התיבה, סיסמת אפליקציה או פרטי גישה לספק SMTP מותאם. המשתמש מזין סיסמת אפליקציה ישירות באפליקציית הדואר, או את סיסמת התיבה אם היא עדיין מקבלת אותה. גם כשדומיין מנתב הודעות יוצאות דרך ספק מותאם, אפליקציות דואר חיצוניות שולחות לנקודת ה-SMTP הציבורית של TrekMail; TrekMail מחילה מאחוריה את הניתוב הפרטי של הדומיין.

קבלת הגדרות חיבור

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

היקף פנימי נדרש: mailboxes:read. המגבלות האופציונליות domain_ids ו-mailbox_ids של האסימון נאכפות.

התגובה כוללת:

• מארח IMAP נכנס, יציאת SSL, שם משתמש ומצב מוכנות;
• מארח SMTP יוצא, יציאת SSL, שם משתמש ומצב מוכנות;
• כתובת שרת DAV ליומנים ולאנשי קשר, מוכנות החיבור והאם הכתובת ממותגת;
• אותם מדריכים מקומיים בני שלושה שלבים ל-Gmail, Outlook, Apple Mail, Thunderbird ו-IMAP כללי שמוצגים ב-אפליקציות ומכשירים;
• sending.mode: ‏platform, ‏profile או not_configured;
• sending.reason: סיבה יציבה וקריאה למכונה כשהשליחה אינה מוכנה;
• apple_mail_profile.available, שערכו true רק כשהקבלה והשליחה מוכנות;
• shared_mailboxes.native_access_enabled, namespace, items[];
• authentication.client_auth_mode: הערך app_password_only או password_or_app_password;
• authentication.accepted_passwords: הערך ["app_password"] או ["mailbox_password", "app_password"], בהתאמה;
• authentication.app_passwords_endpoint: נקודת הקצה לניהול סיסמאות האפליקציה של התיבה;
• password_included: false כהבטחת בטיחות מפורשת.

shared_mailboxes.items[] כוללת רק חברויות עם הרשאת קריאה כאשר הגישה לתיקיות ביישומי דואר מופעלת. delegated_send_addresses היא רשימה נפרדת של כתובות זמינות לצוות בשדה מאת עם id, email ו־display_name; היא יכולה להיות ריקה. היא אינה נותנת גישה לתיקיות ואינה בדיקת מוכנות לשליחה. כתובות אלה אינן זהויות Message API. השתמשו בשרתים שהוחזרו, גם ב־White Label, במקום להעתיק שם שרת של הפלטפורמה.

כל פריט מואצל כולל native_access_status/native_access_ready קבועים, נתיבים רגילים מדויקים תחת folders, ‏operations שהשרת אוכף וערכי send_as_ready/send_as_reason בפועל. can_send נשאר הרשאת שליחה בשם שהמנהל הקצה; הוא יכול להיות true כאשר SMTP אינו זמין, ולכן האוטומציה חייבת לבדוק את שני שדות המוכנות. תיבת חבר לא פעילה, כניסה מושעית או כניסה ישירה מושבתת משאירות את התיבה המשותפת גלויה, אך מחזירות mailbox_unavailable, ‏mailbox_login_suspended או direct_login_unavailable כסיבת שליחה בשם. השדה הישן folder נשאר הנתיב המדויק לדואר הנכנס. המתינו ל-native_access_ready=true לפני הנחיית המשתמש.

SMTP מעביר תשובה או העברה אך אינו שומר עותק בתיקיית נשלח. לכן sent_copy.smtp_saves_copy הוא false; הגדירו את הלקוח להוסיף עותק אל sent_copy.folder (אותו ערך כמו folders.sent) כדי שכל הצוות יראה אותו. folders.archive ו-folders.junk הם יעדי העברה מדויקים כשהלקוח אינו ממפה ארכיון או ספאם אוטומטית. העברה לזבל לבדה אינה מבטיחה אימון של מסווג הספאם בשרת.

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

רשימת התיקיות shared_mailboxes מתארת גישה מובנית לאנשים שיכולים לקרוא את התיבה. אם items ריק, בדקו גישה מובנית ו־קריאה. רשימה ריקה לא מוכיחה שכל ההרשאות לכתובות משותפות הוסרו. לא מוחזרת סיסמה.

הפרמטר האופציונלי lang מקבל את אותן 13 שפות כמו endpoint הפרופיל של Apple. אם הושמט, TrekMail משתמש ב-Accept-Language ולאחר מכן באזור ברירת המחדל. לכל מדריך יש id יציב, שלושה steps מקומיים ו-action: ‏use_server_settings או download_apple_profile.

connection_status=receiving_only אינו הגדרה מלאה מוצלחת. הגדירו או שחזרו את הנתיב היוצא של הדומיין לפני שתנחו משתמש לחבר לקוח שמאמת את שני השרתים.

connection_status=unavailable פירושו שמחזור החיים של התיבה השתנה והיא אינה יכולה עוד לבצע אימות ישיר. אל תשתמשו בפרטי השרת שהוחזרו ואל תציעו פרופיל Apple Mail; רעננו את מצב התיבה.

הורדת פרופיל Apple Mail

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

התגובה היא קובץ מצורף מסוג .mobileconfig. ערכי lang הנתמכים הם en, ‏es, ‏fr, ‏de, ‏pt, ‏it, ‏nl, ‏ru, ‏zh, ‏ja, ‏ko, ‏ar ו-he. אם lang הושמט, TrekMail משתמש ב-Accept-Language ולאחר מכן באזור ברירת המחדל.

הפרופיל מכיל הגדרות IMAP ו-SMTP ללא שדות סיסמה. Apple מבקשת סיסמה בזמן ההתקנה: השתמשו בסיסמת אפליקציה עבור app_password_only, או באחת משתי הסיסמאות המתקבלות עבור password_or_app_password. TrekMail מחזירה 409 mail_client_setup_not_ready במקום ליצור פרופיל מטעה כשדואר יוצא אינו זמין.

צרו סיסמת אפליקציה בדואר האינטרנט תחת הגדרות, סיסמאות אפליקציה, או בלוח הבקרה תחת תיבות דואר, (תיבת הדואר), אבטחה, סיסמאות אפליקציה. נקודת הקצה להגדרה, שהיא לקריאה בלבד, אינה יוצרת סיסמה. לנקודות קצה של REST ולכלי MCP שמנהלים סיסמאות אלה ואת מצב הכניסה, ראו סיסמאות אפליקציה לדואר באמצעות API ו-MCP.

כלי MCP

הכלים משתמשים באותם REST endpoints וכללי הרשאה:

תעבורות MCP מחזירות תוכן כלי מובנה ולא הורדה בדפדפן. פענחו את content_base64 לבתים ושמרו באמצעות file_name; אל תפרשו אותו כ-JSON או UTF-8 לפני הפענוח.

שני הכלים דורשים את היקף OAuth המתארח mail:read, שמתרחב להיקף הפנימי mailboxes:read. הם לקריאה בלבד ואינם תלויים בדגל סביבתי לפעולות הרסניות בשרת stdio באירוח עצמי.

שגיאות

ה-endpoint של ההגדרה עשוי להחזיר את ערכי sending.reason הבאים: mailbox_unavailable, ‏direct_login_unavailable, ‏domain_unavailable, ‏domain_deprovisioning, ‏account_suspended, ‏email_verification_required, ‏mailbox_sending_disabled, ‏smtp_not_configured, ‏managed_smtp_not_in_plan, ‏managed_smtp_entitlement_inactive, ‏smtp_profile_unavailable או smtp_route_invalid.