نظرة عامة للمطورين على REST API من TrekMail

افتح TrekMail في Claude، واختر Connect وسجّل الدخول واسمح بالوصول. لا تحتاج إلى إنشاء رمز API. يمكنك مراجعة الصلاحيات أو قطع الاتصال في وكلاء الذكاء الاصطناعي وواجهة API، الرموز، التطبيقات المتصلة.

علامتك الخاصة White Label: استخدم عنوان MCP المعروض في لوحة علامتك وسمّ الموصل باسمها. أضفه كـ custom connector؛ صفحة TrekMail العامة تسجّل الدخول عبر TrekMail ولا تحل محل اتصال علامتك.

تتيح لك TrekMail API إدارة النطاقات وصناديق البريد وإعادة التوجيه وDNS وترحيل البريد الإلكتروني وعمليات بريد الويب من عميل HTTP أو وكيل ذكاء اصطناعي. ويشمل ذلك قراءة البريد وإرساله، والمسودات، والجدولة، والمجلدات، وجهات الاتصال، والتقويمات، والهويات، والقوالب، والمرسلين المحظورين. تستخدم الطلبات المصادق عليها رمز Bearer، وتكون الاستجابات بصيغة JSON، ويجري تدقيق نشاط API.

قراءة البريد بمفتاح واحد

في خطتي Pro وAgency، اختر قراءة البريد عند إنشاء مفتاح API. الصلاحية الصريحة هي mailboxes:messages:read؛ أما mailboxes:read فتعرض العناوين وبيانات الاتصال فقط. اختيار جميع الصناديق يشمل الحالية والمستقبلية، ويمكن قصر الوصول على نطاقات وصناديق محددة. لا تحصل المفاتيح الحالية على صلاحيات جديدة تلقائيًا.

استخدم مفتاح الحساب مع مسارات GET أدناه. لا يزال الإرسال والحذف والتعديل يتطلب بيانات وصلاحيات رسائل منفصلة. يقبل MCP المستضاف OAuth وليس tm_live_ أو tm_msg_. يوضح خطأ نوع الرمز للوكيل المسار أو طريقة التفويض الصحيحة.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

ما الذي تحصل عليه

• REST API v1 بتنسيق JSON للطلبات والاستجابات.
• مصادقة رمز Bearer: لا ملفات تعريف ارتباط أو جلسات لاستدعاءات API المصادق عليها.
• مفاتيح تكرار آمن في عمليات الكتابة التي تتطلبها، لمنع تكرار العمل أثناء إعادة المحاولة.
• تحديد المعدل لكل رمز مع ترويسات Retry-After.
• سجل تدقيق ظاهر في لوحة التحكم ضمن وكلاء الذكاء الاصطناعي وAPI، سجل التدقيق.
• خادم MCP مزود بكتالوج مصفى وفق بيانات الاعتماد والنقل وإعدادات الأمان للاتصال الحالي. ولذلك لا يرى اتصال المشروع المحدود إلا الأدوات التي يمكنه استخدامها.
• أسماء النطاقات المستعارة: اربط عناوين مخصصة للاستقبال فقط على نطاق ثانوي بالأجزاء المحلية نفسها على نطاق أساسي، مع حالات تسليم محفوظة مقابل نشطة وإزالة آمنة. راجع أسماء النطاقات المستعارة عبر API وMCP.
• بنية الرمزين: رموز عمليات منفصلة للبنية التحتية، ورموز رسائل لعمليات البريد الإلكتروني الكاملة مثل القراءة والإرسال وإنشاء المسودات والجدولة وجهات الاتصال والتقويمات والهويات والقوالب والمجلدات.
• رؤى قابلية التسليم والارتدادات الصادرة: احصل من لوحة التحكم على ملخص الرسائل المرسلة والمسلّمة والارتدادات الدائمة والمؤقتة، إلى جانب رموز SMTP واستجاباته لكل مستلم. راجع قابلية التسليم والارتدادات.
• كلمات مرور تطبيقات البريد: أدر كلمات مرور منفصلة لـIMAP وSMTP والتقويمات وجهات الاتصال، وحدد كلمات المرور التي تقبلها تطبيقات البريد. لا تحل هذه محل رموز Bearer لواجهة API أو رموز Message API. راجع كلمات مرور تطبيقات البريد عبر API وMCP.
• استخدام مساحة صندوق البريد: تعرض list_mailboxes وget_mailbox القيم used_mb وquota_mb وallocation_mb وis_pooled، ليتمكن الوكيل من اكتشاف صناديق البريد التي تقترب من حدها دون الوصول إلى لوحة التحكم.
• إدارة White Label: افحص الإعداد، وأدر العلامة التجارية لكل نطاق، وادع العملاء، وتحكم في الأدوار والنطاقات، وعلّق الوصول أو استعده، وراجع النشاط عبر API أو MCP. راجع دليل العلامة التجارية ودليل إدارة الفريق.

