MailLandDocs
البريد الوارد

نظرة عامة على البريد الوارد

استقبال ومعالجة رسائل البريد الإلكتروني الواردة عبر بوابة البريد الوارد في Mail.Land

تستقبل بوابة البريد الوارد في MailLand رسائل البريد الإلكتروني على نطاقاتك وتُسلّمها إلى تطبيقك عبر webhooks أو تُخزّنها لاسترجاعها لاحقًا. استخدم معالجة البريد الوارد لبناء صناديق دعم فني، أو لتحليل رسائل مُولَّدة آليًا، أو لتوجيه الردود إلى تطبيقك.

آلية العمل

تكوين نطاقك

وجّه سجلات MX الخاصة بنطاقك إلى خوادم البريد الوارد في MailLand. يحتاج النطاق إلى inboundEnabled ومستأجر نشط. يقبل MailLand البريد فقط للمستلم المطابق لمسار مُفعَّل، أو لأي عنوان إذا كان catchAllEnabled مُفعَّلًا؛ وأي شيء آخر يُرفض عند RCPT.

إنشاء قواعد التوجيه

عرّف مسارات تطابق الجزء المحلي من عنوان المستلم، وحدّد لها إجراءً (إعادة توجيه أو webhook أو تخزين).

استقبال رسائل البريد المُحلَّلة

يعالج MailLand البريد الإلكتروني، فيُحلّل الترويسات والمتن والمرفقات، ثم يُسلّم النتيجة إلى نقطة نهاية webhook الخاصة بك أو يُخزّنها لاسترجاعها عبر API.

إعدادات البريد الوارد

الإعدادات لكل نطاق على حدة، وليست على مستوى مساحة العمل بأكملها:

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

استخدم Authorization: Bearer <token> أو X-API-Key: <api key> للمصادقة.

Get inbound settings
curl https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/settings \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Inbound settings response
{
  "isEnabled": true,
  "catchAllEnabled": true,
  "maxMessageSizeBytes": 26214400,
  "retentionDays": 30,
  "dailyLimit": 10000,
  "storeEmails": true
}

تحديث الإعدادات:

PUT https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/settings
Update settings request
{
  "isEnabled": true,
  "catchAllEnabled": true,
  "maxMessageSizeBytes": 26214400,
  "retentionDays": 30,
  "dailyLimit": 10000,
  "storeEmails": true
}
Update inbound settings
curl -X PUT https://api.mail.land/v1/transactional/inbound/domains/k3v9x2m8q1w7z4/settings \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "isEnabled": true,
    "catchAllEnabled": true,
    "maxMessageSizeBytes": 26214400,
    "retentionDays": 30,
    "dailyLimit": 10000,
    "storeEmails": true
  }'
الحقلالنوعالوصف
isEnabledboolتفعيل/تعطيل معالجة البريد الوارد لهذا النطاق
catchAllEnabledboolقبول البريد لأي مستلم على النطاق، وليس فقط المستلمين المطابقين لمسار مُفعَّل
maxMessageSizeBytesintالحد الأقصى لحجم الرسالة المقبول بالبايت لهذا النطاق، ويُطبَّق برمز SMTP ‎552 5.3.4. تقبل واجهة الإعدادات قيمًا تصل إلى 50 ميبيبايت، لكن المنصة لا تقبل أبدًا أكثر من 25 ميبيبايت بصرف النظر عن هذا الإعداد
dailyLimitintالحد الأقصى لرسائل البريد الوارد المقبولة يوميًا لهذا النطاق
retentionDaysintعدد أيام الاحتفاظ بالرسائل المُخزَّنة. الافتراضي 30، والمسموح من 1 إلى 90
storeEmailsboolما إذا كان سيتم تخزين البريد الإلكتروني المُحلَّل بالكامل لاسترجاعه لاحقًا
routeCountintعدد المسارات المُهيَّأة لهذا النطاق

لا يوجد فحص فيروسات، ولا يوجد webhookUrl/webhookSecret واحد على مستوى مساحة العمل؛ تُربط الـ webhooks بكل مسار عبر webhookId (راجع المسارات).

