אמצעי בטיחות וכוונות מחיקה ב-API

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

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

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

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

מחיקה בשני שלבים (כוונות מחיקה)

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

שלב 1: יצירת כוונת מחיקה

POST /api/v1/mailboxes/{id}:delete-intent

פעולה זו יוצרת כוונה מוגבלת בזמן המתארת מה יימחק. התגובה כוללת:

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

בשלב זה לא נמחקים נתונים.

שלב 2: אישור הכוונה

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

כאשר סל המחזור של TrekMail לתיבות דואר מופעל, האישור מעביר את התיבה אל נמחק לאחרונה ומחזיר כוונה שהושלמה עם status: "executed". ניתן לשחזר את התיבה במשך שבעה ימים, בתנאי שבדומיין יש מקום עבורה בזמן השחזור.

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

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

הכותרת X-Confirm-Delete: true נדרשת בבקשת האישור כבדיקת בטיחות נוספת.

דגלי סיכון

בעת יצירת כוונת מחיקה, ה-API בודק תנאים שעשויים להעיד שלא כדאי להמשיך:

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

מגבלות קצב על פעולות הרסניות

לפעולות הרסניות יש שתי שכבות של הגבלת קצב מעבר למגבלת ה-API הרגילה לדקה:

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

כאשר אחת המגבלות מופעלת, מוחזרת 429 Too Many Requests עם הכותרת Retry-After.

בקרת בטיחות MCP לשרתים באירוח מקומי

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

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

אידמפוטנטיות

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

Idempotency-Key: create-mailbox-alice-2024

• אותו מפתח ואותו גוף משחזרים את התגובה המקורית בלי לחזור על הפעולה.
• אותו מפתח וגוף שונה מחזירים 409 Conflict.
• אסימונים שונים משתמשים במרחבי מפתחות עצמאיים.

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

שערי בטיחות לשליחה

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

שער 1: בקרת השרת המקומי

בשרת MCP באירוח מקומי, הגדירו TREKMAIL_ALLOW_SENDING=true כדי לאפשר את הכלי send_message. MCP באירוח משתמש בהרשאות שאושרו במהלך OAuth.

שער 2: אישור לכל קריאה

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

למה נדרשים שני שערים?

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

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

שערי בטיחות להעברת נתונים

להעברת דואר אלקטרוני דרך שרת MCP יש שערי בטיחות משלה, בדומה לשליחה ולפעולות הרסניות.

בקרת שרת מקומי להעברת נתונים

בשרת MCP באירוח מקומי, הגדירו TREKMAIL_ALLOW_MIGRATION=true כדי לאפשר כלי כתיבה להעברות נתונים (start_migration, retry_migration, delete_migration). MCP באירוח משתמש בהרשאות שאושרו במהלך OAuth.

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

כלי העברת נתונים לקריאה בלבד (list_migrations, get_migration) פועלים ללא שערים. test_migration_connection דורש TREKMAIL_ALLOW_MIGRATION=true משום שהוא יוצר חיבורי IMAP יוצאים.

אישור לכל קריאת העברת נתונים

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

• start_migration דורש confirm_start=true
• cancel_migration דורש confirm_cancel=true
• retry_migration דורש confirm_retry=true

ללא פרמטר האישור, הכלי מחזיר שגיאה המבקשת מהסוכן לאשר.

מגבלת מקביליות לכל השרת

ה-API אוכף מגבלה כללית על העברות נתונים בו זמנית (ברירת מחדל: 20). כשהמגבלה מושגת, בקשות חדשות להעברה מחזירות 503 עם migration_capacity_reached ו-retryable: true. כך מוגנים משאבי השרת כאשר חשבונות רבים מועברים במקביל.

רישום ביקורת

כל פעולת API שמשנה נתונים נרשמת ביומן הביקורת, המוצג בלוח הבקרה תחת סוכני AI ו-API → יומן ביקורת. האירועים כוללים:

• אסימון נוצר או בוטל: מי יצר או ביטל אסימון פעולות ומתי.
• אסימון הודעות נוצר או בוטל: מי יצר או ביטל אסימון הודעות.
• כוונה נוצרה: נוצרה כוונת מחיקה לתיבת דואר מסוימת.
• כוונה אושרה: בקשת המחיקה התקבלה.
• מחיקה בוצעה: תיבת הדואר הועברה אל נמחק לאחרונה וחלון השחזור שלה התחיל.
• כוונה פגה: כוונה שלא אושרה פגה לאחר 10 דקות.
• תיבת דואר נוצרה: תיבת דואר חדשה הוקצתה דרך ה-API.
• הזמנה נוצרה: נשלחה הזמנה להגדרת תיבת דואר.
• העברה עודכנה: כללי ההעברה של תיבת דואר שונו.
• בדיקת DNS חוזרת הופעלה: התבקשה בדיקת DNS לדומיין.
• העברת נתונים התחילה: העברת דואר אלקטרוני התחילה דרך ה-API.
• העברת נתונים בוטלה: העברת נתונים פעילה בוטלה.
• העברת נתונים נוסתה שוב: בוצע ניסיון חוזר להעברה שנכשלה או בוטלה.
• העברת נתונים נמחקה: רשומת העברת נתונים נמחקה.
• הודעה נקראה: הודעות הוצגו או נקראו דרך Message API.
• הודעה נשלחה: דואר אלקטרוני נשלח דרך Message API.
• שליחת הודעה נכשלה: ניסיון לשליחת דואר אלקטרוני נכשל.
• דגלי הודעה עודכנו: דגלי ההודעה (נקראה/לא נקראה, מסומנת בכוכב) שונו.
• הודעה נמחקה: הודעה נמחקה מתיקייה בתיבת דואר.
• הודעה הועברה: הודעה הועברה בין תיקיות.
• דומיין נוצר: דומיין נוסף דרך ה-API.
• דומיין נמחק: דומיין הוסר דרך ה-API.
• כרטיס נוצר: כרטיס תמיכה נפתח דרך ה-API.
• כרטיס נענה: תשובה פורסמה בכרטיס.
• כרטיס נסגר: כרטיס נסגר.
• SMTP הוגדר: הגדרות SMTP עודכנו.
• חיבור SMTP נמחק: חיבור SMTP מותאם אישית הוסר.
• בדיקת SMTP נוספה לתור: בדיקת חיבור SMTP התחילה.
• אסימון Cloudflare נמחק: אסימון Cloudflare שמור הוסר דרך ה-API.

כל אירועי Message API, כולל קריאות, שליחות, עדכוני דגלים, מחיקות והעברות, נרשמים במלואם. רשומות ביקורת נשמרות במשך 90 יום.

כל אירוע מתעד את האסימון שנעשה בו שימוש, המשאב שהושפע, כתובת ה-IP ומזהה בקשה.

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

תיקונים מהירים

• הכוונה פגה לפני האישור: צרו כוונת מחיקה חדשה. כוונות פגות לאחר 10 דקות.
• "Missing confirm header": הוסיפו את הכותרת X-Confirm-Delete: true לבקשת האישור.
• 429 באישור מחיקה: הגעתם למגבלה היומית או לזמן ההמתנה. המתינו למשך הזמן המצוין ב-Retry-After.
• סוכן MCP באירוח עצמי מדווח שכלי המחיקה מושבתים: המנהל המקומי יכול להגדיר TREKMAIL_ALLOW_DESTRUCTIVE=true בסביבה של תהליך MCP זה.
• סוכן MCP באירוח עצמי מדווח "Sending is disabled": המנהל המקומי יכול להגדיר TREKMAIL_ALLOW_SENDING=true בסביבה של תהליך MCP זה.
• סוכן MCP מדווח "Send not confirmed": הסוכן חייב להעביר confirm_send=true כפרמטר בכל קריאה אל send_message.
• סוכן MCP באירוח עצמי מדווח שכלי העברת הנתונים מושבתים: המנהל המקומי יכול להגדיר TREKMAIL_ALLOW_MIGRATION=true בסביבה של תהליך MCP זה.
• 503 "migration_capacity_reached": יותר מדי העברות נתונים פועלות בכל השרת. המתינו כמה דקות ונסו שוב.
• 409 "active migration running": בטלו את העברת הנתונים הקיימת או המתינו לסיומה לפני התחלת העברה חדשה.