قابلية التسليم والارتدادات عبر API وMCP

تعرض لوحة تحكم TrekMail نوعين من بيانات الارتداد في علامة تبويب الإحصاءات لكل نطاق:

1. ملخص لمدة 30 يوما: أعداد الرسائل المرسلة والمسلّمة والارتدادات المؤقتة والدائمة، بالإضافة إلى معدلات التسليم والارتداد.
2. قائمة لكل مستلم: آخر 50 ارتدادا للرسائل الصادرة مع رمز حالة SMTP والاستجابة من خادم الاستلام، حتى تتمكن من معرفة سبب فشل رسالة معينة.

يتوفر كلا النوعين الآن من خلال REST API وخادم MCP. يستطيع الوكيل جلب أسباب الارتداد وتلخيص سلامة السمعة وتغذية سير عمل تنظيف القوائم من دون فتح لوحة التحكم مطلقا.

البيانات المتاحة

تتطلب الأدوات الثلاث جميعها domains:read (أو mailboxes:read للقائمة المقصورة على صندوق البريد). وهي للقراءة فقط. لا حاجة إلى مفتاح لتفادي التكرار.

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

REST API: أمثلة سريعة

ملخص النطاق

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

يمثل status الإشارة نفسها ذات الحالات الثلاث التي تعرضها لوحة التحكم:

• good: معدل الارتداد أقل من 2%.
• warning: معدل الارتداد بين 2% و 5%.
• poor: معدل الارتداد يبلغ 5% أو أكثر. راجع قائمة الإرسال ونظفها.

يوضح forwarding_bounces_excluded عدد الارتدادات المرتبطة بإعادة التوجيه التي أزيلت من حساب المعدلات (بما يتوافق مع لوحة التحكم التي تتعامل معها على أنها آثار للتوجيه وليست مشكلات في قائمة المرسل).

قائمة الارتدادات لكل مستلم

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

معلمات الاستعلام

قائمة مقصورة على صندوق البريد

لتحليل سمعة كل مرسل، اقصر النطاق على صندوق بريد واحد:

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

تأتي الاستجابة بالبنية نفسها التي تستخدمها نقطة نهاية النطاق.

خصوصية استجابات SMTP

تزيل TrekMail معلومات التشخيص الداخلية قبل إرجاع استجابة SMTP. الرسالة المتبقية هي نفسها التي تظهر لمالك الحساب في لوحة التحكم، والغرض منها المساعدة في تشخيص التسليم وليس كشف التفاصيل الداخلية للخادم.

أدوات MCP

تقبل الأدوات الثلاث المعلمات نفسها التي تقبلها نقاط نهاية REST. وهي للقراءة فقط ولا تغير البريد أو إعدادات الحساب.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

ترويسات قابلية التسليم للمرسلين بكميات كبيرة

إذا كنت ترسل بريدا تسويقيا أو بريدا جماعيا قائما على الاشتراك، فقد تطلب شركات صناديق البريد الكبرى ترويسات لإلغاء الاشتراك بنقرة واحدة. تطبق Google هذه القاعدة على الرسائل التسويقية ورسائل الاشتراك الواردة من مرسلين يتجاوزون حد الإرسال الجماعي لديها، ولا تطبق قاعدة النقرة الواحدة على رسائل المعاملات. توجد طريقتان لإرفاق الترويسات:

لكل رسالة (تحكم دقيق). مررها من خلال حقل headers في POST /api/v1/messages/send:

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

يقبل حقل headers قائمة سماح صغيرة: List-Unsubscribe وList-Unsubscribe-Post وReply-To وأي ترويسة تتبع مخصصة من نوع X-*. يرفض إدخال الترويسات (CR/LF) والترويسات المدارة (From وSubject وDate وMessage-Id وAuthentication-Results وDKIM-Signature وغيرها) مع الرمز 422.

على مستوى الحساب (ضبط لمرة واحدة). إذا كانت كل رسالة صادرة من هذا الحساب مؤتمتة، يمكنك تفعيل auto_list_unsubscribe في الحساب. عند تفعيله، تضيف المنصة ترويسة List-Unsubscribe تقتصر على عنوان mailto إلى كل رسالة صادرة لا تحتوي عليها بالفعل. ولا تضيف List-Unsubscribe-Post، لذلك لا يوفر هذا الخيار الاحتياطي إلغاء الاشتراك بنقرة واحدة وفقا لمعيار RFC 8058. لتوفير إلغاء اشتراك بنقرة واحدة متوافق مع متطلبات الشركات، أرسل الترويستين لكل رسالة باستخدام نقطة نهاية HTTPS خاصة بك لإلغاء الاشتراك، كما في المثال أعلاه. تكون الأولوية دائما للترويسات التي يوفرها المتصل. يكون المفتاح متوقفا افتراضيا، ولا تتغير الحسابات الحالية.

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

أنماط لوكلاء الذكاء الاصطناعي

تتيح نقاط النهاية هذه بعض أساليب العمل عالية القيمة:

• ملخص أسبوعي للسمعة. في كل يوم اثنين، استدع get_domain_deliverability لكل نطاق في الحساب وانشر ملخصا في Slack أو Teams. اعرض فقط النطاقات التي تكون فيها قيمة status هي warning أو poor.
• تنظيف القائمة بالاستناد إلى الارتدادات. استدع list_domain_bounces?type=hard&days=14، وأزل القيم المكررة من recipient_email، ثم استبعد تلك العناوين من قائمة الإرسال. تعني الارتدادات الدائمة عادة أن عنوان المستلم لم يعد موجودا، وأن إعادة الإرسال تهدر رصيد قابلية التسليم.
• التحليل لكل مرسل. عندما يقفز bounce_rate لصندوق بريد واحد، استدع list_mailbox_bounces له واجمع النتائج حسب smtp_status_code. قد تعني الزيادة المفاجئة في رموز 550 أن قائمة العناوين قديمة، وقد تعني الزيادة في رموز 421 أن خادم البريد المستلم فرض حدا على معدل إرسال رسائلك.
• تحقيق دعم العملاء. عندما يبلغ مستخدم عن عدم وصول بريد إلكتروني، اطلب من الوكيل استدعاء list_domain_bounces?recipient=<their-address>. قد تشير استجابة SMTP إلى الإجراء التالي، مثل إفراغ صندوق بريد المستلم الممتلئ أو إزالة حظر لدى المستلم أو إصلاح رفض DMARC.

إدارة الإصدارات

تتبع نقاط النهاية هذه عقد إدارة الإصدارات نفسه المطبق على بقية API v1: تغييرات إضافية فقط، ولا يعاد تسمية الحقول بطريقة غير متوافقة من دون مساحة أسماء v2/.

مواضيع ذات صلة

• مقاييس البريد المزعج: بيانات حماية البريد الوارد من الرسائل المزعجة (get_spam_metrics وget_spam_summary).
• التحقق من البريد الإلكتروني: تنظيف القائمة قبل الإرسال لمنع حدوث الارتدادات.
• نظرة عامة على API: المصادقة والنطاقات وحدود المعدل وتفادي التكرار.