يتم تطبيق maxMessageSizeBytes وdailyLimit وretentionDays فعليًا. يُستقبل البريد على العنوان ‎<inboundSubdomain>.<domain>‎، وهو المضيف الذي يشير إليه سجل MX، بينما يستمر النطاق الجذري أيضًا في الاستقبال. تُرفض الرسالة التي تتجاوز قيمة maxMessageSizeBytes الخاصة بالنطاق برمز SMTP ‎552 5.3.4، ولا يتجاوز الرفض أبدًا الحد الأقصى للمنصة البالغ 25 ميبيبايت حتى لو تم ضبط قيمة أكبر (تقبل واجهة الإعدادات حتى 50 ميبيبايت، لكن المُطبَّق فعليًا هو 25 ميبيبايت فقط). وعند بلوغ dailyLimit (القيمة الافتراضية 10000) لليوم، يتلقى المرسلون رمز 452 4.2.2 مؤقتًا ويُتوقع منهم إعادة المحاولة لاحقًا؛ ولا تُفقد الرسالة. تُحذف الرسائل المخزَّنة بعد انقضاء retentionDays (الافتراضي 30 يومًا، والمسموح به من 1 إلى 90).

حالات البريد الإلكتروني

تُعاد كسلاسل نصية، وليست كأرقام:

الحالةالوصف
Receivedتم استلام البريد، بانتظار المعالجة
Processingقيد المعالجة (التحليل، فحص البريد المزعج، التوجيه)
Processedتمت معالجته واكتمل إجراؤه
Deliveredتم التسليم بنجاح (إعادة توجيه أو إرسال webhook)
Failedفشلت المعالجة
Expiredانتهت فترة الاحتفاظ؛ تم حذف البريد الإلكتروني

لا توجد حالة منفصلة باسم Quarantined؛ البريد المزعج هو علامة منطقية isSpam على البريد الإلكتروني، مستقلة عن status.

سرد رسائل البريد الوارد

GET https://api.mail.land/v1/transactional/inbound/emails
List inbound emails
curl https://api.mail.land/v1/transactional/inbound/emails \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
المعاملالنوعالافتراضيالوصف
cursorstring-مؤشر غير شفاف من nextCursor الخاص بالصفحة السابقة. اتركه فارغًا للصفحة الأولى.
limitint20عدد العناصر لكل صفحة (بحد أقصى 100)، يُقيَّد بدلًا من أن يُرفض
domainIdstring-التصفية حسب المعرّف العام للنطاق
statusstring-التصفية حسب حالة البريد الإلكتروني (Received، Processing، Processed، Delivered، Failed، Expired)
routeIdstring-التصفية حسب المسار المطابق
isSpambool-التصفية حسب علامة البريد المزعج. تحديد isSpam (سواء true أو false) يقرر بُعد البريد المزعج بنفسه ويُعطّل مرشّح excludeQuarantined الافتراضي، لذا فإن isSpam=true تُعيد صفوف البريد المزعج (لا تزال خاضعة لقاعدة "المخزَّن فقط" أدناه). احذف isSpam للإبقاء على الإعداد الافتراضي لصندوق الوارد الذي يُخفي البريد المزعج.
fromdatetime-الرسائل المستلمة بعد هذا الوقت
todatetime-الرسائل المستلمة قبل هذا الوقت
searchstring-البحث في الموضوع والمرسل (العنوان أو الاسم)؛ لا يطابق المستلم
sortBystring-حقل الترتيب: subject أو from أو الافتراضي receivedAt
sortDescbooltrueالترتيب تنازليًا
excludeQuarantinedbooltrueاستبعاد الرسائل المُعلَّمة كبريد مزعج من القائمة. يُتجاهَل عند تحديد isSpam.
includeWebhookOnlyboolfalseتضمين الرسائل التي لم تُخزَّن عند الاستلام (مسارات webhook فقط أو مسارات الإسقاط). افتراضيًا هذه مخفية، لذا فإن مستأجرًا كل مساراته webhook فقط سيرى قائمة فارغة هنا.

لا يوجد بحث بالموضوع subject فقط، ولا تصفية بعنوان المرسل/المستلم بمفردهما، وfrom/to هنا تواريخ وليست عناوين (استخدم search لمطابقة نصية في المرسل/الموضوع).