Drive API وأتمتة الملفات

يعد Drive جزءا من واجهة API العامة. وهو يغطي مساحات Account Drive وDrive الخاصة بصناديق البريد، والاستخدام، وتصفح المجلدات، ورفع الملفات، وإدارة الملفات والمجلدات، وسلة المحذوفات، والإجراءات الجماعية، وروابط المشاركة العامة، وإدارة كلمات مرور أجهزة المزامنة، وحالة إضافة Drive Storage للقراءة فقط.

يستخدم Drive أحد عشر نطاقا لرمز العمليات: drive:account:read وdrive:account:write وdrive:account:share وdrive:account:purge وdrive:mailbox:read وdrive:mailbox:write وdrive:mailbox:share وdrive:mailbox:purge وdrive:addon:read وdrive:devices:read وdrive:devices:write. تظل إجراءات فوترة إضافة Drive وشرائها وتغيير حجمها وإلغائها متاحة عبر لوحة التحكم فقط، ولا تعرض كعمليات كتابة عبر API أو MCP.

ابدأ بـنظرة عامة على Drive API أو البدء السريع مع Drive API.

بنية الرمزين

تستخدم API نوعين مستقلين من الرموز. يمكنك استخدام أحدهما أو كليهما حسب احتياجاتك:

لرموز العمليات ورموز الرسائل نطاقات وحدود معدل منفصلة. ويمكن لوكيل واحد استخدام الرمزين في الوقت نفسه من خلال إعدادهما في بيئة خادم MCP.

تتوفر رموز الرسائل في خطتي Pro وAgency.

قبل أن تبدأ

• تتيح جميع الخطط الوصول إلى API:
  • Nano: أداة التحقق من البريد الإلكتروني. أضف إضافة Drive Storage للوصول الكامل إلى Drive API وMCP.
  • Starter: وصول كامل إلى Drive وأداة التحقق من البريد الإلكتروني، ووصول للقراءة فقط إلى بقية أقسام البنية التحتية. استخدم لوحة التحكم لإجراءات الكتابة فيها.
  • Pro / Agency: وصول أساسي كامل إلى API، بما في ذلك رموز الرسائل. تضاف نطاقات White Label أثناء نشاط الفترة التجريبية أو الإضافة المدفوعة.
• هل توصل وكيل ذكاء اصطناعي؟ أضف https://trekmail.net/mcp كخادم MCP بعيد في أي عميل متوافق. وإذا كان يدعم التفويض عبر المتصفح، فلن تحتاج إلى رمز يدوي. راجع توصيل وكلاء الذكاء الاصطناعي (MCP) لمعرفة خيارات الاتصال البعيد وCLI وسطح المكتب والجسر والاستضافة الذاتية.
• هل تكتب تكاملك الخاص؟ أنشئ رمز tm_live_ ضمن وكلاء الذكاء الاصطناعي وAPI، الرموز، إنشاء رمز وأرسله بصيغة Authorization: Bearer …. راجع إنشاء رموز API وإدارتها.
• هل أنت جديد على API؟ انقر على بدء الجولة أعلى صفحة وكلاء الذكاء الاصطناعي وAPI للاطلاع على شرح موجز لطرق الاتصال وإدارة الرموز والتطبيقات المتصلة وسجل التدقيق.

آلية عمل المصادقة

يجب أن يتضمن كل طلب رمزك في ترويسة Authorization:

Authorization: Bearer tm_live_abc123...

تبدأ رموز العمليات بـtm_live_ وتبدأ رموز الرسائل بـtm_msg_. يعرض كلاهما مرة واحدة عند الإنشاء ولا يمكن عرضهما مجددا.

إذا كان الرمز مفقودا أو ملغى أو منتهي الصلاحية، فستعيد API الرمز 401 مع رمز الخطأ unauthenticated.

عنوان URL الأساسي وتحديد الإصدارات

توجد جميع نقاط النهاية ضمن:

https://trekmail.net/api/v1

يظهر عنوان URL الأساسي في لوحة تحكم وكلاء الذكاء الاصطناعي وAPI ضمن المرجع السريع. يظهر الإصدار في مسار URL. وعند تقديم v2، إن حدث ذلك، سيستمر v1 في العمل.

تنسيق الاستجابة

تعيد الاستجابات الناجحة JSON مع مفتاح data للمورد الفردي أو القائمة المقسمة إلى صفحات:

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

تتبع استجابات الأخطاء بنية موحدة:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

معرّفات الطلبات

تتضمن كل استجابة ترويسة X-Request-Id. ويمكنك أيضا تمرير معرّفك عبر X-Request-Id في الطلب. سيعاد إليك ويسجل في مسار التدقيق.

