الإرسال الجماعي

إرسال رسائل البريد الإلكتروني لمستلمين متعددين في طلب API واحد

الإرسال الجماعي متاح فقط مع بيانات اعتماد تدفق التسويق. تُعيد بيانات اعتماد المعاملات 400 BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL. يمنع هذا إساءة استخدام تدفقات المعاملات للبريد الإلكتروني الجماعي.

إرسال دفعة

POST https://api.mail.land/v1/transactional/send-batch

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

curl -X POST https://api.mail.land/v1/transactional/send-batch \
  -H "X-API-Key: ml_pem_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Your Company"
    },
    "recipients": [
      {
        "email": "[email protected]",
        "name": "Alice",
        "variables": { "firstName": "Alice", "plan": "Pro" }
      },
      {
        "email": "[email protected]",
        "name": "Bob",
        "variables": { "firstName": "Bob", "plan": "Starter" }
      }
    ],
    "subject": "Hi {{firstName}}, check out what'\''s new",
    "htmlContent": "<h1>Hey {{firstName}}!</h1><p>Your {{plan}} plan just got an upgrade.</p>",
    "variables": {
      "companyName": "Acme Inc",
      "year": "2026"
    },
    "tags": ["product-update", "february-2026"],
    "batchName": "February Product Update"
  }'

حقول الطلب

الحقل	النوع	مطلوب	الوصف
`from`	object	نعم	عنوان المُرسِل (`email` واسم `name` اختياري)
`recipients`	array	نعم	قائمة المستلمين (ملاحظة: `recipients`، وليس `to`)
`recipients[].email`	string	نعم	بريد المستلم الإلكتروني
`recipients[].name`	string	لا	اسم عرض المستلم
`recipients[].variables`	object	لا	متغيرات القالب لكل مستلم
`subject`	string	مشروط	مطلوب ما لم يتم استخدام `templateId`
`templateId`	string	لا	استخدام قالب مُخزّن
`htmlContent`	string	مشروط	محتوى HTML (مطلوب إذا لم يُحدَّد `templateId`)
`textContent`	string	لا	نص بديل بتنسيق عادي
`variables`	object	لا	متغيرات عامة. تُطبَّق سواء استُخدم `templateId` أم لا؛ وعند تكرار المفتاح، تفوز قيمة `recipients[].variables` الخاصة بالمستلم
`replyTo`	string	لا	عنوان الرد
`batchName`	string	لا	اسم مقروء لهذه الدفعة
`tags`	array	لا	وسوم للتحليلات وتصفية webhook
`customHeaders`	object	لا	ترويسات بريد إلكتروني مخصصة
`tracking`	object	لا	تجاوزات تتبع الفتح/النقر
`ipPoolId`	string	لا	محجوز لمجمّعات IP المخصّصة. غير متاح بعد: إرساله يُرجع `400 IP_POOL_NOT_FOUND`. يُحذف.
`scheduledAt`	datetime	لا	جدولة التسليم المستقبلي، بحد أقصى 7 أيام مقدَّماً
`externalBatchId`	string	لا	معرّف الدفعة في نظامك: عند إرساله، تتم إعادته كما هو باعتباره `batchId` في الاستجابة
`priority`	enum	لا	`Low`، `Normal` (الافتراضي)، `High`، `Critical`
`idempotencyKey`	string	لا	لمنع الإرسال المكرر لنفس المفتاح. يُفضَّل استخدام رأس `X-Idempotency-Key`

لاحظ الفرق في اسم الحقل: يستخدم الإرسال الجماعي recipients بينما يستخدم الإرسال الفردي to.

الاستجابة

الحالة: 202 Accepted

استجابة الدفعة

{
  "success": true,
  "batchId": "batch_f47ac10b58cc43729876fedcba098765",
  "messageIds": ["m_a1b2c3...", "m_d4e5f6..."],
  "totalRecipients": 2,
  "acceptedCount": 2,
  "rejectedCount": 0,
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "estimatedCompletion": "2026-02-17T10:35:00Z",
  "isSandboxed": false
}

الحقل	النوع	الوصف
`batchId`	string	معرّف فريد للدفعة
`messageIds`	array	معرّفات الرسائل لكل مستلم (بادئة `m_` للتسويق)
`totalRecipients`	int	إجمالي المستلمين في الطلب
`acceptedCount`	int	المستلمون المقبولون للتسليم
`rejectedCount`	int	المستلمون المرفوضون
`rejectedRecipients`	array	تفاصيل المستلمين المرفوضين مع الأسباب
`estimatedCompletion`	datetime	الوقت المقدّر لإتمام معالجة الدفعة

دمج المتغيرات

تتجاوز متغيرات كل مستلم المتغيرات العامة عند تداخل المفاتيح:

أولوية المتغيرات

{
  "variables": {
    "companyName": "Acme Inc",
    "greeting": "Hello"
  },
  "recipients": [
    {
      "email": "[email protected]",
      "variables": { "greeting": "Dear valued customer" }
    },
    {
      "email": "[email protected]"
    }
  ]
}

[email protected] يتلقى: greeting = "Dear valued customer"، companyName = "Acme Inc"
[email protected] يتلقى: greeting = "Hello"، companyName = "Acme Inc"

معالجة الأخطاء

أخطاء خاصة بالإرسال الجماعي:

الحالة	الرمز	الوصف
`400`	`BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL`	بيانات اعتماد المعاملات لا يمكنها إرسال دفعات
`400`	`VALIDATION_FAILED`	تجاوز الحد الأقصى للمستلمين لكل دفعة (10,000)
`400`	`INVALID_REQUEST`	`scheduledAt` أبعد من 7 أيام ("لا يمكن جدولة البريد لأكثر من 7 أيام مقدَّماً")
`400`	`TEMPLATE_NOT_FOUND`	لا يوجد لدى `templateId` قالب نشط في هذا الحساب (يُرجع أيضاً لقالب محذوف)
`400`	`IP_POOL_NOT_FOUND`	لا يوجد لدى `ipPoolId` مجمّع مخصَّص لهذا الحساب
`422`	`TEMPLATE_VARIABLE_MISSING`	ينقص كل مستلم قيمة `{{placeholder}}` (إذا نقصت بعضهم فقط يُتخطّون ويُدرجون في `rejectedRecipients` بالسبب `template_variable_missing: name`). لا يوضع شيء في الطابور
`400`	`BATCH_SEND_FAILED`	جميع المستلمين مقموعون
`429`	`RATE_LIMIT_EXCEEDED`	تم تجاوز حد المعدل (على مستوى مساحة العمل/الخطة، وليس لكل بيانات اعتماد)
`429`	`QUOTA_EXCEEDED`	استُنفدت الحصة الشهرية

رموز مستوى توثيق الحساب ومحرك السياسات الموثَّقة لـ POST /v1/transactional/send، مثل SENDING_BLOCKED وACTION_REQUIRED وDAILY_LIMIT_EXCEEDED وMARKETING_PAUSED وغيرها، تنطبق هنا أيضاً.

النجاح الجزئي ممكن: قد يتم قبول بعض المستلمين بينما يُرفض آخرون (مثال: العناوين المحظورة). تحقق من rejectedRecipients في الاستجابة.

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

واجهة REST API: مرجع إرسال البريد الإلكتروني الفردي
القوالب: إنشاء قوالب للبريد الإلكتروني الجماعي
البريد الإلكتروني المُجدول: جدولة الدفعات للإرسال لاحقاً

الإرسال الجماعي

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

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

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

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

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