Inbound emails list response
{
  "items": [
    {
      "id": "k7m2x9q4p1w8z3",
      "domainId": "k3v9x2m8q1w7z4",
      "domainName": "yourdomain.com",
      "matchedRouteId": "r7k3m9q2p4w8x1",
      "matchedRouteName": "Support inbox",
      "fromAddress": "[email protected]",
      "fromName": "Customer Name",
      "subject": "Need help with my account",
      "textPreview": "Hi, I need help with...",
      "hasHtml": true,
      "hasText": true,
      "attachmentCount": 1,
      "sizeBytes": 45230,
      "status": "Delivered",
      "spfResult": "Pass",
      "dkimResult": "Pass",
      "dmarcResult": "Pass",
      "isSpam": false,
      "spamScore": 1.2,
      "receivedAt": "2026-02-17T14:30:00Z",
      "expiresAt": "2026-03-19T14:30:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

لا يوجد حقل to في عنصر القائمة؛ يوجد المستلمون في استجابة التفاصيل ضمن envelopeRecipients/headerRecipients. status سلسلة نصية، وليست رقمًا.

الحصول على تفاصيل البريد الإلكتروني

GET https://api.mail.land/v1/transactional/inbound/emails/{id}
Get email details
curl https://api.mail.land/v1/transactional/inbound/emails/{id} \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يُعيد بيانات البريد الإلكتروني الوصفية المُحلَّلة والترويسات ومعاينة نصية وبيانات وصفية للمرفقات، وليس نص HTML/النص الكامل. اجلب الرسالة الخام لذلك (انظر أدناه).

Inbound email detail response
{
  "id": "k7m2x9q4p1w8z3",
  "domainId": "k3v9x2m8q1w7z4",
  "domainName": "yourdomain.com",
  "matchedRouteId": "r7k3m9q2p4w8x1",
  "matchedRouteName": "Support inbox",
  "fromAddress": "[email protected]",
  "fromName": "Customer Name",
  "subject": "Need help with my account",
  "textPreview": "Hi, I need assistance with...",
  "hasHtml": true,
  "hasText": true,
  "attachmentCount": 1,
  "sizeBytes": 45230,
  "status": "Delivered",
  "spfResult": "Pass",
  "dkimResult": "Pass",
  "dmarcResult": "Pass",
  "isSpam": false,
  "spamScore": 1.2,
  "receivedAt": "2026-02-17T14:30:00Z",
  "expiresAt": "2026-03-19T14:30:00Z",
  "envelopeFrom": "[email protected]",
  "replyTo": "[email protected]",
  "messageId": "<[email protected]>",
  "inReplyTo": null,
  "dateHeader": "2026-02-17T14:30:00Z",
  "authResultsHeader": "spf=pass dkim=pass dmarc=pass",
  "spamReason": null,
  "sourceIp": "203.0.113.5",
  "heloHostname": "mail.example.com",
  "processingError": null,
  "processedAt": "2026-02-17T14:30:01Z",
  "envelopeRecipients": [
    { "address": "[email protected]", "localPart": "support", "matchedRouteId": "r7k3m9q2p4w8x1" }
  ],
  "headerRecipients": [
    { "type": "To", "address": "[email protected]", "name": null }
  ],
  "attachments": [
    { "id": "a3k7m2q9p4w1x8", "fileName": "screenshot.png", "contentType": "image/png", "sizeBytes": 34500, "isInline": false, "contentId": null }
  ],
  "webhookAttempts": [
    { "attemptNumber": 1, "status": "Delivered", "webhookUrl": "https://yourapp.com/webhooks/inbound", "httpStatusCode": 200, "errorMessage": null, "durationMs": 145, "attemptedAt": "2026-02-17T14:30:02Z", "nextRetryAt": null }
  ]
}

نتائج المصادقة

تتضمن كل رسالة بريد وارد نتائج التحقق من SPF وDKIM وDMARC. القيم الممكنة تختلف لكل فحص: headerRecipients[].type هي "To" أو "Cc" أو "Bcc" (بحساسية لحالة الأحرف)، وdateHeader هي طابع زمني بصيغة ISO 8601، وليست نص رأس RFC 2822 الخام.

spfResultالوصف
Noneلم يُعثر على سجل SPF أو لم يُجرَ الفحص
Passالمرسل مخوَّل
Failالمرسل غير مخوَّل
SoftFailقد لا يكون المرسل مخوَّلًا
Neutralلا يوجد بيان بشأن التخويل
TempErrorخطأ DNS مؤقت
PermErrorخطأ DNS دائم
dkimResultالوصف
Noneلم يُعثر على توقيع DKIM أو لم يُجرَ الفحص
Passتم التحقق من التوقيع
Failفشل التحقق من التوقيع
TempErrorخطأ DNS مؤقت
PermErrorخطأ DNS دائم
dmarcResultالوصف
Noneلم يُعثر على سياسة DMARC أو لم يُجرَ الفحص
Passنجحت المطابقة
Failفشلت المطابقة
Quarantineتُوصي السياسة بالحجر
Rejectتُوصي السياسة بالرفض

تنزيل البريد الإلكتروني الخام

GET https://api.mail.land/v1/transactional/inbound/emails/{id}/raw
Download raw email
curl https://api.mail.land/v1/transactional/inbound/emails/{id}/raw \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o email.eml

يُعيد البريد الإلكتروني الخام الأصلي (بتنسيق RFC 5322) كملف قابل للتنزيل.

حذف رسائل البريد الإلكتروني

حذف بريد إلكتروني واحد:

DELETE https://api.mail.land/v1/transactional/inbound/emails/{id}
Delete inbound email
curl -X DELETE https://api.mail.land/v1/transactional/inbound/emails/{id} \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

حذف رسائل بالجملة:

POST https://api.mail.land/v1/transactional/inbound/emails/bulk-delete
Bulk delete request
{
  "ids": ["k7m2x9q4p1w8z3", "p3q8w2x7m9k4z1", "w9k3p7m2q8x4z6"]
}
Bulk delete inbound emails
curl -X POST https://api.mail.land/v1/transactional/inbound/emails/bulk-delete \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["k7m2x9q4p1w8z3", "p3q8w2x7m9k4z1", "w9k3p7m2q8x4z6"]
  }'

توجد أيضًا POST /v1/transactional/inbound/emails/bulk-mark-spam بنفس نص الطلب {"ids": [...]}، لوضع علامة بريد مزعج على نفس الدفعة من الرسائل في استدعاء واحد.

العزل

تظهر هنا الرسائل التي تحمل isSpam: true (لا يوجد فحص فيروسات، ولا حالة منفصلة باسم Quarantined؛ البريد المزعج مجرد علامة منطقية). عرض الرسائل المعزولة:

GET https://api.mail.land/v1/transactional/inbound/quarantine
List quarantined emails
curl https://api.mail.land/v1/transactional/inbound/quarantine \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

إطلاق بريد إلكتروني من العزل:

POST https://api.mail.land/v1/transactional/inbound/quarantine/{id}/release
Release from quarantine
curl -X POST https://api.mail.land/v1/transactional/inbound/quarantine/{id}/release \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يقتصر إطلاق البريد الإلكتروني على مسح علامة isSpam الخاصة به فقط. فهو لا يُعيد تشغيل التوجيه ولا يُعيد إرسال الـ webhooks. لإعادة تسليم webhook لبريد تم إطلاقه (أو أي بريد آخر)، استدعِ POST /v1/transactional/inbound/emails/{id}/replay-webhook: هذا يُدرج تسليمًا واحدًا موثوقًا إلى الـ webhook المطابق للمسار، ويعيد 202 Accepted (انظر Inbound Webhooks). كما تُضيف معلمة استعلام اختيارية ?addToAllowlist=true المرسل إلى قائمة السماح وقت الإطلاق.

قائمة السماح وقائمة الحظر

قائمة السماح

تتجاوز الرسائل من المرسلين المُدرجين في قائمة السماح فلترة البريد المزعج:

GET https://api.mail.land/v1/transactional/inbound/allowlist
Get allowlist
curl https://api.mail.land/v1/transactional/inbound/allowlist \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
POST https://api.mail.land/v1/transactional/inbound/allowlist
Add to allowlist
{
  "pattern": "[email protected]",
  "matchType": "ExactEmail",
  "description": "Trusted partner"
}
Add to allowlist
curl -X POST https://api.mail.land/v1/transactional/inbound/allowlist \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "[email protected]",
    "matchType": "ExactEmail",
    "description": "Trusted partner"
  }'

تُعاد وتُرسَل كسلاسل نصية، وليست كأرقام:

نوع المطابقةالوصف
ExactEmailمطابقة عنوان بريد إلكتروني دقيق
Domainمطابقة جميع الرسائل من نطاق
WildcardPatternمطابقة نمط عام (wildcard)

قائمة الحظر

تتم معالجة الرسائل من المرسلين المحظورين تلقائيًا:

GET https://api.mail.land/v1/transactional/inbound/blocklist
Get blocklist
curl https://api.mail.land/v1/transactional/inbound/blocklist \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
POST https://api.mail.land/v1/transactional/inbound/blocklist
Add to blocklist
{
  "pattern": "[email protected]",
  "matchType": "ExactEmail",
  "action": "RejectAtSmtp",
  "description": "Known spammer"
}
Add to blocklist
curl -X POST https://api.mail.land/v1/transactional/inbound/blocklist \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "[email protected]",
    "matchType": "ExactEmail",
    "action": "RejectAtSmtp",
    "description": "Known spammer"
  }'

