סיסמאות לאפליקציות דואר באמצעות API ו-MCP

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

סיסמת אפליקציה מאפשרת גישה ל-IMAP, ל-SMTP ביציאות 465 ו-587, ל-ManageSieve ול-CalDAV/CardDAV. היא לעולם אינה פותחת את דואר האינטרנט החדש או את לוח הבקרה. דואר האינטרנט הקלאסי נכנס דרך IMAP ומקבל סיסמאות אפליקציה. 2FA של התיבה מגן רק על הכניסה לדואר האינטרנט החדש; אפליקציות דואר ודואר האינטרנט הקלאסי לעולם אינם מבקשים את הקוד שלו.

לתכונה אין מגבלת תוכנית נפרדת לתיבות דואר. הרשאות התוכנית הקיימות ל-API ול-MCP עדיין חלות; ראו טווחי הרשאות API והרשאות.

אימות, טווחי הרשאות והרשאות חברים

השתמשו באסימון Bearer בבקשות REST תחת /api/v1. כתיבות JSON משתמשות ב-Content-Type: application/json ובכותרת Idempotency-Key.

ההרשאה לקביעת סיסמה נבדקת בתפקיד החבר, בנוסף לטווח ה-API של האסימון. הדבר חל על אסימוני חברים ועל מחברים שחברים אישרו. אסימון של בעל החשבון אינו צריך טווח נוסף לקביעת סיסמה. חוסר בהרשאת החבר מחזיר 403 scope_blocked_by_membership.

מחברי OAuth באירוח יכולים להשתמש בטווחי יכולות REST המתאימים. בחבילות הישנות, mail:read מספק mailboxes:read ו-account:read; mail:write מספק גם mailboxes:write. הרחבת טווחים לעולם אינה עוקפת את כללי הרשאות החברים או את הכללים שמוגבלים לבעל החשבון.

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

נקודות הקצה במבט אחד

הנתיבים שלמטה כוללים את הקידומת /api/v1. ‏{mailbox} הוא מזהה התיבה הרגילה; {id} הוא מזהה רשומת סיסמת אפליקציה ששייכת לה.

כל הכתיבות בטבלה הזו דורשות Idempotency-Key. נקודת הקצה לסיסמה היא פעולת איפוס מנהלית קיימת, נפרדת מהחלפת סיסמת אפליקציה.

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

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

התגובה מכילה את השדות ברמה העליונה mailbox_id, client_auth_mode, limit, active_count ו-data, מערך רשומות. limit הוא 25 סיסמאות פעילות לתיבה. הרשומות הפעילות מופיעות ראשונות, מהחדשה לישנה; רשומות שבוטלו נשארות גלויות 90 יום. אף תגובת רשימה אינה מכילה סוד.

כל רשומה מכילה:

סיבות הביטול הציבוריות הן revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared ו-mailbox_trashed. הרשימה אינה כוללת פרטי גישה שהפלטפורמה מנפיקה לשימוש פנימי.

יצירת סיסמת אפליקציה

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

השדה name נדרש: 1 עד 64 תווים ניתנים להדפסה. רצפים של רווחים מצטמצמים לרווח אחד. התיבה חייבת להיות רגילה ופעילה, ללא השעיית כניסה, עם פחות מ-25 סיסמאות אפליקציה פעילות.

תגובת 201 מכילה את הרשומה המלאה תחת data, מוסיפה data.password וכוללת message. לדוגמה, אלה שדות פרטי הגישה בתגובה הזו:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

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

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

השתמשו בAPI להגדרת לקוח דואר להגדרות החיבור. פרופיל Apple שהורד אינו מכיל סיסמה; המשתמש מזין את סיסמת האפליקציה כש-macOS או iOS מבקשים אותה בזמן ההתקנה.

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