حدود المعدل

يطبق حد معدل لكل دقيقة على كل رمز. وعند بلوغ الحد، تعيد API الرمز 429 مع ترويسة Retry-After التي تحدد موعد إعادة المحاولة.

للعمليات المدمرة، أي طلبات الحذف، حد يومي إضافي لكل رمز وفترة انتظار بين عمليات الحذف المتتالية.

لعمليات كتابة الترحيل، البدء والإلغاء وإعادة المحاولة، حد مخصص قدره 10 طلبات في الدقيقة لكل رمز، إلى جانب سقف تزامن على مستوى الخادم يعيد 503 عندما تعمل عمليات ترحيل كثيرة عالميا.

تستخدم رموز الرسائل حدودا منفصلة. القيم الافتراضية هي 30 طلب قراءة في الدقيقة لكل رمز، و60 طلب إرسال في الدقيقة لكل رمز، و5,000 قراءة ناجحة يوميا لكل رمز، و100 عملية إرسال عبر API يوميا لصندوق بريد واحد. ولعداد أمان إرسال ثان حد افتراضي قدره 500 لكل رمز يوميا، وعادة يطبق حد صندوق البريد الأقل أولا. لا تحل إجراءات حماية API هذه محل حدود SMTP المُدار لخطتك أو حدود مزود خارجي.

التكرار الآمن

تتطلب نقاط النهاية التي تغير الحالة والمعلّمة بأنها آمنة التكرار ترويسة Idempotency-Key. ويشمل ذلك عمليات الإنشاء والتحديث والإرسال والحذف التي قد يؤدي تكرارها تلقائيا إلى ازدواج العمل. لا تتطلب إجراءات POST الشبيهة بالقراءة، مثل اكتشاف المزود أو اختبار الاتصال، هذه الترويسة؛ تحقق من جدول نقاط النهاية أو مواصفات OpenAPI. وإذا أرسلت المفتاح نفسه مع النص نفسه، تعيد API الاستجابة الأصلية دون إنشاء نسخ مكررة. ويُستثنى من ذلك إرسال الرسائل إذا فشل تسليمها (بسبب حد إرسال مثلا): عندها لا تعيد API الاستجابة 202 السابقة، فيمكن إرسال الرسالة نفسها لاحقا بالمحتوى نفسه. وإذا كنت تمرر معرّفك الخاص عبر X-Request-Id، فاستخدم معرّفا جديدا لهذه المحاولة: إذ تعدّ API أيضا الإرسال من صندوق البريد نفسه بقيمة X-Request-Id نفسها تكرارا، فلا يعيد المعرّف القديم إلا التسليم الأصلي الفاشل، ولا يُرسل شيء. أما إعادة محاولة إرسال ما زال معلقا أو تم تسليمه فتحصل على الاستجابة الأصلية كما كانت.

Idempotency-Key: create-mailbox-alice-2024

إذا أرسلت المفتاح نفسه مع نص مختلف، تعيد API الخطأ 409 Conflict.

تخصيص مساحة صندوق البريد

تقبل كل نقطة نهاية تنشئ صندوق بريد أو دعوة، POST /api/v1/mailboxes و/api/v1/mailboxes:bulk و/api/v1/mailboxes/invites و/api/v1/mailboxes/invites:bulk، عددا صحيحا اختياريا باسم storage_allocation_mb.

يجري التحقق من التخصيصات مقابل المجموعة النشطة بعد طرح صناديق البريد المخصصة الحالية والدعوات المخصصة المعلقة. وتتحقق نقاط النهاية الجماعية أيضا من مجموع التخصيصات في الدفعة، وترفض الدفعة بأكملها مع 422 storage_pool_exceeded إذا كانت ستتجاوز السعة. تتجدد المجموعة عند حذف صندوق بريد مخصص، أو استرداد دعوة، حيث ينتقل التخصيص إلى صندوق البريد الجديد، أو انتهاء صلاحية دعوة معلقة.

بالنسبة إلى الدعوات، يسجل التخصيص على رمز الوصول وينسخ إلى صندوق البريد الجديد وقت الاسترداد. وإذا لم تعد المجموعة تستوعب التخصيص المطلوب وقت الاسترداد، مثلا لأن مسؤولا آخر زاد تخصيصه المخصص في هذه الأثناء، فإن الاسترداد يخفض بسلاسة صندوق البريد الجديد إلى الوضع المشترك بدلا من الفشل، ويرى المستلم إشعارا في صفحة النجاح.

