أحداث Webhook

يحدد كتالوج أحداث MailLand 21 نوع حدث موزعة على 6 فئات (اثنان من أصل الـ21 هما إشعارا منصة لا يمكنك الاشتراك فيهما). يُسلَّم كل حدث كطلب HTTP POST موقّع إلى نقطة نهاية webhook الخاصة بك.

كتالوج الأحداثنسخ رابط القسم

احصل على كتالوج الأحداث الكامل برمجيًا:

GET https://api.mail.land/v1/webhooks/catalog

curl -X GET https://api.mail.land/v1/webhooks/catalog

{
  "version": 1,
  "products": [
    { "id": "transactional", "name": "Transactional Email", "isActive": true, "comingSoon": false },
    { "id": "marketing", "name": "Marketing Email", "isActive": true, "comingSoon": false },
    { "id": "inbound", "name": "Inbound Email", "isActive": true, "comingSoon": false },
    { "id": "system", "name": "System Events", "isActive": true, "comingSoon": false },
    { "id": "validation", "name": "Email Validation", "isActive": false, "comingSoon": true }
  ],
  "categories": [
    {
      "id": "message",
      "name": "Message Events",
      "events": [
        { "id": "message.sent", "name": "Message Sent", "products": ["transactional", "marketing"] },
        { "id": "message.delivered", "name": "Message Delivered", "products": ["transactional", "marketing"] }
      ]
    }
  ]
}

نقطة النهاية هذه عامة (لا تتطلب مصادقة) وتُرجع دائمًا أحدث إصدار من الكتالوج.

هيكل البيانات الموحدنسخ رابط القسم

يتضمن كل تسليم webhook هيكلًا خارجيًا موحّدًا:

{
  "event": "message.delivered",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "occurred_at": "2026-02-17T12:34:56.120Z",
  "schema_version": 1,
  "data": {
    // Event-specific fields
  }
}

يحمل الحقل data في كل حدث رسالة أيضًا status_version وstatus وprevious_status وcomplaint_status وreason، راجع إصدارات الحالة.

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

يحمل كل حدث رسالة الحقول data.status_version وdata.status وdata.previous_status وdata.complaint_status وdata.reason. تزداد status_version بمقدار واحد في كل مرة ترسل فيها MailLand حدثًا لتغيير في حالة الرسالة أو سببها أو حالة الشكوى الخاصة بها.

استثناءان:

• تبدأ الرسالة بقيمة status_version تساوي 0 ما دامت queued أو sent. الانتقال من queued إلى sent لا يرسل أي حدث ولا يغيّر الإصدار.
• يمكن لعدة أحداث message.deferred أن تشترك في status_version واحدة: التأخير المتكرر لا يغيّر الحالة.

قد تصل الـ webhooks بغير ترتيبها وقد يُعاد إرسالها، لذا طبّقها حسب status_version، وليس أبدًا حسب ترتيب الوصول.

قد تتغير الحالة بعد أن كانت نهائية. تُبلغ MailLand بما تعرفه حين تعرفه. وإذا عرفت المزيد لاحقًا، ترسل الحالة الأحدث مع status_version أعلى:

• قد ترتد رسالة مُسلَّمة لاحقًا، عندما يرفضها خادم المستلم بعد قبولها (ارتداد خارج الجلسة)؛
• بعد عطل داخلي، أو بعد تعافي خادم البريد لدى MailLand، قد يُبلَّغ عن تسليم أو رفض متأخرًا. عندها قد تصبح رسالة failed إما bounced أو delivered، وقد تصبح رسالة bounced بحالة delivered، وقد تصبح رسالة unknown بأي حالة نهائية.

لا تنتقل الرسالة أبدًا من delivered إلى failed. تُحصي MailLand هذه التصحيحات.

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

