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

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

הם לעולם אינם מחזירים את סיסמת התיבה או אישורים של ספק SMTP מותאם. המשתמש מזין את הסיסמה ישירות באפליקציית הדואר. גם כשדומיין מנתב הודעות יוצאות דרך ספק מותאם, אפליקציות חיצוניות שולחות ל-endpoint הציבורי של 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, מרחב השמות שהוגדר ורשומת items[] לכל תיבה משותפת שהואצלה לתיבה רגילה זו;
• password_included: false כהבטחת בטיחות מפורשת.

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

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

כאשר הגישה המקורית מושבתת, shared_mailboxes.native_access_enabled הוא false ו-items ריק. כאשר היא מופעלת אך 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 מבקשת מהמשתמש את סיסמת התיבה במהלך ההתקנה. TrekMail מחזיר 409 mail_client_setup_not_ready במקום ליצור פרופיל מטעה כאשר דואר יוצא אינו זמין.

כלי 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.