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

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

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

• REST API v1 بتنسيق JSON للطلبات والاستجابات.
• مصادقة رمز Bearer: لا ملفات تعريف ارتباط أو جلسات لاستدعاءات API المصادق عليها.
• مفاتيح تكرار آمن في عمليات الكتابة التي تتطلبها، لمنع تكرار العمل أثناء إعادة المحاولة.
• تحديد المعدل لكل رمز مع ترويسات Retry-After.
• سجل تدقيق ظاهر في لوحة التحكم ضمن وكلاء الذكاء الاصطناعي وAPI → سجل التدقيق.
• خادم MCP مزود بكتالوج مصفى وفق بيانات الاعتماد والنقل وإعدادات الأمان للاتصال الحالي. ولذلك لا يرى اتصال المشروع المحدود إلا الأدوات التي يمكنه استخدامها.
• أسماء النطاقات المستعارة: اربط عناوين مخصصة للاستقبال فقط على نطاق ثانوي بالأجزاء المحلية نفسها على نطاق أساسي، مع حالات تسليم محفوظة مقابل نشطة وإزالة آمنة. راجع أسماء النطاقات المستعارة عبر API وMCP.
• بنية الرمزين: رموز عمليات منفصلة للبنية التحتية، ورموز رسائل لعمليات البريد الإلكتروني الكاملة مثل القراءة والإرسال وإنشاء المسودات والجدولة وجهات الاتصال والتقويمات والهويات والقوالب والمجلدات.
• رؤى قابلية التسليم والارتدادات الصادرة: احصل من لوحة التحكم على ملخص الرسائل المرسلة والمسلّمة والارتدادات الدائمة والمؤقتة، إلى جانب رموز SMTP واستجاباته لكل مستلم. راجع قابلية التسليم والارتدادات.
• استخدام مساحة صندوق البريد: تعرض 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 الاستجابة الأصلية دون إنشاء نسخ مكررة.

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

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

وصول صندوق البريد إلى 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.

تقبل نقطة النهاية الجماعية محددا واحدا بالضبط من 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 أيام في غيرها. ولا توجد أحداث أقدم للاستعلام عنها لأن أحداث إعادة التوجيه تحذف دوريا.

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

صندوق البريد المشترك هو صندوق وارد للفريق مثل support@ أو sales@ يفتحه الأعضاء عبر حساب صندوق بريدهم العادي، في بريد الويب، وعند تمكين الوصول الأصلي، كمجلد IMAP مفوض. لا توجد كلمة مرور مشتركة أو عملية دخول منفصلة. الوصول موحد: يستطيع كل عضو القراءة، وتتحكم علامة can_send واحدة فيما إذا كان يستطيع الرد باسم العنوان (true) أو تكون صلاحيته للقراءة فقط (false). ولا توجد أدوار للأعضاء.

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

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

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

تؤدي إزالة عضو أو تغيير 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 قبل إعادة المحاولة.

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

تأخذ 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 على مستوى الحساب.