مسارات البريد الوارد

تحدد المسارات كيفية تعامل MailLand مع رسائل البريد الوارد لنطاق معيّن. يطابق كل مسار الجزء المحلي من عنوان المستلم (الجزء الذي يسبق @) وينفذ إجراءً واحدًا أو أكثر: التخزين، أو التسليم إلى ويب هوك، أو إعادة التوجيه، أو الرفض على مستوى SMTP، أو الإسقاط. تُقيَّم المسارات بترتيب الأولوية (الرقم الأصغر أولاً)، ويفوز أول مسار مطابق.

أنواع المطابقةنسخ رابط القسم

المطابقة غير حساسة لحالة الأحرف وتُجرى دائمًا على الجزء المحلي: يطابق كل من [email protected] و[email protected] مسارًا بنمط support مقيدًا بنفس النطاق.

إجراءات المسارنسخ رابط القسم

حقل actions في المسار هو قائمة تحتوي على واحدة أو أكثر من القيم النصية التالية:

يمكن دمج store وwebhook مع بعضهما البعض ومع forward. أما reject وdrop وunsubscribe فهي نهائية: يجب أن يكون كل منها الإجراء الوحيد في المسار؛ وترفض واجهة البرمجة أي طلب يجمع بين أحدها وأي إجراء آخر.

وجهات إعادة التوجيهنسخ رابط القسم

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

عند إنشاء أو تحديث مسار يحتوي على forward ضمن actions، يقوم MailLand تلقائيًا بما يلي:

1. إنشاء سجل وجهة إعادة توجيه لـ forwardToEmail (أو إعادة استخدام سجل موجود)، ضمن نطاق مستأجرك: يُتذكَّر العنوان نفسه عبر كل مسار يعيد التوجيه إليه.
2. إذا كان العنوان بحاجة إلى تأكيد ولم يُطلب منه ذلك من قبل، يرسل بريدًا إلكترونيًا للتأكيد يحتوي على رابط.

حفظ المسار نفسه ينجح دائمًا؛ فشل بريد التأكيد لا يُفشل حفظ المسار: تبقى الوجهة ببساطة pending (لا يُعاد توجيه أي شيء إليها) إلى أن تعيد إرسال التأكيد.

رابط التأكيدنسخ رابط القسم

الرابط الموجود في بريد التأكيد صالح لمدة 7 أيام وهو للاستخدام مرة واحدة: بمجرد أن يؤكد المستلم أو يرفض، فإن زيارة الرابط مرة أخرى تعرض القرار نفسه فقط، ولا يمكن التراجع عنه بزيارته مجددًا. الرابط المنتهي الصلاحية الذي لم يُبتّ فيه يُعيد 410 Gone عند فتحه مرة أخرى.

• التأكيد: سيُرسَل الآن البريد المُعاد توجيهه من هذا المستأجر إلى العنوان.
• الرفض: نهائي. لن يُعاد توجيه أي شيء إلى العنوان من هذا المستأجر مرة أخرى أبدًا، ولا يمكن للمستأجر طلب التأكيد مجددًا له.

جلب وجهة إعادة توجيهنسخ رابط القسم

GET https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}

{
  "id": "f2k9m3q7p4w8x1",
  "email": "[email protected]",
  "status": "pending",
  "confirmedVia": null,
  "lastSentAt": "2026-09-26T10:00:00Z",
  "confirmedAt": null,
  "declinedAt": null
}

القيمة status هي إحدى pending أو confirmed أو declined. القيمة confirmedVia تكون link عندما يؤكد المالك عبر البريد الإلكتروني، أو verified_domain عندما يكون العنوان على أحد نطاقاتك الخاصة الموثّقة للإرسال ولم يحتج إلى تأكيد، أو null في الحالات الأخرى. تحمل استجابة المسار أيضًا نفس هذا الكائن ضمن forwardDestination (انظر استجابة المسار أدناه).

إعادة إرسال التأكيدنسخ رابط القسم