POST /api/v1/mailboxes ו-POST /api/v1/mailboxes:bulk מקבלים ערך בוליאני אופציונלי create_app_password. עם true, כל תיבה שנוצרת מקבלת גם את סיסמת האפליקציה הראשונה שלה, שמוחזרת פעם אחת בתור app_password: שדות הרשומה שתוארו למעלה ועוד password. שמה Created with the mailbox, ולא נשלחת עליה הודעת דוא״ל, כי התיבה חדשה והגורם הקורא קיבל זה עתה את הסיסמה שלה. בלי השדה (ברירת המחדל false) התגובה אינה משתנה. המערכת מתעלמת ממנו כל עוד סיסמאות אפליקציה אינן מופעלות.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

תגובת 201 כוללת אז את one_time_password, סיסמת התיבה לדואר האינטרנט, ואת app_password.password לאפליקציות דואר. בתגובה לפעולה בכמות גדולה, לכל שורה שנוצרה יש app_password משלה. אם לא ניתן היה להנפיק אותה, app_password הוא null (ביצירה בודדת נוסף גם _app_password_warning); התיבה נוצרת בכל זאת, ואפשר ליצור סיסמה בנקודת הקצה שלמעלה. ניסיון חוזר זהה של יצירה בודדת עם אותו Idempotency-Key מחזיר את אותה תגובה, כולל שני הסודות, בלי להנפיק סיסמת אפליקציה שנייה. הרצה חוזרת של בקשה בכמות גדולה משמיטה את הסודות, כמו שהיא עושה עם one_time_password.

החלפה או ביטול של סיסמה

החלפה אינה דורשת גוף JSON:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

תגובת 200 מכילה את הרשומה החדשה המלאה תחת data, את data.password החד-פעמי שלה, את השדה ברמה העליונה replaced_id שמציין את הרשומה הישנה, ואת message. לחלופה יש data.id חדש ואותו שם. הרשומה הישנה מבוטלת עם revoked_reason: "rotated", הסוד שלה מפסיק לעבוד מיד והאפליקציות שמשתמשות בו מנותקות. עדכנו את המכשיר בחלופה.

לביטול ללא הנפקת חלופה:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

אין צורך בגוף בקשה. תגובת 200 מכילה status: "revoked" ואת הרשומה המלאה שבוטלה תחת data. האפליקציה מאבדת גישה; מכשירים אחרים עם סיסמאות אפליקציה תקפות מתחברים מחדש בעצמם. אי אפשר לבטל את פעולת הביטול. ניסיון להחליף או לבטל רשומה שכבר בוטלה בבקשה חדשה מחזיר 409 conflict.

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

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

השדה mode נדרש ומקבל:

• app_password_only: אפליקציות דואר דורשות סיסמת אפליקציה. חיבורים עם סיסמת התיבה מנותקים; אפליקציות עם סיסמת אפליקציה תקפה מתחברות מחדש בעצמן.
• password_or_app_password: אפליקציות דואר מקבלות את סיסמת התיבה או סיסמת אפליקציה.

תגובת 200 מכילה mailbox_id, client_auth_mode ו-message. קביעת המצב הנוכחי שוב מחזירה 200 ואינה משנה דבר. שינוי מצב אינו מבטל סיסמאות אפליקציה קיימות.

צרו סיסמאות למכשירים לפני שדורשים אותן. כניסה שסורבה עם סיסמת התיבה עשויה להציג: "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (הכניסה נכשלה. תיבת דואר זו מקבלת רק סיסמאות אפליקציה: צרו אחת בדואר האינטרנט תחת הגדרות > סיסמאות אפליקציה). חלק מהאפליקציות מציגות רק שגיאת סיסמה כללית.

לתיבות משותפות אין כניסה ישירה והן מחזירות 422 mailbox_not_eligible בנקודת הקצה הזו. אי אפשר להעביר תיבות מערכת של הפלטפורמה ל-app_password_only; הדבר מחזיר 422 system_mailbox_protected.

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

שינוי מצבים בכמות גדולה

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

ספקו mode ובורר אחד בדיוק:

מגבלות החשבון והאסימון מצמצמות כל בחירה. מזהה מפורש מחוץ להרשאת הגישה או מזהה לא מוכר מחזיר 404 במקום להחיל בחירה חלקית. דומיין לא מוכר או ששייך לחשבון אחר מחזיר 422 validation_error. אפס בוררים או כמה בוררים מחזירים 422 invalid_selection.

לכל היותר 1000 תיבות יכולות להתאים. בחירה גדולה יותר מחזירה 422 selection_too_large לפני כל שינוי. צמצמו את הבחירה בדומיין או שלחו קבוצות מפורשות.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

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

קריאת מצב התיבה וקביעת ברירת המחדל בחשבון

כשסיסמאות אפליקציה מופעלות, GET /api/v1/mailboxes ו-GET /api/v1/mailboxes/{mailbox} כוללים את השדות האלה במשאבי תיבות הדואר:

• client_auth_mode: הערך app_password_only או password_or_app_password.
• app_passwords_count: מספר שלם של סיסמאות אפליקציה פעילות וגלויות, ללא פרטי גישה פנימיים של הפלטפורמה.

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

GET /api/v1/account דורש account:read. השדות הרגילים ברמה העליונה נשארים זמינים: id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits ו-created_at. הוא מוסיף new_mailbox_client_auth_mode רק כשסיסמאות אפליקציה מופעלות וגם הפלטפורמה מחילה את ברירת המחדל בחשבון על תיבות חדשות. אחרת GET נשאר זמין ומשמיט את השדה הזה.

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

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

השדה הנדרש מקבל את אותם שני מצבים. זהו שדה החשבון היחיד שניתן לכתוב כאן. התגובה כוללת ברמה העליונה id, new_mailbox_client_auth_mode ו-message. PATCH מחזיר 404 אלא אם שני התנאים להצגת השדה מתקיימים, ו-403 scope_blocked_by_membership לכל אסימון חבר או מחבר שחבר אישר.

אסימון של בעל החשבון המוגבל באמצעות domain_ids או mailbox_ids מחזיר 403 token_resource_constrained. השתמשו באסימון של בעל החשבון ללא מגבלות משאבים, או שנו את ברירת המחדל בהגדרות החשבון.

ברירת המחדל משפיעה על תיבות עתידיות שנוצרות בלוח הבקרה, בכמות גדולה, בהזמנות, ב-API או בידי סוכנים. היא לעולם אינה משנה תיבות קיימות. ביצירת תיבה אחת דרך API אפשר לספק במפורש client_auth_mode ב-POST /api/v1/mailboxes; השמטתו מחילה את ברירת המחדל בחשבון. תיבות קיימות שומרות על password_or_app_password עם השקת התכונה. ברירת המחדל לתיבות חדשות היא app_password_only אלא אם בעל החשבון משנה אותה.

איפוס סיסמת התיבה מבטל אוטומטית סיסמאות אפליקציה

POST /api/v1/mailboxes/{mailbox}/password דורש mailboxes:write, את אותה הרשאת קביעת סיסמה לחבר ו-Idempotency-Key. גוף הבקשה דורש password, סיסמת התיבה החדשה, בהתאם למדיניות סיסמאות התיבות. זו אינה נקודת קצה ליצירת סיסמת אפליקציה.

כל איפוס מנהלי מוצלח דרך נקודת הקצה הזו, כולל שינוי סיסמה בידי סוכן MCP, מבטל את כל סיסמאות האפליקציה עם הסיבה mailbox_password_reset. אין אפשרות לוותר על הביטול. כשהתכונה מופעלת, התגובה כוללת app_passwords_revoked, ספירה כמספר שלם, לצד status, sync_pending ו-message:

• 200, ‏status: "updated", ‏sync_pending: false כשסנכרון שרת הדואר הושלם.
• 202, ‏status: "update_pending", ‏sync_pending: true כשהסיסמה נשמרה והסנכרון ממתין. סיסמאות האפליקציה כבר מבוטלות בשלב הזה.

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

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

אידמפוטנטיות וסודות חד-פעמיים

