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

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

جدولة بريد إلكتروني

POST https://api.mail.land/v1/transactional/scheduled

Schedule an email

curl -X POST https://api.mail.land/v1/transactional/scheduled \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Your App"
    },
    "to": {
      "email": "[email protected]",
      "name": "Jane Doe"
    },
    "subject": "Your trial expires tomorrow",
    "html": "<h1>Hi Jane,</h1><p>Your free trial expires tomorrow. Upgrade now to keep access.</p>",
    "text": "Hi Jane, Your free trial expires tomorrow. Upgrade now to keep access.",
    "scheduledAt": "2026-02-18T09:00:00Z",
    "timeZone": "America/New_York",
    "tags": ["trial-expiry", "reminder"]
  }'

حقول الطلب

الحقل	النوع	مطلوب	الوصف
`from`	object	نعم	عنوان المُرسِل (`email` و`name` اختياري)
`to`	object	نعم	مستلم واحد (`email` و`name` اختياري)
`subject`	string	نعم	سطر موضوع البريد الإلكتروني
`html`	string	مشروط	محتوى HTML (أحد `html` أو `text` مطلوب)
`text`	string	مشروط	محتوى نص عادي
`replyTo`	string	لا	عنوان الرد
`cc`	array	لا	مستلمو CC (`email` و`name` اختياري)
`bcc`	array	لا	مستلمو BCC (`email` و`name` اختياري)
`attachments`	array	لا	مرفقات الملفات (نفس تنسيق الإرسال المفرد)
`headers`	object	لا	رؤوس بريد إلكتروني مخصصة
`tags`	array	لا	علامات للتحليلات
`scheduledAt`	datetime	نعم	وقت الإرسال. يُفسَّر دائمًا بتوقيت UTC: أرسله مع `Z` أو إزاحة صريحة
`timeZone`	string	لا	منطقة زمنية IANA (مثلاً `America/New_York`). تُخزَّن وتُعاد للعرض فقط: لا تؤثر في وقت الإرسال الفعلي

يجب أن يكون scheduledAt في المستقبل وألا يتجاوز 7 أيام. ضبط timeZone لا يحوّل scheduledAt إلى تلك المنطقة: الطابع الزمني يُقرأ دائمًا كـ UTC. الوقت في الماضي يُرفض بخطأ 400 VALIDATION_FAILED؛ وما يتجاوز 7 أيام يُرفض بخطأ 400 INVALID_REQUEST ("Cannot schedule email more than 7 days in advance"). ونافذة الـ 7 أيام نفسها تنطبق سواء أُنشئت الجدولة هنا أو عبر نقطة نهاية الإرسال أو عبر إعادة الجدولة.

لاحظ الفرق في أسماء الحقول من نقطة نهاية الإرسال: تستخدم رسائل البريد الإلكتروني المجدولة html/text (وليس htmlContent/textContent) وتكون to كائنًا واحدًا (وليس مصفوفة).

الاستجابة

الحالة: 201 Created

Schedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

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

الحالة	الوصف
`pending`	في قائمة الانتظار للتسليم المستقبلي
`processing`	قيد المعالجة للإرسال
`sent`	تم الإرسال بنجاح
`failed`	فشل الإرسال (تحقق من حقل `error`)
`cancelled`	تم الإلغاء قبل الإرسال

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

GET https://api.mail.land/v1/transactional/scheduled?limit=20

List scheduled emails

curl https://api.mail.land/v1/transactional/scheduled?limit=20 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

التصفية حسب الحالة:

GET https://api.mail.land/v1/transactional/scheduled?status=pending

List scheduled emails by status

curl "https://api.mail.land/v1/transactional/scheduled?status=pending" \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

List response

