إدارة عمليات ترحيل البريد الإلكتروني عبر API

تتيح لك 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 مستضاف محليا أن يطلب موافقة صريحة على عمليات كتابة الترحيل. راجع ربط وكلاء الذكاء الاصطناعي (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 واسم المضيف والمنفذ وإعداد الأمان.