تعيد MailLand محاولة الرسالة المؤجلة حتى مهلة إعادة المحاولة الخاصة بها: نحو 5 ساعات بعد أول تسليم لها إلى طابور التسليم في البريد المعاملاتي، ونحو 25 ساعة في البريد التسويقي. بعد المهلة لا تضع MailLand الرسالة في الطابور لأي محاولة تسليم جديدة. أما النسخة التي كانت تنتظر اتصالًا عند حلول المهلة فقد تُحاوَل بعدها. هذه مُهل لإعادة المحاولة، وليست وعودًا بموعد تلقيك الحدث النهائي. تتلقى كل حدث حين تصل النتيجة إلى MailLand؛ وهذا التأخير لم يُقَس بعد، وقد يطول أثناء انقطاع داخلي. الرسالة التي لم تتمكن MailLand من تسليمها إلى طابور التسليم خلال 24 ساعة تُنهى بحالة expired.

إذا كنت تحتفظ بالحالة الحالية للرسالة من الـ webhooks (إجراء مطلوب)نسخ رابط القسم

هذا تغيير في السلوك بالنسبة إلى عمليات التكامل الحالية. فعملية التكامل التي تعدّ message.failed أو message.delivered نهائيًا وتتجاهل الأحداث اللاحقة قد تبقى على حالة خاطئة بعد تصحيح. أسماء الأحداث الموجودة أصلًا صار لها الآن تسلسلات ممكنة جديدة.

• اشترك في كل أحداث الرسائل: message.delivered وmessage.deferred وmessage.bounced وmessage.failed وmessage.complained وmessage.outcome_unknown وmessage.retried. عندئذ فقط تتضمن الأحداث التي تتلقاها كل تغيير في الحالة.
• خزّن status_version مع الحالة. لا تطبّق حدثًا إلا إذا كانت status_version الخاصة به أعلى من المخزنة؛ وmessage.deferred بإصدار مساوٍ لا يغيّر شيئًا.
• واصل معالجة الأحداث بعد message.failed أو message.bounced أو message.delivered: الحدث اللاحق ذو status_version الأعلى يحل محل الحالة السابقة.
• بمجرد أن تتلقى كل الأحداث حتى status_version التي تعرضها الواجهة البرمجية، تتساوى حالتك مع حالتها. قد تسبق الواجهة البرمجية الـ webhooks التي تلقيتها حتى الآن، وعند status_version تساوي 0 قد تعرض sent دون أي حدث.

إذا كنت مشتركًا في بعض أحداث الرسائل فقط، فإن أعلى status_version تلقيتها ليست بالضرورة الحالة الحالية: ربما غيّرها نوع حدث لست مشتركًا فيه. اقرأ الحالة الحالية من الواجهة البرمجية، مثلًا لكل رسالة يكون آخر حدث تلقيته لها message.failed أو message.bounced أو message.outcome_unknown، ثم وفّق بينهما.

إذا لم تستطع تغيير عملية التكامل، فاستعلم من الواجهة البرمجية عن حالة الرسائل التي تهمك. أما عمليات التكامل التي تكتفي بعدّ الأحداث أو بعرض السجل فلا تحتاج إلى أي تغيير.

أحداث الرسائلنسخ رابط القسم

message.sentنسخ رابط القسم

توضيحي: لم يُصدَر بعد. هذا الحدث مُدرج في الكتالوج لكن لا يوجد له مُصدِر اليوم.

{
  "event": "message.sent",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:56.789Z"
  }
}

message.deliveredنسخ رابط القسم

يُطلق عند تسليم البريد الإلكتروني بنجاح إلى خادم بريد المستلم.

قد يصل هذا الحدث أيضًا كتصحيح بعد حالة نهائية سابقة للرسالة نفسها. راجع إصدارات الحالة.

{
  "event": "message.delivered",
  "event_id": "evt_b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "timestamp": "2026-02-17T12:34:58.123Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:58.123Z",
    "smtp_response": "OK",
    "status_version": 1,
    "status": "delivered",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": null
  }
}

message.deferredنسخ رابط القسم

يُطلق عندما يتأخر التسليم مؤقتًا. سيعيد MailLand المحاولة تلقائيًا.