{
  "items": [
    {
      "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "pending",
      "scheduledAt": "2026-02-18T09:00:00Z",
      "timeZone": "America/New_York",
      "to": "[email protected]",
      "recipientCount": 1,
      "subject": "Your trial expires tomorrow",
      "createdAt": "2026-02-17T10:00:00Z",
      "processedAt": null,
      "messageIds": [],
      "rejectedRecipients": [],
      "reasonCode": null,
      "error": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

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

المعامل	النوع	الافتراضي	الوصف
`cursor`	string	-	مؤشر معتم من `nextCursor` للصفحة السابقة. احذفه للصفحة الأولى.
`limit`	int	20	العناصر في الصفحة (بحد أقصى 100)
`status`	string	-	التصفية حسب الحالة: `pending` أو `processing` أو `sent` أو `failed` أو `cancelled`

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

GET https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Get a scheduled email

curl https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Detail response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "sent",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": "2026-02-18T09:00:02Z",
  "messageId": "t_a1b2c3d4e5f6...",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

بعد الإرسال، تتضمن الاستجابة processedAt (وقت الإرسال) وmessageId (لتتبع أحداث التسليم).

إلغاء بريد إلكتروني مجدول

DELETE https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Cancel a scheduled email

curl -X DELETE https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

يُرجع 204 No Content عند النجاح. يمكنك إلغاء رسائل البريد الإلكتروني ذات الحالة pending فقط. تُرجع محاولة إلغاء بريد إلكتروني بحالة processing أو sent أو failed خطأ 400 Bad Request.

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

تغيير وقت التسليم لبريد إلكتروني في الانتظار:

PATCH https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Reschedule an email

curl -X PATCH https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2026-02-19T14:00:00Z",
    "timeZone": "Europe/London"
  }'

Reschedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-19T14:00:00Z",
  "timeZone": "Europe/London",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

تنطبق نفس قيود الجدولة: يجب أن يكون الوقت الجديد في المستقبل وألا يتجاوز 7 أيام من الآن، وإلا رُفض الطلب بخطأ 400 INVALID_REQUEST.

معالجة المناطق الزمنية

يُفسَّر scheduledAt دائمًا كـ UTC، سواء قدَّمت timeZone أم لا: أرسله مع Z أو إزاحة صريحة. تُخزَّن timeZone وتُعاد في الاستجابات لأغراض العرض فقط؛ لا يحوّل MailLand قيمة scheduledAt إلى تلك المنطقة. استخدم معرّفات المناطق الزمنية IANA إن أردت تسجيلها للعرض:

America/New_York
Europe/London
Asia/Tokyo
Australia/Sydney

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

يمكنك أيضاً جدولة رسائل البريد الإلكتروني مباشرةً عبر نقطة نهاية الإرسال العادية بتضمين حقل scheduledAt:

Schedule via send endpoint

{
  "from": { "email": "[email protected]" },
  "to": [{ "email": "[email protected]" }],
  "subject": "Scheduled email",
  "htmlContent": "<p>This will be sent later.</p>",
  "scheduledAt": "2026-02-18T09:00:00Z"
}

تتضمن استجابة 202 من نقطة نهاية الإرسال scheduleId وscheduledAt. وهذه الجدولة هي نفس نوع الصف الذي تعمل عليه نقاط النهاية في هذه الصفحة: يمكن سردها والحصول عليها وإلغاؤها وإعادة جدولتها بنفس النقاط الموصوفة أعلاه، تمامًا كما لو أُنشئت مباشرةً عبر /v1/transactional/scheduled. ونافذة الـ 7 أيام (انظر التنبيه أعلاه) تنطبق هنا أيضًا: scheduledAt الذي يتجاوز 7 أيام يُرفض بخطأ 400 INVALID_REQUEST.

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

REST API: الإرسال الفوري للبريد الإلكتروني
القوالب: استخدام القوالب عبر /v1/transactional/send مع scheduledAt
الإرسال الجماعي: جدولة إرسال جماعي

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

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

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

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

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

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

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

إلغاء بريد إلكتروني مجدولنسخ رابط القسم

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

معالجة المناطق الزمنيةنسخ رابط القسم

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

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

في هذه الصفحة