השתמשו ב-Idempotency-Key חדש לכל כתיבה מכוונת, והשתמשו בו שוב רק לניסיון חוזר עקב בעיית תעבורה עם אותה שיטה, נתיב וגוף. מפתחות נדרשים ויכולים לכלול עד 255 תווים. תגובות מוצלחות נשמרות במטמון בחלון ברירת מחדל של 24 שעות; שימוש חוזר במפתח לבקשה אחרת מחזיר 409 idempotency_mismatch.

תגובה חוזרת ליצירה או להחלפה של סיסמת אפליקציה מחזירה את אותם מזהים בטוחים, אבל משמיטה data.password. היא כוללת _idempotency_replay_warning ואת כותרת התגובה X-Idempotency-Replayed: true. תגובה חוזרת אינה יכולה לשחזר סוד שאבד. השתמשו ב-data.id שהוחזר כדי להחליף את הרשומה הפעילה עם מפתח חדש ולקבל חלופה שמישה. עקבו אחר המזהה החדש אחרי ההחלפה.

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

מגבלות קצב ושגיאות

היצירה מוגבלת ל60 לשעה לחשבון, וההחלפה ל30 לשעה לחשבון. משתמשי API ו-MCP חולקים את המכסות האלה בחשבון, ולא מקבלים מכסות נפרדות לכל אסימון. לשינויי מצב בכמות גדולה יש הגבלה נוספת של 10 בקשות לדקה. מגביל ה-API הרגיל חל גם על הנתיבים האלה; ברירת המחדל שלו היא 60 בקשות לדקה לכל אמצעי אימות. בקשה שהגיעה למגבלה מחזירה 429 rate_limited; כבדו את הכותרת Retry-After לפני ניסיון חוזר.

שגיאות משתמשות באובייקט error הרגיל עם code, message, hint, request_id ו-retryable. טפלו בקוד הקריא למכונה במקום להשוות נוסח הודעות.

כלי MCP והגבלת פעולות שמשנות גישה

MCP משתמש באותם כללי הרשאה ובאותם שדות תגובה של REST. הכלים הישירים הם:

כלי יצירת התיבות create_mailbox_generated_password ו-bulk_create_mailboxes מקבלים את אותו קלט אופציונלי create_app_password כמו REST.

כלי כתיבה מקבלים גם idempotency_key אופציונלי. REST משתמש בשדה הגוף mode לשינוי מצב תיבה; כלי ה-MCP קורא לקלט הזה client_auth_mode. הבוררים לפעולה בכמות גדולה כפופים לאותם כללי גישה ולמגבלת 1000 תיבות כמו REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

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

פרופילי החיבור מהספריות של ChatGPT/OpenAI ושל Claude

הפרופילים האלה מספקים קישור הגדרה מאובטח ללוח הבקרה ליצירה ולהחלפה במקום להנפיק סוד בצ׳אט. גם יצירת תיבה נעשית שם דרך קישור ללוח הבקרה, ולכן סיסמת האפליקציה הראשונה מגיעה מהכרטיס התיבה נוצרה בלוח הבקרה, ולא מ-create_app_password. היעד הוא /app/mailboxes/{mailbox_id}/security#app-passwords; המשתמש נכנס ומשלים את הפעולה שם.

פרופיל OpenAI חושף get_mailbox_app_password_setup_link ו-get_mailbox_app_password_replacement_setup_link. פרופיל Claude שומר על השמות create_mailbox_app_password ו-rotate_mailbox_app_password, אבל מחזיר את קישור ההגדרה המאובטח במקום data.password. אל תבטיחו סוד מכלי הספרייה האלה ואל תבקשו מהמשתמש להדביק אחד בשיחה.

לפרטי החיבור, השתמשו ב-get_mail_client_setup. להגדרת מחברים כללית, ראו חיבור סוכני AI. תיבות White Label משתמשות באותה תכונת API ובמארחי דואר אינטרנט ודואר ממותגים; קראו לפרטי הגישה סיסמת אפליקציה בהוראות למשתמש.