تُعاد وتُرسَل كسلاسل نصية، وليست كأرقام. الإجراء الافتراضي هو MarkAsSpam إذا لم يُحدَّد:

إجراء الحظرالوصف
RejectAtSmtpالرفض على مستوى SMTP (استجابة 550)
MarkAsSpamالقبول مع وضع علامة بريد مزعج (افتراضي)
Dropإسقاط البريد الإلكتروني بصمت

الحذف من قائمة السماح أو الحظر:

DELETE https://api.mail.land/v1/transactional/inbound/allowlist/{id}
DELETE https://api.mail.land/v1/transactional/inbound/blocklist/{id}
Delete from allowlist or blocklist
# Delete from allowlist
curl -X DELETE https://api.mail.land/v1/transactional/inbound/allowlist/{id} \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Delete from blocklist
curl -X DELETE https://api.mail.land/v1/transactional/inbound/blocklist/{id} \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

إحصائيات البريد الوارد

GET https://api.mail.land/v1/transactional/inbound/stats
Get inbound stats
curl https://api.mail.land/v1/transactional/inbound/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
المعاملالنوعالوصف
domainIdstringالتصفية حسب المعرّف العام للنطاق
fromdatetimeالتصفية حسب receivedAt عند هذا الوقت أو بعده
todatetimeالتصفية حسب receivedAt قبل نهاية هذا اليوم
Inbound stats response
{
  "totalEmails": 1500,
  "todayEmails": 42,
  "receivedCount": 1500,
  "processingCount": 5,
  "processedCount": 1345,
  "failedCount": 20,
  "spamCount": 80,
  "webhookFailedCount": 3,
  "storageUsedBytes": 52428800,
  "byDomain": [
    { "domainId": "k3v9x2m8q1w7z4", "domainName": "yourdomain.com", "count": 1500 }
  ],
  "byStatus": { "Received": 5, "Processing": 5, "Processed": 1345, "Delivered": 1300, "Failed": 20, "Expired": 50 },
  "dailyStats": [
    { "date": "2026-02-17", "total": 120, "processed": 115, "spam": 8 }
  ]
}