تتبع صناديق البريد العادية الجديدة، بما فيها الإنشاء الجماعي والدعوات والإنشاء بواسطة وكلاء الذكاء الاصطناعي، الإعداد إعدادات الحساب > صناديق البريد الجديدة > تحتاج تطبيقات البريد إلى كلمات مرور التطبيقات المفعّل افتراضيًا. لا يؤدي تغييره إلى تغيير الصناديق الموجودة. يمكن لـPOST /api/v1/mailboxes اختيار client_auth_mode بالقيمة app_password_only أو password_or_app_password؛ وإذا أُغفل الحقل، يُطبّق إعداد الحساب. تعرض موارد قائمة الصناديق وتفاصيلها client_auth_mode وapp_passwords_count (كلمات مرور التطبيقات النشطة). لا تملك الصناديق المشتركة كلمات مرور تطبيقات أو وضع تسجيل دخول خاصًا بها.

أدوات MCP الست لإدارة كلمات مرور التطبيقات هي list_mailbox_app_passwords، create_mailbox_app_password، rotate_mailbox_app_password، revoke_mailbox_app_password، set_mailbox_client_auth_mode، update_account. update_account: عيّن new_mailbox_client_auth_mode للصناديق المستقبلية؛ تحتفظ الصناديق الحالية بوضعها. يتطلب mailboxes:write ورمز صاحب الحساب أو موصله دون قيود على الموارد، وTREKMAIL_ALLOW_DESTRUCTIVE=true في stdio المستضاف ذاتيا.

وصول صندوق البريد إلى Drive

يحمل كل صندوق بريد مستوى drive_access يحدد مقدار ما يصل إليه مستخدمه من Drive في بريد الويب. يظهر المستوى في مورد صندوق البريد ويمكن تعيينه عبر PATCH /api/v1/mailboxes/{id} أو، لعدة صناديق دفعة واحدة، عبر POST /api/v1/mailboxes:drive-access.

مساحة التخزين مشتركة على مستوى الحساب، ولذلك يحدد هذا الخيار مقدار ما يستطيع شخص واحد ملؤه من تلك المجموعة بالملفات.

تعليق تسجيل الدخول إلى صندوق البريد

يمكن تعليق تسجيل الدخول إلى صندوق بريد مع استمرار استلامه للبريد: يرفض بريد الويب وIMAP وSMTP وكلمات مرور الأجهزة، وتنتهي الجلسات المفتوحة، لكن التسليم لا يتأثر، فلا يرتد شيء وتنتظر الرسائل حتى استعادة تسجيل الدخول. اضبطه عبر POST /api/v1/mailboxes/{id}:suspend-login ومعه :resume-login، أو لعدة صناديق عبر POST /api/v1/mailboxes:login-access.

يعرض مورد صندوق البريد الحالة في login_suspended وlogin_suspended_at وlogin_suspended_reason. اقرأ login_suspended لمعرفة ما إذا كان الشخص يستطيع تسجيل الدخول، وstatus لمعرفة ما إذا كان صندوق البريد نفسه يعمل. يبقى الصندوق المعلق active لأنه ما زال يستقبل البريد. أما :pause فهو مختلف: يضبط status على disabled ويوقف التسليم أيضا.

يلغي تعليق تسجيل الدخول جميع كلمات مرور التطبيقات نهائيًا. ولا تعيدها استعادة تسجيل الدخول. كما تُلغى جميعها عندما يعيّن مسؤول كلمة مرور جديدة للصندوق من لوحة التحكم أو API أو وكيل ذكاء اصطناعي، وعند استرداد كلمة المرور أو التحويل إلى صندوق مشترك أو النقل إلى المحذوفة مؤخرًا. ولا تعيدها استعادة صندوق محذوف.

راجع تعليق تسجيل الدخول إلى صندوق البريد عبر API.

تقبل نقطة النهاية الجماعية محددا واحدا بالضبط من mailbox_ids أو domain_id أو all، وتعيد ما نفذته:

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

domain_id هو المحدد المناسب عندما يمثل النطاق عميلا واحدا. تعد صناديق البريد الموجودة بالفعل على المستوى المطلوب ضمن matched لا updated، ولذلك يمكن تكرار الاستدعاء بأمان.

ترفض صناديق البريد المشتركة في نقطة النهاية الفردية مع 422 drive_access_not_applicable، وتتجاوزها نقطة النهاية الجماعية وتحسبها: فليس لها مستخدم بريد ويب خاص بها، بل يفتحها الأعضاء بمستوياتهم، ولن تغير قيمة مخزنة في صف الصندوق المشترك شيئا.

ينطبق القيد على API والواجهة معا. لا تظهر مساحة Drive لصندوق البريد المقيد في GET /api/v1/drive/spaces، وتجيب ملفاته بالرمز 404 عند طلبها بالمعرّف، ولا يمكن إنشاء جهاز مزامنة له.

عناوين إعادة التوجيه