قد تؤجَّل الرسالة عدة مرات. يزيد أول تأجيل قيمة status_version؛ وتحمل التأجيلات المتكررة قيمة status_version نفسها.

{
  "event": "message.deferred",
  "event_id": "evt_c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
  "timestamp": "2026-02-17T12:35:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:00.000Z",
    "smtp_response": "Try again later",
    "bounce_reason": "TransientFailure"
  }
}

message.bouncedنسخ رابط القسم

يُطلق عند ارتداد بريد إلكتروني (ارتداد دائم أو مؤقت).

قد يصل هذا الحدث أيضًا كتصحيح بعد حالة نهائية سابقة للرسالة نفسها. راجع إصدارات الحالة.

{
  "event": "message.bounced",
  "event_id": "evt_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
  "timestamp": "2026-02-17T12:35:01.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:01.000Z",
    "bounce_type": "hard",
    "bounce_reason": "InvalidRecipient",
    "smtp_response": "The email account that you tried to reach does not exist.",
    "status_version": 1,
    "status": "bounced",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": "InvalidRecipient"
  }
}

bounce_reason هو رمز التصنيف الذي تُسنده MailLand للارتداد (مثل InvalidRecipient أو QuotaIssues أو SpamBlock)، وليس نص SMTP الخام، استخدم smtp_response لذلك. bounce_type يكون واحدًا من hard أو soft أو blocked أو unknown.

smtp_response هو نص رد خادم المستلم، دون رمز الرد الرقمي ورمز الحالة المُوسَّع. يبيّن bounce_type ما فعلته MailLand بالعنوان: hard، حُظر لكل البريد؛ soft، حُظر للبريد التسويقي لمدة 30 يومًا؛ blocked، كان الرفض متعلقًا بالإرسال لا بالعنوان (مثل تصفية البريد المزعج أو مصادقة المرسل أو السمعة أو سياسة المستلم)، لذا لا يُحظر شيء؛ unknown، لا يوجد تصنيف، ويُعامل مثل soft.

message.failedنسخ رابط القسم

يُطلق عندما تُنهي MailLand رسالة بناءً على دليل قاطع على أنها لم تُسلَّم، لسبب من جانب MailLand لا من جانب المستلم. في الحالات الموصوفة في إصدارات الحالة قد يتبعه message.delivered أو message.bounced مع status_version أعلى. تصبح حالة الرسالة Failed وليس Bounced، ويُحدد reason الحالة:

• لا يُحظر المستلم، ولا يُحتسب هذا الفشل ضمن معدل الارتداد لديك.
• تُنتج الرسالة الواحدة حدث message.failed واحدًا على الأكثر. وهو آخر حدث لتلك الرسالة ما لم تتلقَّ MailLand لاحقًا تسليمًا أو رفضًا؛ عندها يتبعه message.delivered أو message.bounced مع status_version أعلى.

يُبلَّغ عن رفض خادم البريد المستلم كحدث message.bounced، وليس أبدًا كحدث message.failed.

{
  "event": "message.failed",
  "event_id": "evt_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "timestamp": "2026-09-28T02:00:19.1047332Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-09-28T02:00:18.2522997Z",
    "reason": "dkim_revoked",
    "smtp_response": "Next delivery time PT3.028008S > PT1S",
    "status_version": 1,
    "status": "failed",
    "previous_status": "sent",
    "complaint_status": "none"
  }
}

message.outcome_unknownنسخ رابط القسم

يُطلق عندما لا تستطيع MailLand تحديد ما إذا كانت الرسالة قد وصلت إلى طابور التسليم لديها، مثلًا لأن تسليمها إلى القائمة انقطع ولم يمكن التحقق منه بعد ذلك. يُرسل بعد مدة من مهلة إعادة المحاولة الخاصة بالرسالة، حاليًا 7 أيام، إذا لم يصل أي دليل حتى ذلك الحين. هذه ليست حالة نهائية. تصبح الحالة unknown. إذا عرفت MailLand النتيجة لاحقًا، تتلقى message.delivered أو message.bounced أو message.failed مع status_version أعلى.

