ניהול העברות דואר אלקטרוני באמצעות API

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

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

• נדרשת תוכנית Starter ומעלה. תוכנית Nano אינה כוללת את כלי העברת הנתונים.
• בתוכניות Pro ו-Agency אפשר להתחיל, לבטל, לנסות שוב ולמחוק העברות נתונים דרך ה-API (migrations:read + migrations:write). בתוכנית Starter אפשר לקרוא העברות דרך ה-API ולהפעיל העברות חדשות מלוח הבקרה.
• בכל חשבון אפשר להפעיל העברה אחת בכל פעם. התחילו העברה חדשה לאחר שהנוכחית מסתיימת, או בטלו תחילה את ההעברה הנוכחית.

טווחים

נקודות קצה

בדיקת חיבור

POST /api/v1/migrations/test-connection
Scope: migrations:write

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

גוף הבקשה:

תגובה (הצלחה):

{
  "success": true,
  "folders": {
    "INBOX": 1234,
    "Sent": 567,
    "Drafts": 12,
    "Work": 89
  }
}

תגובה (כישלון): 422 עם קוד השגיאה connection_failed.

הצגת העברות נתונים

GET /api/v1/migrations
Scope: migrations:read

מחזירה רשימה מחולקת לעמודים של משימות העברת הנתונים בחשבון.

פרמטרים של השאילתה:

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

GET /api/v1/migrations/{id}
Scope: migrations:read

מחזירה מצב מפורט של ההעברה, כולל פירוט ההתקדמות בכל תיקייה.

תגובה:

{
  "data": {
    "id": 5,
    "mailbox_id": 10,
    "mailbox_email": "support@acme.com",
    "provider": "gmail",
    "source_host": "imap.gmail.com",
    "source_email": "j***e@gmail.com",
    "status": "processing",
    "progress": 45,
    "total_messages": 1234,
    "imported_messages": 556,
    "failed_messages": 2,
    "skipped_duplicates": 12,
    "selected_folders": ["INBOX", "Sent"],
    "import_since": "2025-01-01",
    "skip_duplicates": true,
    "folders": [
      { "name": "INBOX", "status": "processing", "expected": 1000, "imported": 450, "failed": 2, "skipped": 10 },
      { "name": "Sent", "status": "pending", "expected": 234, "imported": 0, "failed": 0, "skipped": 0 }
    ],
    "error_message": null,
    "poll_hint_seconds": 10,
    "started_at": "2026-03-13T10:00:00+00:00",
    "finished_at": null,
    "created_at": "2026-03-13T09:59:50+00:00"
  }
}

poll_hint_seconds מציין באיזו תדירות לבדוק עדכונים: 5 שניות במצבים pending/validating/planning,‏ 10 שניות במצב processing, ו-null במצבים סופיים.

source_email מוסתר חלקית לצורכי אבטחה (לדוגמה, j***e@gmail.com).

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

POST /api/v1/migrations
Scope: migrations:write

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

גוף הבקשה:

תגובה: 201 עם משאב משימת ההעברה.

תגובות שגיאה:

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

POST /api/v1/migrations/{id}:cancel
Scope: migrations:write

מבטלת העברת נתונים פעילה. ההעברה חייבת להיות במצב פעיל (pending,‏ validating,‏ planning או processing).

ניסיון חוזר להעברת נתונים

POST /api/v1/migrations/{id}:retry
Scope: migrations:write

מנסה שוב העברה במצב failed או cancelled. מאפסת את ההתקדמות ל-0 ונכנסת מחדש לתהליך האימות.

מחזירה 409 אם העברת נתונים אחרת כבר פועלת בחשבון.

העברות חלקיות

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

מחיקת העברת נתונים

DELETE /api/v1/migrations/{id}
Scope: migrations:write

מוחקת רשומת העברה. אסור שההעברה תהיה פעילה (בטלו אותה תחילה).

מחזירה 204 No Content בהצלחה.

מגבלות קצב

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

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

אירועי ביקורת

כל פעולות API ההעברה נרשמות ביומן הביקורת:

• migration_started: התחילה העברת נתונים חדשה
• migration_cancelled: העברת נתונים פעילה בוטלה
• migration_retried: התבצע ניסיון חוזר להעברה שנכשלה או בוטלה
• migration_deleted: רשומת העברה נמחקה

כלי MCP

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

API להעברות מרובות

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

נקודות קצה

בקשת תצוגה מקדימה

POST /api/v1/migrations/bulk/preview
Scope: migrations:write

התגובה כוללת שורות לפי קטגוריות (valid,‏ invalid_source_email,‏ invalid_destination וכן הלאה), מגבלות תוכנית, הערכת זמן ופרטי אחסון.

בקשת התחלת אצווה

POST /api/v1/migrations/bulk
Scope: migrations:write

אותם שדות כמו בתצוגה המקדימה, וגם:

מגבלות מקביליות

מגבלת השרת הגלובלית (20 העברות בו-זמנית) משותפת להעברות יחידות ומרובות.

כלי MCP

כלי MCP להעברות מרובות הם preview_bulk_migration,‏ start_bulk_migration,‏ list_bulk_migrations,‏ get_bulk_migration,‏ cancel_bulk_migration,‏ retry_bulk_migration,‏ resume_bulk_migration,‏ delete_bulk_migration ו-update_bulk_migration_job_password. מנהל MCP באירוח מקומי יכול לדרוש אישור מפורש לפעולות כתיבה.

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

• 403 "insufficient_scope": האסימון זקוק ל-migrations:read או migrations:write. צרו אסימון חדש עם הטווחים הנכונים.
• 403 "token_scope_blocked_by_plan": טווחי העברה דורשים תוכנית בתשלום (Starter ומעלה).
• 409 "active migration running": בטלו את ההעברה הקיימת או המתינו עד שתסתיים.
• 503 "migration_capacity_reached": השרת הגיע לקיבולת המרבית. נסו שוב בעוד כמה דקות.
• 422 בבדיקת test-connection: בדקו את פרטי ההתחברות ל-IMAP, שם המארח, היציאה והגדרת האבטחה.