تعيد GET /api/v1/domains/{id}/forwarding-addresses أكثر من القائمة، لأن أمرين يتعلقان بعنوان إعادة التوجيه لا يظهران في العنوان نفسه:

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• يطبق limits.max لكل نطاق ويعتمد على الخطة: 100 في Pro، و300 في Agency، و25 محفوظة ولكن غير نشطة في Nano أو Starter.
• يوضح delivery.active ما إذا كانت هذه القواعد تنقل البريد الآن. تكون قيمته false في خطة أدنى من requires_plan، وتكون false أثناء تعيين paused_until، أي عندما تجاوز الحساب معدل الإرسال بالساعة؛ راجع حدود الإرسال لكل خطة. يمكن أن تكون القاعدة is_active: true ومع ذلك لا تسلّم، لذا اقرأ delivery وليس is_active فقط قبل الإبلاغ بأن إعادة التوجيه تعمل.

يسمح بالإنشاء في خطة لا تستطيع التسليم، ويعيد 201: تحفظ القاعدة وتبدأ العمل عند الترقية. وهذا يماثل لوحة التحكم التي تعرض تلك القواعد كمحفوظة وغير نشطة.

تعود حالات الرفض بالرمز 422 مع تعيين error.code إلى validation_error أو limit_exceeded، وذلك إذا كان العنوان مستخدما بالفعل في النطاق، أو كان المستلم على النطاق نفسه مما ينشئ حلقة، أو لم يكن لنطاق المستلم MX عامل، أو امتلأت حصة النطاق.

يتطلب POST وDELETE في نقاط النهاية هذه مفتاح Idempotency-Key، بينما لا يتطلبه PATCH.

سجل التسليم

تعيد GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log ما حدث فعليا للبريد الحديث، بدءا بالأحدث:

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

تكون outcome واحدة من delivered أو deferred، أي فشل مؤقت مع استمرار إعادة المحاولة، أو failed، أي أن خادم المستلم رفضها، أو blocked. وتعني الأخيرة أن مرشح الرسائل المزعجة لدينا أوقف الرسالة قبل إعادة التوجيه، فلم تصل إلى المستلم أصلا. ومعاملة blocked كارتداد ستدفع شخصا إلى ملاحقة خادم الاستلام بسبب مشكلة حدثت لدينا.

limit بين 1 و200، والقيمة الافتراضية 100، هو المعامل الوحيد. وتمثل النافذة مدة الاحتفاظ للخطة: 30 يوما في Agency و7 أيام في غيرها. ولا توجد أحداث أقدم للاستعلام عنها لأن أحداث إعادة التوجيه تحذف دوريا.

صناديق البريد المشتركة للفريق

للصندوق المشترك وارد فريق خاص به. can_read هي قراءة وcan_send هي إرسال باسم. فتح المجلدات المشتركة يحتاج إلى قراءة، والإرسال من الصندوق عبر Message API يحتاج إلى الصلاحيتين. لا توجد كلمة مرور مشتركة أو دخول منفصل أو أدوار للأعضاء.

تعيد GET /api/v1/mailboxes وGET /api/v1/mailboxes/{id} الآن mailbox_type بقيمة "user" أو "shared"، والقيمة المنطقية is_shared، كما تتضمن صناديق البريد المشتركة shared_member_count. استخدم هذه الحقول لتمييز صندوق الفريق عن الصندوق العادي قبل استدعاء نقاط نهاية الأعضاء.

تؤدي العودة إلى صندوق عادي إلى إزالة جميع الأعضاء. حدد كلمة مرور جديدة لبريد الويب، ثم أنشئ كلمات مرور تطبيقات لتطبيقات البريد في علامة الأمان.

قد يعيد تغيير الأذونات 422 no_access_left إذا كان سيوقف الإذنين، أو 422 send_only_disabled إذا كان التغيير المطلوب في صلاحية قراءة غير متاح، أو 422 last_reader إذا كان آخر قارئ نشط سيفقد الوصول. استخدم إزالة لإنهاء الوصول كله، وامنح عضوا نشطا آخر صلاحية قراءة قبل إزالة آخر قارئ. تعيد كل هذه الأخطاء أيضًا shared_mailbox_id، وmember_id للعضو الموجود، وhint يذكر الطلب الذي يصلح المشكلة.

تعيد نقاط نهاية الأعضاء استخدام نطاقي mailboxes:read وmailboxes:write الحاليين. ولا يوجد نطاق منفصل لصندوق البريد المشترك.