POST https://api.mail.land/v1/transactional/inbound/forward-destinations/{destinationId}/resend

فقط لوجهة لا تزال pending وتحتاج فعليًا إلى رابط (عنوان على أحد نطاقات الإرسال الموثّقة الخاصة بك يُعيد 409 FORWARD_DESTINATION_NO_CONFIRMATION_NEEDED، لأنه لا يوجد ما يُعاد إرساله). محدود المعدل: بحد أقصى مرة كل 5 دقائق و5 مرات يوميًا لكل وجهة، و50 مرة يوميًا عبر المستأجر بأكمله. تجاوز أي من الحدّين يُعيد 429 FORWARD_CONFIRMATION_RATE_LIMITED.

إنشاء مسارنسخ رابط القسم

تنتمي المسارات إلى نطاق وتُنشأ ضمن ذلك النطاق.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

{
  "name": "Support Inbox",
  "matchType": "exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 10
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Inbox",
    "matchType": "exact",
    "matchPattern": "support",
    "actions": ["store", "webhook"],
    "webhookId": "w4k8m2q7p9x3z1",
    "priority": 10
  }'

الاستجابةنسخ رابط القسم

{
  "id": "r7k3m9q2p4w8x1",
  "name": "Support Inbox",
  "domainId": "k3v9x2m8q1w7z4",
  "domainName": "yourdomain.com",
  "priority": 10,
  "isEnabled": true,
  "matchType": "Exact",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "webhookName": "Support Webhook",
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "forwardToEmail": null,
  "forwardDestination": null,
  "rejectStatus": null,
  "rejectMessage": null,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

تقبل الطلبات matchType بأي حالة أحرف؛ أما الاستجابات فتُعيد دائمًا اسم التعداد بحرف كبير في البداية: Exact، Prefix، Suffix، Contains، PlusAddressing، CatchAll، Regex. لا تقارن قيمة matchType في الاستجابة بسلسلة أحرف صغيرة.

لا يُملأ forwardDestination إلا عندما تتضمن actions قيمة forward؛ ويحمل نفس الكائن الموصوف في جلب وجهة إعادة توجيه:

{
  "...": "...",
  "actions": ["store", "forward"],
  "forwardToEmail": "[email protected]",
  "forwardDestination": {
    "id": "f2k9m3q7p4w8x1",
    "email": "[email protected]",
    "status": "pending",
    "confirmedVia": null,
    "lastSentAt": "2026-09-26T10:00:00Z",
    "confirmedAt": null,
    "declinedAt": null
  }
}

إدراج مسارات نطاقنسخ رابط القسم

GET https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes

يُرجع جميع مسارات النطاق، مرتبة حسب الأولوية (الأدنى أولاً).

curl https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "items": [
    { "id": "r7k3m9q2p4w8x1", "name": "Support Inbox", "priority": 10, "isEnabled": true, "..." : "..." }
  ],
  "totalCount": 1
}

إدراج جميع المساراتنسخ رابط القسم

لإدراج المسارات عبر جميع نطاقات المستأجر، استخدم بدلاً من ذلك نقطة النهاية المُرقّمة بالمؤشر:

GET https://api.mail.land/v1/transactional/inbound/routes

الحصول على تفاصيل مسارنسخ رابط القسم

GET https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تحديث مسارنسخ رابط القسم

PUT https://api.mail.land/v1/transactional/inbound/routes/{routeId}

يطابق نص الطلب طلب الإنشاء، لكن كل حقل اختياري، تُحدَّث فقط الحقول التي ترسلها.

curl -X PUT https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "matchPattern": "help",
    "priority": 5
  }'

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

يعكس قيمة isEnabled دون التأثير على أي حقل آخر. لا يوجد نص طلب.

POST https://api.mail.land/v1/transactional/inbound/routes/{routeId}/toggle

curl -X POST https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1/toggle \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

إعادة ترتيب المساراتنسخ رابط القسم

