سجلات البريد الإلكتروني

البحث والتصفية وفحص سجلات التسليم التفصيلية لكل بريد إلكتروني أُرسل عبر Mail.Land

تسرد هذه الصفحة الرسائل التبادلية (transactional) فقط: يُستبعد بريد الحملات والأتمتة (بما فيه رسائل النظام sys_*). استخدم نقطة نهاية مستلمي الحملات (انظر الحملات) لسجل إرسال التسويق/الأتمتة.

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

GET https://api.mail.land/v1/transactional/logs

List emails

curl "https://api.mail.land/v1/transactional/logs?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

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

المعامل	النوع	الافتراضي	الوصف
`cursor`	string	-	مؤشر معتم من `nextCursor` للصفحة السابقة. احذفه للصفحة الأولى. المؤشر غير الصحيح أو المُتلاعَب به يُرجع `400 INVALID_CURSOR`.
`limit`	int	20	عدد العناصر في الصفحة
`status`	string	-	التصفية حسب الحالة (انظر أدناه)
`search`	string	-	البحث بالمستلم أو الموضوع أو معرّف الرسالة
`from`	datetime	منذ 30 يومًا	تاريخ البداية
`to`	datetime	الآن	تاريخ النهاية
`refresh`	bool	false	تجنّب صفحة قديمة: لم يعد هناك ذاكرة تخزين مؤقت للعدد لتجاوزها

فلاتر الحالة

القيمة	التطابق
`queued`	في انتظار التنفيذ في قائمة الانتظار
`sent`	مقبول من قِبل MTA
`deferred` أو `retrying`	متأخر مؤقتًا
`delivered`	تم التسليم بنجاح
`bounced`	ارتداد دائم
`failed`	خطأ في النظام أو ارتداد إداري
`opened`	فتح المستلم البريد الإلكتروني
`clicked`	نقر المستلم على رابط
`complained`	قدّم المستلم شكوى بريد مزعج

Email logs response

