ایمیل‌های زمان‌بندی شده

زمان‌بندی ایمیل‌ها برای ارسال آینده با پشتیبانی از منطقه زمانی

زمان‌بندی یک ایمیل

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 باید در آینده باشد و حداکثر تا ۷ روز جلوتر تنظیم شود. تنظیم timeZone مقدار scheduledAt را به آن منطقه تبدیل نمی‌کند: این مقدار زمانی همیشه به‌صورت UTC خوانده می‌شود. زمانی در گذشته با خطای 400 VALIDATION_FAILED رد می‌شود؛ بیش از ۷ روز جلوتر با خطای 400 INVALID_REQUEST رد می‌شود ("Cannot schedule email more than 7 days in advance"). همین بازهٔ ۷روزه، چه زمان‌بندی از همین‌جا ساخته شود، چه از طریق endpoint ارسال، و چه با تغییر زمان‌بندی، اعمال می‌شود.

تفاوت نام فیلدها با endpoint ارسال را توجه کنید: ایمیل‌های زمان‌بندی شده از 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	موارد در هر صفحه (حداکثر ۱۰۰)
`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
}

همان محدودیت‌های زمان‌بندی اعمال می‌شود: زمان جدید باید در آینده باشد و حداکثر تا ۷ روز از اکنون جلوتر باشد، وگرنه درخواست با خطای 400 INVALID_REQUEST رد می‌شود.

مدیریت منطقهٔ زمانی

scheduledAt همیشه به‌صورت UTC تفسیر می‌شود، چه timeZone ارائه دهید چه ندهید: آن را با Z یا افست صریح ارسال کنید. timeZone فقط برای نمایش در پاسخ‌ها ذخیره و بازگردانده می‌شود؛ MailLand مقدار scheduledAt را به آن منطقه تبدیل نمی‌کند. اگر می‌خواهید برای نمایش ثبت شود، از شناسه‌های منطقهٔ زمانی IANA استفاده کنید:

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

زمان‌بندی از طریق endpoint ارسال

می‌توانید ایمیل‌ها را مستقیماً از طریق endpoint ارسال معمولی با افزودن فیلد 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 از endpoint ارسال شامل scheduleId و scheduledAt است. این زمان‌بندی همان نوع رکوردی است که endpointهای این صفحه روی آن کار می‌کنند: دقیقاً مانند زمان‌بندیِ ساخته‌شده مستقیم از طریق /v1/transactional/scheduled، می‌توان آن را با endpointهای بالا فهرست کرد، دریافت کرد، لغو کرد و زمان‌بندی‌اش را تغییر داد. بازهٔ ۷روزه (به هشدار بالا نگاه کنید) اینجا هم اعمال می‌شود: scheduledAtی که بیش از ۷ روز جلوتر باشد با خطای 400 INVALID_REQUEST رد می‌شود.

مراحل بعدی

REST API: ارسال فوری ایمیل
قالب‌ها: استفاده از قالب‌ها از طریق /v1/transactional/send همراه با scheduledAt
ارسال دسته‌ای: زمان‌بندی ارسال‌های دسته‌ای

ایمیل‌های زمان‌بندی شده

زمان‌بندی یک ایمیلکپی پیوند بخش

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

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

وضعیت‌های ایمیل زمان‌بندی شدهکپی پیوند بخش

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

دریافت یک ایمیل زمان‌بندی شدهکپی پیوند بخش

لغو یک ایمیل زمان‌بندی شدهکپی پیوند بخش

تغییر زمان‌بندی ایمیلکپی پیوند بخش

مدیریت منطقهٔ زمانیکپی پیوند بخش

زمان‌بندی از طریق endpoint ارسالکپی پیوند بخش

مراحل بعدیکپی پیوند بخش

در این صفحه