حدِّث أولوية جميع مسارات نطاق دفعة واحدة، بتمرير معرّفات المسارات بالترتيب المطلوب: يصبح المعرّف الأول ذا أولوية 1، والثاني أولوية 2، وهكذا.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/reorder

{
  "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/reorder \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "routeIds": ["r7k3m9q2p4w8x1", "m2p8w4x1k7q3z9", "x4k1p7m3q9w2z8"]
  }'

اختبار مسارنسخ رابط القسم

تحقّق من المسار الذي سيطابق عنوان مستلم معيّن دون معالجة بريد فعلي.

POST https://api.mail.land/v1/transactional/inbound/domains/{domainId}/routes/test

{
  "emailAddress": "[email protected]"
}

curl -X POST https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/routes/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "[email protected]"
  }'

{
  "matched": true,
  "matchedRouteId": "r7k3m9q2p4w8x1",
  "matchedRouteName": "Support Inbox",
  "actions": ["store", "webhook"]
}

إذا لم يطابق أي مسار، تكون الاستجابة 200 مع matched: false، وتكون matchedRouteId/matchedRouteName/actions جميعها null. أما 404 فيعني أن النطاق غير موجود، أو أن العنوان المُختبَر غير صالح (بلا @).

حذف مسارنسخ رابط القسم

DELETE https://api.mail.land/v1/transactional/inbound/routes/{routeId}

curl -X DELETE https://api.mail.land/v1/transactional/inbound/routes/r7k3m9q2p4w8x1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

أمثلة مساراتنسخ رابط القسم

مسار شامل (catch-all): تخزين كل مستلم غير مطابق:

{
  "name": "Catch All",
  "matchType": "catchall",
  "matchPattern": "*",
  "actions": ["store"],
  "priority": 999
}

العنونة بالإضافة (plus-addressing): توجيه كل صيغ support+*@yourdomain.com إلى ويب هوك واحد:

{
  "name": "Support Tickets",
  "matchType": "plusaddressing",
  "matchPattern": "support",
  "actions": ["store", "webhook"],
  "webhookId": "w4k8m2q7p9x3z1",
  "priority": 5
}

الرفض عبر SMTP: رفض البريد الموجه إلى صندوق متوقف قبل قبوله:

{
  "name": "Retired Mailbox",
  "matchType": "exact",
  "matchPattern": "old-team",
  "actions": ["reject"],
  "rejectStatus": "550 5.1.1",
  "rejectMessage": "Mailbox does not exist",
  "priority": 1
}

شكل النسخة المُعاد توجيههانسخ رابط القسم

النسخة المُعاد توجيهها هي رسالة تراسلية جديدة وعادية، وليست ترحيلًا خامًا للبايتات الأصلية، تُرسَل من نطاقك الموثّق حتى تتمكن من اجتياز DKIM وDMARC لدى مزوّد صندوق بريد الوجهة:

• From: بالصيغة "<اسم المُرسِل الأصلي> via <العنوان المطابق>@<نطاقك>"، مثل "Jane Doe via [email protected]". أي اسم عرض يشبه عنوانًا (يحتوي على @ أو < أو >) يُستبدل بالعنوان الأصلي المجرد، حتى لا تتمكن أي نسخة أبدًا من انتحال علامة تجارية تحت DKIM الخاص بك.
• Reply-To: حقل Reply-To في الرسالة الأصلية إن وُجد، وإلا عنوان المُرسِل الأصلي، حتى تصل الردود إلى الكاتب الحقيقي وليس إليك.
• بدون تتبّع: يكون تتبّع الفتح والنقر مُعطّلاً دائمًا في النسخة المُعاد توجيهها، بغض النظر عن إعدادات التتبّع في مساحة عملك.
• بدون تذييل علامة تجارية: لا يُضاف أبدًا التذييل الذي قد تحمله عمليات الإرسال الأخرى في خطة Free.
• المرفقات: تُصفَّى وفق نفس قواعد الإرسال الصادر عبر واجهة البرمجة (النوع، العدد، الحجم الإجمالي). ما يُستبعد يُذكر في ملاحظة أعلى النسخة: "Forwarded without N attachment(s) that exceed the outbound attachment limits: ..."، تصل النسخة مع ذلك، لكن بدون تلك الأجزاء.
• الوسم: تحمل كل نسخة مُعاد توجيهها الوسم inbound-forward، حتى تتمكن من العثور عليها في سجل رسائلك المعتاد؛ حالة تسليمها (queued، sent، delivered، bounced، إلخ) هي نفس الحالة التي تحصل عليها أي رسالة تراسلية أخرى، لأنها تمر عبر نفس خط التسليم.
• الاستخدام: تُحتسب كل نسخة مُعاد توجيهها كعملية إرسال واحدة ضمن حصة خطتك وفوترتها، وتظهر كسطر "Inbound forward" منفصل في الاستخدام، منفصلًا عن عمليات الإرسال عبر واجهة البرمجة وSMTP والحملات والأتمتة.