لاكتشاف الوصول الأصلي من تطبيق البريد، استدع GET /api/v1/mailboxes/{member_mailbox_id}/client-setup لصندوق بريد عضو عادي. يعرض كائن shared_mailboxes جاهزية الوصول الأصلي الدائمة، وجاهزية الإرسال الفعلية باسم العنوان وسببها، ومسارات Inbox والمرسل وArchive وJunk الدقيقة، والعمليات المسموح بها. تمثل can_send صلاحية إرسال باسم المعينة، وليست دليلا على جاهزية SMTP حاليا. لا تعيد نقطة النهاية كلمة مرور مطلقا. ويؤدي استدعاؤها بمعرّف صندوق البريد المشترك إلى 422 direct_login_unavailable لأن العنوان المشترك لا يمكنه المصادقة مباشرة.

تشمل shared_mailboxes.items[] العضويات التي لديها صلاحية قراءة عند تفعيل الوصول الأصلي للمجلدات فقط. delegated_send_addresses قائمة منفصلة بعناوين المرسل المتاحة للفريق في حقل من، ولكل منها id وemail وdisplay_name؛ قد تكون فارغة. لا تمنح وصولا للمجلدات ولا تؤكد جاهزية الإرسال. هذه العناوين ليست هويات Message API. استخدم الخوادم المعادة، بما في ذلك White Label، بدلا من نسخ اسم خادم المنصة.

تؤدي إزالة عضو أو تغيير can_read / can_send أو تحويل صندوق مشترك إلى عادي إلى مزامنة أذونات خادم البريد عند تمكين الوصول الأصلي. ويمكن إعادة محاولة استجابة 503 native_access_sync_failed، وهي تضمن بقاء العضوية أو الإذن أو نوع صندوق البريد دون تغيير بدلا من تطبيق العملية جزئيا.

نقاط النهاية المتاحة

لدى Drive مرجعه الخاص ولا يتكرر هنا، راجع نظرة عامة على Drive API. وتوصف نقاط نهاية SMTP على مستوى الحساب، المحفوظة للتوافق مع الإصدارات السابقة، ضمن توجيه SMTP لكل نطاق بدلا من إدراجها كنقاط حالية.

تتبع نقاط نهاية Cloudflare التدفق نفسه في لوحة التحكم: تحقق من الرمز، واسرد المناطق، واربط النطاقات، وعاين تغييرات DNS، ثم طبقها. تقبل كل من /cloudflare/preview و/cloudflare/apply عنصري تحكم اختياريين لكل نطاق:

• included_records، وهي قائمة سماح بالسجلات التي ستتأثر، مفهرسة بمعرّف النطاق: { "123": ["mx_primary", "spf_record"] }. يتم تجاوز السجلات التي لا تدرجها، لذا يمكنك تطبيق MX وSPF فقط والعودة إلى DKIM لاحقا. احذف الحقل لتطبيق كل سجل.
• confirmed_conflicts، عندما تشير المعاينة إلى سجل موجود بالفعل بقيمة مختلفة، أدرج معرّف سجله هنا، بالبنية نفسها { domain_id: [record_ids] }، للسماح باستبداله.

تأتي معرّفات السجلات (mx_primary وspf_record وdkim_primary وdmarc_main و…) مباشرة من استجابة المعاينة، ولذلك يستدعي الوكيل المعتاد المعاينة أولا ويمرر المعرّفات التي يريدها إلى التطبيق:

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

توجيه SMTP لكل نطاق والإعداد الافتراضي للحساب

يضبط SMTP لكل نطاق. يختار كل نطاق واحدا من ثلاثة مسارات: الإرسال المُدار عبر المنصة، أو ملف تعريف SMTP محفوظ، أي مزودك الخاص القابل لإعادة الاستخدام عبر النطاقات، أو "غير مضبوط"، ويحدد إعداد افتراضي واحد على مستوى الحساب المسار الذي تبدأ عليه النطاقات الجديدة.

نقاط النهاية لكل نطاق (smtp:read / smtp:write):

بعض الملاحظات حول نص المسار:

• يحدد smtp_mode=platform الإرسال المُدار؛ ويتطلب smtp_mode=profile القيمة smtp_connection_id؛ أما not_configured فيمسح المسار.
• تجعل smtp_mode=inherit النطاق يتبع مباشرة إعداد الحساب الافتراضي، فكلما تغير الافتراضي تغير هذا النطاق معه. تكتب واجهة الويب دائما مسارات محددة، لكن الخلفية ما زالت تدعم inherit، ولهذا يعيد GET الحقل effective_smtp_mode ليبين القيمة التي يحل إليها inherit حاليا.
• تمثل set_account_default: true في API مفتاح اجعل هذا إعداد الحساب الافتراضي في لوحة التحكم، فتبدأ النطاقات الجديدة على هذا المسار. وتمثل apply_to_all: true زر تطبيق على جميع النطاقات، أي تحويل جميع النطاقات إلى هذا المسار مرة واحدة.

