ارسال دسته‌ای

ارسال ایمیل به چندین گیرنده در یک فراخوانی 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	خیر	زمان‌بندی برای ارسال آینده، حداکثر تا ۷ روز بعد
`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`	تعداد گیرندگان بیش از حداکثر هر دسته (۱۰٬۰۰۰)
`400`	`INVALID_REQUEST`	`scheduledAt` بیش از ۷ روز جلوتر («امکان زمان‌بندی ایمیل بیش از ۷ روز جلوتر وجود ندارد»)
`400`	`TEMPLATE_NOT_FOUND`	`templateId` به هیچ قالب فعالی از این حساب اشاره ندارد (برای قالب حذف‌شده نیز برگردانده می‌شود)
`400`	`IP_POOL_NOT_FOUND`	`ipPoolId` به هیچ استخری که به این حساب اختصاص یافته باشد اشاره ندارد
`422`	`TEMPLATE_VARIABLE_MISSING`	برای هر گیرنده مقدار یک `{{placeholder}}` وجود ندارد (اگر فقط برای بعضی نباشد، آن‌ها رد می‌شوند و با دلیل `template_variable_missing: name` در `rejectedRecipients` می‌آیند). چیزی در صف قرار نمی‌گیرد
`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: مرجع ارسال ایمیل تکی
قالب‌ها: ایجاد قالب برای ایمیل‌های دسته‌ای
ایمیل‌های زمان‌بندی شده: زمان‌بندی ارسال دسته‌ای

ارسال دسته‌ای

ارسال یک دستهکپی پیوند بخش

فیلدهای درخواستکپی پیوند بخش

پاسخکپی پیوند بخش

ادغام متغیرهاکپی پیوند بخش

مدیریت خطاکپی پیوند بخش