{
  "event": "message.outcome_unknown",
  "event_id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "timestamp": "2026-10-08T17:05:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-08T17:05:00.000Z",
    "status_version": 1,
    "status": "unknown",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": "handoff_undetermined"
  }
}

message.retriedنسخ رابط القسم

يُطلق عندما تعيد محاولة رسالة مرتدّة أو فاشلة فتضعها MailLand في الطابور من جديد. تصبح الحالة queued وتزداد status_version؛ وتتبعها أحداث النسخة المعاد إرسالها بإصدارات أعلى. هذه ليست حالة نهائية.

{
  "event": "message.retried",
  "event_id": "evt_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "timestamp": "2026-10-01T18:00:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-01T18:00:00.000Z",
    "attempt": 1,
    "status_version": 2,
    "status": "queued",
    "previous_status": "bounced",
    "complaint_status": "none",
    "reason": null
  }
}

أحداث التفاعلنسخ رابط القسم

message.openedنسخ رابط القسم

توضيحي: غير متاح.

{
  "event": "message.opened",
  "event_id": "evt_f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "timestamp": "2026-02-17T13:15:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:15:00.000Z"
  }
}

message.clickedنسخ رابط القسم

توضيحي: غير متاح.

{
  "event": "message.clicked",
  "event_id": "evt_g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
  "timestamp": "2026-02-17T13:16:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:16:00.000Z"
  }
}

message.unsubscribedنسخ رابط القسم

يُرسَل عندما يلغي مستلم اشتراكه من رسالة أرسلتها: عبر ترويسة List-Unsubscribe أو عنوان mailto: الخاص بها، أو طلب POST بنقرة واحدة، أو رابط إلغاء الاشتراك، أو صفحة التفضيلات. لا يُرسَل عند إلغاء الاشتراك الذي تجريه أنت بنفسك عبر الواجهة البرمجية أو لوحة التحكم، ولا عند شكاوى البريد المزعج (message.complained). يُرسَل مرة واحدة لكل رسالة، في اللحظة نفسها التي يُسجَّل فيها إلغاء اشتراك المستلم، إلى كل نقطة نهاية مشتركة فيه. وككل أحداث الرسائل، يحمل data أيضًا حقول حالة الرسالة الحالية (راجع إصدارات الحالة).

{
  "event": "message.unsubscribed",
  "event_id": "evt_h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
  "timestamp": "2026-02-17T14:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T14:00:00.000Z",
    "status_version": 3,
    "status": "delivered",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": null
  }
}

أحداث الإيقافنسخ رابط القسم

message.complainedنسخ رابط القسم

يُطلق عندما يُبلّغ المستلم عن البريد الإلكتروني كرسالة مزعجة (حلقة تغذية راجعة من مزوّد الخدمة).

{
  "event": "message.complained",
  "event_id": "evt_i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
  "timestamp": "2026-02-17T15:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T15:00:00.000Z",
    "feedback_type": "abuse"
  }
}

suppression.addedنسخ رابط القسم

توضيحي: لم يُصدَر بعد. هذا الحدث مُدرج في الكتالوج لكن لا يوجد له مُصدِر اليوم.

{
  "event": "suppression.added",
  "event_id": "evt_j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "timestamp": "2026-02-17T15:00:01.000Z",
  "data": {
    "email": "[email protected]",
    "type": "complaint",
    "scope": "global",
    "reason": "Spam complaint via ISP feedback loop"
  }
}

suppression.removedنسخ رابط القسم

توضيحي: لم يُصدَر بعد. هذا الحدث مُدرج في الكتالوج لكن لا يوجد له مُصدِر اليوم.

{
  "event": "suppression.removed",
  "event_id": "evt_k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5",
  "timestamp": "2026-02-17T16:00:00.000Z",
  "data": {
    "email": "[email protected]",
    "type": "manual",
    "scope": "global"
  }
}

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

inbound.receivedنسخ رابط القسم