نقاط نهاية الإعداد الافتراضي على مستوى الحساب (smtp:read / smtp:write):

يعيد حذف ملف تعريف كان إعداد الحساب الافتراضي ذلك الإعداد إلى أساس الخطة.

نقاط النهاية القديمة. تظل GET/PUT /api/v1/smtp على مستوى الحساب، ومعها DELETE /api/v1/smtp/{id} وPOST /api/v1/smtp:test وGET /api/v1/smtp:test-status/{jobId}، متاحة للتوافق مع الإصدارات السابقة، لكنها لم تعد تتحكم في التوجيه لكل نطاق: استخدم نقاط النهاية لكل نطاق و/smtp/default أعلاه. كما أصبحت أداتا MCP القديمتان get_smtp_config وupdate_smtp_config مهملتين للسبب نفسه.

علامة White Label التجارية والعملاء ووصول الفريق

تضبط العلامة التجارية لكل نطاق باستخدام branding:read / branding:write. يشغل النطاق علامته الخاصة (mode=custom)، أو يرث إعداد الحساب الافتراضي (mode=inherit)، أو تكون العلامة متوقفة. يلزم توفر فترة تجريبية نشطة لـWhite Label أو إضافة مدفوعة. وبعد الإلغاء، يحتفظ المالك بوصول استرداد للقراءة فقط أثناء مهلة السماح المعروضة. اقرأ dns_records للنطاق وانشر السجلات المعادة كما هي تماما. لا تستنتج أسماء المضيفين أو أهداف CNAME من مثال.

يمثل PATCH دمجا جزئيا، ولذلك تبقى الحقول المحذوفة محفوظة. وإذا كانت العلامة التجارية متوقفة حاليا، فمرر mode لإعادة تمكينها. يجب أن يكون sender_email المخصص على نطاق له مفتاح DKIM متحقق منه. يوفر mail_zone_enabled تطبيقات البريد ومزامنة DAV ضمن نطاق العلامة نفسه. وهو يتبع العلامة لا نطاقا واحدا، ولذلك يحتاج إلى mode=custom أو scope=account_default؛ ويعيد نطاق inherit الخطأ 422 inherited_brand. اقرأ mail_zone.dns_status وmail_zone.client_hosts_status وmail_zone.records وmail_zone.dav_url وmail_zone.dav_ready لتتبع التجهيز، ولا تستخدم إلا عنوان DAV جاهزا. للاطلاع على سير العمل الكامل للوكيل، راجع دليل White Label Branding عبر API وMCP.

تضيف واجهة White Label على مستوى الحساب 13 مسارا ضمن /api/v1/white-label: الحالة وتقدم الإعداد، وكتالوج وصول مباشر، وقائمة الأعضاء وإجراءات دورة حياتهم، ونشاط الحساب، وسجل الإجراءات وتسجيل الدخول لكل عضو. تستخدم members:read وmembers:write وactivity:read. يكون الوصول دائما تقاطع استحقاق الحساب وعضوية الشخص الحالية ومنحة بيانات الاعتماد وأي قيد على النطاق. راجع إدارة فرق White Label باستخدام API وMCP للاطلاع على جدول المسارات وانتقالات الحالة.

تتوفر مواصفات OpenAPI في /api/openapi.json لاستيرادها إلى Postman أو Insomnia أو مولدات التعليمات البرمجية.

إصلاحات سريعة