{
  "items": [
    {
      "messageId": "t_a1b2c3d4e5f6",
      "recipient": "[email protected]",
      "subject": "Your order has shipped",
      "status": "delivered",
      "sentAt": "2026-02-17T12:34:56Z",
      "deliveredAt": "2026-02-17T12:34:58Z",
      "openedAt": "2026-02-17T13:15:00Z",
      "clickedAt": null,
      "bounceReason": null,
      "openCount": 2,
      "clickCount": 0
    },
    {
      "messageId": "t_d4e5f6a1b2c3",
      "recipient": "[email protected]",
      "subject": "Invoice #1234",
      "status": "bounced",
      "sentAt": "2026-02-17T12:30:00Z",
      "deliveredAt": null,
      "openedAt": null,
      "clickedAt": null,
      "bounceReason": "550 5.1.1 Mailbox not found",
      "openCount": 0,
      "clickCount": 0
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

أولوية الحالة

يعكس حقل status الحدث الأعلى أولوية لكل بريد إلكتروني:

complained (الأعلى)
clicked
opened
حالة التسليم: queued → sent → deferred → delivered → bounced → failed

على سبيل المثال، إذا تم تسليم بريد إلكتروني ثم فُتح، تعرض الحالة opened.

يُطبَّق نطاق زمني افتراضي مدته 30 يومًا لأغراض الأداء. يُصفّي معامل البحث حسب بريد المستلم الإلكتروني أو سطر الموضوع أو معرّف الرسالة (غير حساس لحالة الأحرف).

إحصائيات السجل

احصل على إحصائيات مجمّعة لسجلات بريدك الإلكتروني:

GET https://api.mail.land/v1/transactional/logs/stats

Get log stats

curl "https://api.mail.land/v1/transactional/logs/stats" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

المعامل	النوع	الافتراضي	الوصف
`from`	datetime	منذ 7 أيام	تاريخ البداية
`to`	datetime	الآن	تاريخ النهاية
`emailType`	int	-	`0` = معاملاتي، `1` = تسويقي. حذفه يشمل جميع أنواع البريد الإلكتروني: على عكس "سرد رسائل البريد" أعلاه، التي تقتصر على المعاملاتي فقط.
`refresh`	bool	false	تجاوز ذاكرة التخزين المؤقت

Log stats response

{
  "total": 4750,
  "accepted": 4750,
  "sent": 4700,
  "delivered": 4680,
  "opened": 1498,
  "clicked": 195,
  "bounced": 38,
  "complained": 1,
  "failed": 12,
  "queued": 20,
  "deliveryRate": 99.57,
  "openRate": 32.01,
  "clickRate": 13.02,
  "bounceRate": 0.81,
  "complaintRate": 0.021,
  "source": "clickhouse",
  "queryTimeMs": 32
}

حسابات المعدلات:

المعدل	الصيغة
`deliveryRate`	`delivered / sent * 100`
`openRate`	`opened / delivered * 100`
`clickRate`	`clicked / delivered * 100`
`bounceRate`	`bounced / sent * 100`
`complaintRate`	`complained / sent * 100` (3 منازل عشرية)

تشير ترويسات الاستجابة إلى حالة التخزين المؤقت:

الترويسة	القيم
`X-Cache`	`HIT` أو `MISS` أو `FRESH`
`X-Stats-Source`	`cache` أو `clickhouse`
`Cache-Control`	دائمًا `no-store, no-cache, must-revalidate`

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

احصل على التفاصيل الكاملة لبريد إلكتروني محدد، بما في ذلك الجدول الزمني للأحداث:

GET https://api.mail.land/v1/transactional/logs/{messageId}

Get email detail

curl https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Email detail response

{
  "messageId": "t_a1b2c3d4e5f6",
  "recipient": "[email protected]",
  "fromEmail": "[email protected]",
  "subject": "Your order has shipped",
  "status": "opened",
  "sentAt": "2026-02-17T12:34:56Z",
  "deliveredAt": "2026-02-17T12:34:58Z",
  "openedAt": "2026-02-17T13:15:00Z",
  "clickedAt": null,
  "createdAt": "2026-02-17T12:34:55Z",
  "bounceReason": null,
  "bounceCategory": null,
  "ipAddress": null,
  "retryCount": 0,
  "smtpResponse": "250 2.0.0 OK",
  "openCount": 2,
  "clickCount": 0,
  "htmlContent": "<html>...</html>",
  "textContent": "Your order has shipped...",
  "events": [
    {
      "eventType": "delivered",
      "timestamp": "2026-02-17T12:34:58Z",
      "ipAddress": null,
      "userAgent": null,
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": "250 2.0.0 OK",
      "deviceType": null,
      "browser": null,
      "country": null,
      "city": null
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T13:15:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "desktop",
      "browser": "Chrome",
      "country": "US",
      "city": "San Francisco"
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T14:30:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "mobile",
      "browser": "Safari",
      "country": "US",
      "city": "San Francisco"
    }
  ]
}

مصدر مصفوفة events هو ClickHouse ومرتبة حسب الطابع الزمني. إذا كان ClickHouse غير متاح مؤقتًا، تُعاد تفاصيل البريد الإلكتروني من PostgreSQL لكن events ستكون مصفوفة فارغة.

حقول الحدث

الحقل	الوصف
`eventType`	`delivered` أو `opened` أو `clicked` أو `bounced` أو `complained`، وأيضًا `accepted` أو `sent` أو `deferred` أو `admin_bounce` أو `oob_bounce` أو `expired`
`timestamp`	وقت وقوع الحدث (UTC)
`ipAddress`	عنوان IP للعميل (للفتح/النقر)
`userAgent`	سلسلة وكيل المستخدم للعميل
`linkUrl`	URL المنقور عليه (لأحداث `clicked`)
`bounceType`	`hard` أو `soft` أو `unknown` (لأحداث `bounced`)
`bounceReason`	استجابة SMTP (لأحداث `bounced`)
`smtpResponse`	استجابة الخادم البعيد (لأحداث `delivered`)
`deviceType`	`desktop` أو `mobile` أو `tablet`
`browser`	اسم المتصفح (Chrome وSafari وFirefox وغيرها)
`country`	رمز الدولة ISO
`city`	اسم المدينة

إعادة إرسال بريد إلكتروني فاشل

أعد محاولة تسليم بريد إلكتروني مرتد أو فاشل:

POST https://api.mail.land/v1/transactional/logs/{messageId}/retry

Retry failed email

curl -X POST https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يجب أن تكون الرسالة في حالة Bounced أو Failed، ويجب ألا يكون المستلم مُثبَّطًا.

الحالة	الرمز	الوصف
`200`	-	تم قبول إعادة المحاولة
`400`	`INVALID_REQUEST`	البريد الإلكتروني ليس مرتدًا أو فاشلًا
`400`	`RECIPIENT_SUPPRESSED`	المستلم موجود في قائمة القمع
`404`	`RESOURCE_NOT_FOUND`	الرسالة غير موجودة: وليس `EMAIL_NOT_FOUND`
`422`	`DOMAIN_NOT_VERIFIED`	نطاق الإرسال لم يعد موثَّقًا
`429`	`MARKETING_PAUSED`	إرسال التسويق متوقف مؤقتًا حاليًا لهذه المساحة
`422`	`RETRY_ATTACHMENTS_UNAVAILABLE`	كانت للرسالة مرفقات لم يعد استرجاعها ممكنًا؛ أرسلها من جديد مع مرفقاتها
`422`	`RETRY_ATTACHMENTS_UNKNOWN`	أُرسلت الرسالة قبل تسجيل المرفقات، لذا لا تستطيع إعادة المحاولة ضمان مرفقاتها؛ أرسلها من جديد
`429`	`PLATFORM_CAPACITY_PROTECTION`	الإرسال الجديد متوقف لفترة وجيزة لحماية سعة المنصة؛ لم يتغير شيء، أعد المحاولة بعد قليل
`503`	`RETRY_ATTACHMENT_STORAGE_UNAVAILABLE`	تعذّرت قراءة المرفقات الآن؛ لم يتغير شيء، أعد المحاولة بعد قليل

تُنشئ إعادة المحاولة مهمة بريد إلكتروني جديدة بالمحتوى الأصلي وتضعها في قائمة الانتظار للتسليم. تُرسَل النسخ المعاد محاولتها دون تتبع الفتح/النقر.

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

نظرة عامة على التحليلات: ملخصات الأحداث المجمّعة والمعدلات
التحليلات المتقدمة: تفاصيل جغرافية وحسب الجهاز ووقت اليوم
الارتدادات: فهم معالجة الارتداد وإعادة المحاولة

سجلات البريد الإلكتروني

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

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

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

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

إحصائيات السجلنسخ رابط القسم

تفاصيل البريد الإلكترونينسخ رابط القسم

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

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

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

في هذه الصفحة