يُطلق عند استلام بريد إلكتروني وارد على أحد نطاقاتك.

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "timestamp": "2026-02-17T12:00:00.000Z",
  "occurred_at": "2026-02-17T12:00:00.000Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "r7n2k5x9m1p4w6_s5m3x8k1p7n4w2",
    "email": {
      "id": "r7n2k5x9m1p4w6",
      "received_at": "2026-02-17T12:00:00.000Z",
      "size_bytes": 4521,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Doe" },
        "to": [{ "address": "[email protected]" }],
        "subject": "Help with my order",
        "message_id": "<[email protected]>",
        "date": "2026-02-17T11:59:50.000Z"
      },
      "body": {
        "text_preview": "Hi, I need help with...",
        "has_text": true,
        "has_html": true
      },
      "attachments": [],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 0.1,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.10",
        "hostname": "mail.external.com"
      }
    },
    "matched_route": {
      "id": "s5m3x8k1p7n4w2",
      "name": "Support inbox"
    }
  }
}

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

account.webhook_pausedنسخ رابط القسم

يُطلق عند إيقاف webhook تلقائيًا بسبب إخفاقات متتالية.

{
  "event": "account.webhook_paused",
  "event_id": "evt_m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7",
  "timestamp": "2026-02-17T18:00:00.000Z",
  "data": {
    "webhook_id": "z8m3p1k6x4w2n7",
    "webhook_name": "Production Events",
    "consecutive_failures": 10,
    "last_error": "Connection refused"
  }
}

account.domain_verifiedنسخ رابط القسم

توضيحي: لم يُصدَر بعد. هذا الحدث مُدرج في الكتالوج لكن لا يوجد له مُصدِر اليوم.

{
  "event": "account.domain_verified",
  "event_id": "evt_n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com"
  }
}

account.domain_failedنسخ رابط القسم

توضيحي: لم يُصدَر بعد. هذا الحدث مُدرج في الكتالوج لكن لا يوجد له مُصدِر اليوم.

{
  "event": "account.domain_failed",
  "event_id": "evt_o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com",
    "reason": "DKIM record not found for selector mlnd"
  }
}

account.quota_warningنسخ رابط القسم

توضيحي: لم يُصدَر بعد. هذا الحدث مُدرج في الكتالوج لكن لا يوجد له مُصدِر اليوم.

{
  "event": "account.quota_warning",
  "event_id": "evt_p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
  "timestamp": "2026-02-17T20:00:00.000Z",
  "data": {
    "used": 45000,
    "limit": 50000,
    "percentage": 90
  }
}

account.quota_exceededنسخ رابط القسم

توضيحي: لم يُصدَر بعد. هذا الحدث مُدرج في الكتالوج لكن لا يوجد له مُصدِر اليوم.

{
  "event": "account.quota_exceeded",
  "event_id": "evt_q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1",
  "timestamp": "2026-02-17T22:00:00.000Z",
  "data": {
    "used": 50000,
    "limit": 50000,
    "percentage": 100
  }
}

ملخص الأحداثنسخ رابط القسم

"متاح" هو علامة availableNow في الكتالوج: هل يُصدِر شيء ما هذا الحدث فعليًا اليوم. يمكن فقط للأحداث المتاحة أن تُدرج في اشتراك.

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

عندما تكون includeFutureEvents بقيمة true (الافتراضي)، يستلم الـwebhook الخاص بك تلقائيًا أنواع الأحداث الجديدة أثناء إضافتها إلى منتجاتك المشترك بها. اضبطها على false لتثبيت اشتراكك على لقطة الأحداث الحالية.

الأحداث المُعلَّمة بـ"ليس بعد" أعلاه تصبح قابلة للاشتراك عند إطلاق مُصدِراتها: أسماء الأحداث وهياكل البيانات الموثقة هنا لن تتغير عند ذلك.

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

• التحقق من التوقيع: تحقق من أن الأحداث صادرة من MailLand
• منطق إعادة المحاولة: افهم سلوك إعادة المحاولة
• نظرة عامة على الـWebhooks: أنشئ الـwebhooks وأدرها