• 401 "unauthenticated": تحقق من وجود الترويسة Authorization: Bearer <token> ومن أن الرمز لم يلغ أو تنته صلاحيته.
• 403 "plan_api_disabled": النطاق المطلوب غير متاح في خطتك. تغطي Nano أداة التحقق من البريد الإلكتروني، وDrive إذا اشتريت إضافة Drive Storage. قم بالترقية إلى Starter أو أعلى لبقية API.
• 403 "token_scope_blocked_by_plan": يحتوي رمزك على نطاقات غير متاحة في خطتك الحالية. ألغ الرمز وأنشئ رمزا جديدا بالنطاقات المسموح بها.
• 403 "scope_blocked_by_entitlement": منحة White Label المحفوظة غير متاحة لأن الإضافة غير نشطة أو لأن العملية كتابة أثناء فترة السماح. أعد تنشيط White Label، ثم أعد إصدار بيانات الاعتماد أو تفويضها.
• 403 "scope_blocked_by_membership": دور العضو الحالي أضيق من الإجراء المطلوب. اطلب من المالك تغييره؛ لا يمكن لإعادة التفويض وحدها توسيع العضوية.
• 422 "missing_idempotency_key": أضف ترويسة Idempotency-Key إلى عملية الكتابة المذكورة في مرجع نقطة النهاية.
• 403 "mailbox_sending_paused": توقف الإرسال من صندوق البريد لأن بريده الصادر لم يعد يبدو صادرا عن مالكه، وعادة يكون السبب وقوع كلمة المرور في أيد غير صحيحة. تظل القراءة والسرد وجميع نقاط النهاية الأخرى عاملة؛ يرفض الإرسال وحده، ولن تؤدي إعادة المحاولة إلى رفع الإيقاف. يجب تغيير كلمة مرور صندوق البريد، وبعد ذلك يعيد الدعم تشغيل الإرسال. راجع لماذا لا يمكنني إرسال البريد الإلكتروني؟.
• 429 تجاوز حد المعدل: انتظر المدة المحددة في ترويسة Retry-After قبل إعادة المحاولة. وعند بلوغ الحد اليومي لـAPI لكل صندوق بريد، تعيد API أيضا الرمز rate_limited، لكن مع retryable بقيمة false وdimension بقيمة api_mailbox_daily ووقت في resets_at: لن تنجح إعادة المحاولة قبل ذلك، فانتظر حتى هذا الوقت.
• 429 "sending_limit_exceeded": نفد أحد حدود الإرسال. يذكر dimension أي حد هو، ويذكر resets_at موعد تجدده. لا يمكن أن تنجح إعادة المحاولة قبل ذلك، ولهذا تكون قيمة retryable هي false. يبين remaining_today في GET /api/v1/messages/sending-limits عدد المستلمين الإضافيين الذين يمكن لصندوق البريد الإرسال إليهم اليوم. وعندما يكون أدنى حد هو المجموع اليومي للحساب، تكون قيمة limit_today هي null، وكذلك remaining_today إلى أن ينفد ذلك المجموع (فتصبح 0)؛ ويقرأ رمز العمليات هذا المجموع عبر GET /api/v1/sending-limits. وإذا كانت قيمة dimension هي recipients_per_message، فقسّم الرسالة إلى رسائل أصغر. راجع حدود الإرسال لكل خطة.

إرسال البريد الإلكتروني: النص والترويسات وقابلية التسليم

تأخذ POST /api/v1/messages/send بنية الطلب {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.

• كل من body.text وbody.html اختياري، لكن يلزم واحد منهما على الأقل. إذا قدمت body.text فقط، فإننا ننشئ تلقائيا بديلا بصيغة HTML باستخدام فقرات <p>، حيث تفصل الأسطر الفارغة بين الفقرات وتصبح الأسطر الجديدة المفردة <br>، لكي تظهر الرسالة كبريد عادي في كل عميل حديث. وإذا احتجت إلى خط ثابت العرض، فأرسل <pre>...</pre> حرفيا في body.html.
• headers كائن اختياري للترويسات الصادرة التي يقدمها المستخدم. قائمة السماح هي List-Unsubscribe وList-Unsubscribe-Post وReply-To وأي ترويسة تتبع مخصصة من X-*. تدير المنصة الأسماء الأخرى مثل From وSubject وMessage-Id وAuthentication-Results، وترفضها مع 422. وترفض أيضا القيم التي تحتوي على CR/LF للحماية من حقن الترويسات. ويبلغ حد القيم 998 محرفا وفقا لـRFC 2822.
• لحالات الاستخدام الجماعي والأتمتة، راجع قسم ترويسات قابلية التسليم للمرسل الجماعي لإعداد List-Unsubscribe ومفتاح auto_list_unsubscribe على مستوى الحساب.

تعني الاستجابة 202 أن الرسالة قُبلت ولم تُرسل بعد. تُفحص حدود الإرسال مرة أخرى عند خروج الرسالة من قائمة الانتظار، لذا تحقق من النتيجة عبر GET /api/v1/messages/deliveries/{request_id} باستخدام request_id الوارد في الاستجابة 202. ويمكن لأي رمز رسائل لصندوق البريد نفسه التحقق منها، لا الرمز الذي أرسل الرسالة فقط؛ ويعيد request_id غير معروف الخطأ 404. وإذا أوقفها حد ما، فستكون قيمة status هي failed، ويذكر failure الحد (dimension) وموعد تجدده (resets_at). ويمكن إعادة إرسال رسالة فشل إرسالها لاحقا بالمحتوى نفسه. وإذا كنت تمرر معرّفك الخاص عبر X-Request-Id، فاستخدم معرّفا جديدا، لأن المعرّف القديم لا يعيد إلا التسليم الأصلي. والرسالة المجدولة التي تبلغ حدا عند موعدها تُحتجز بالحالة limit_reached وتُحفظ لمدة 7 أيام: اعرض هذه الرسائل عبر GET /api/v1/messages/scheduled?status=limit_reached، وأرسل إحداها لاحقا بتحديد scheduled_for جديد عبر PATCH /api/v1/messages/scheduled/{id}، أو احذفها عبر DELETE.