ما لا يُعاد توجيهه أبدًانسخ رابط القسم

الرسالة التي تطابق مسار forward لا تُعاد توجيهها، ولا تُفوتَر أبدًا، عندما:

• تُصنَّف كبريد مزعج، أو يكون المُرسِل محظورًا كمصدر بريد مزعج.
• تفشل في اجتياز DMARC بموجب السياسة الفعلية لنطاق المُرسِل، وتكون quarantine أو reject، تُحدَّد هذه السياسة بالصعود من نطاق المُرسِل بحثًا عن أقرب سجل منطبق، بحيث تكون قيمة sp= الخاصة بالنطاق الفرعي أَولى من p= الخاصة بنطاقه التنظيمي، وتُعامَل سجلات t=y (تجريبية) أو pct=0 على أنها بمستوى سياسة أدنى، إذ ستؤدي إعادة توجيهها إلى إعادة توقيع رسالة طلب مُرسِلها صراحةً من المستلمين رفضها.
• تتجاوز هي أو نص HTML/النص العادي فيها حدود الحجم الصادر للمنصة.
• ستؤدي إعادة توجيهها إلى حلقة: تكون الوجهة أحد مستلمي الرسالة نفسها، أو تحمل بالفعل عددًا كبيرًا جدًا من القفزات أو ترويسات Received.

النسخة المؤهلة التي يتعذّر إرسالها مؤقتًا (تأخير سياسة، نافذة حصة، انقطاع) تُعاد المحاولة مع تراجع تدريجي لمدة تصل إلى 24 ساعة، ثم تنتهي صلاحيتها دون إرسال. المسار الذي يُعطَّل أو يُحذف أو تتغيّر وجهته بعد استلام رسالة يوقف أيضًا أي نسخة لا تزال بانتظاره: تظل تهيئة المسار الحالية هي المرجع دائمًا.

التحقق من نتيجة إعادة التوجيهنسخ رابط القسم

كل رسالة واردة طابقت مسار forward تحمل مصفوفة forwards في استجابة تفاصيلها (GET /v1/transactional/inbound/emails/{id}): عنصر واحد لكل وجهة كانت الرسالة في طابور إعادة التوجيه إليها، لترى ما حدث فعليًا لا مجرد الوجهة التي تم ضبطها.

"forwards": [
  {
    "destination": "[email protected]",
    "status": "Admitted",
    "reason": null,
    "omittedAttachmentCount": 0,
    "messageId": "m_01hz3k...",
    "createdAt": "2026-09-26T10:00:00Z",
    "updatedAt": "2026-09-26T10:00:02Z"
  }
]

status تكون إحدى القيم التالية:

Pending وProcessing وDeferred هي الحالات غير النهائية الوحيدة، أي قيمة أخرى نهائية.

استجابات خطأ إعادة التوجيهنسخ رابط القسم

استجابات الخطأنسخ رابط القسم

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

• Inbound Overview: كيفية عمل معالجة البريد الوارد
• Inbound Webhooks: تنسيق حمولة ويب هوك وتسليمها
• Domains: إعداد سجلات MX للبريد الوارد