لا يوجد حقل spamRate/averageSizeBytes؛ الشكل أعلاه شامل بالكامل.

استجابات الأخطاء

الحالةالرمزالوصف
400VALIDATION_FAILEDمعاملات طلب غير صالحة
403FORBIDDENصلاحيات غير كافية
404RESOURCE_NOT_FOUNDالبريد الإلكتروني غير موجود

الخطوات التالية

  • المسارات: تهيئة قواعد التوجيه لرسائل البريد الوارد
  • Webhooks: استقبال بيانات البريد المُحلَّلة عبر webhook
  • النطاقات: إعداد سجلات MX لمعالجة البريد الوارد

التحقق الجماعي

تحقق من صحة ما يصل إلى 100 عنوان بريد إلكتروني في طلب واحد

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

إعداد قواعد التوجيه لتوجيه رسائل البريد الوارد إلى التخزين أو ويب هوك أو إجراءات أخرى

في هذه الصفحة

آلية العملتكوين نطاقكإنشاء قواعد التوجيهاستقبال رسائل البريد المُحلَّلةإعدادات البريد الواردحالات البريد الإلكترونيسرد رسائل البريد الواردالحصول على تفاصيل البريد الإلكترونينتائج المصادقةتنزيل البريد الإلكتروني الخامحذف رسائل البريد الإلكترونيالعزلقائمة السماح وقائمة الحظرقائمة السماحقائمة الحظرإحصائيات البريد الوارداستجابات الأخطاءالخطوات التالية