ایران ناتیفیکیشن
ورودشروع رایگان
مستنداتv1 stable
کنسول APISDKهادریافت کلید API

ارسال ایمیل

ارسال ایمیل تراکنشی با متن/HTML، پیوست، قالب و زمان‌بندی.

POSThttps://api.irnoti.com/v1/email/send
scope: email.send

نامه از صف عبور می‌کند و پاسخ 202 فوراً برمی‌گردد؛ وضعیت نهایی (ارسال، تحویل، بازگشت) را با GET /email/outbound/{id} یا وب‌هوک‌های email.sent، email.delivered، email.bounced، email.complained و email.failed دریافت کنید. **فرستنده (from)** باید یکی از صندوق‌های شما یا نشانی‌ای از یکی از دامنه‌های **تأییدشدهٔ** شما باشد. **هزینه** به‌ترتیب از سهمیهٔ ماهانهٔ بسته، بستهٔ ارسال و در پایان کیف پول (در صورت فعال بودن پرداخت به‌ازای ارسال) کم می‌شود و اگر نامه هرگز ارسال نشود برمی‌گردد. گیرندگانی که در فهرست ممنوعه (بازگشتی، شکایت، لغو اشتراک) باشند حذف می‌شوند؛ اگر همه حذف شوند خطای 422 all_suppressed می‌گیرید. با فیلد template می‌توانید به‌جای subject/html/text نام قالب و مقدار متغیرها را بدهید ({{name}} در قالب). **فیلدهای پاسخ:** id، status (queued|sent|failed)، recipients، billedVia (plan|pack|wallet|mixed)، cost و duplicate (اگر همان Idempotency-Key قبلاً دیده شده باشد).

پارامترها

ناممحلنوعتوضیح
from *بدنهstringنشانی فرستنده (صندوق شما یا دامنهٔ تأییدشده).
fromNameبدنهstringنام نمایشی فرستنده.
to *بدنهstring | string[]گیرنده(ها)؛ حداکثر به تعداد مجاز بسته (پیش‌فرض ۵۰ در کل to/cc/bcc).
ccبدنهstring[]رونوشت.
bccبدنهstring[]رونوشت مخفی.
replyToبدنهstringنشانی پاسخ.
subjectبدنهstringموضوع (حداکثر ۵۰۰ نویسه).
textبدنهstringمتن ساده.
htmlبدنهstringمتن HTML؛ اگر text نباشد از روی آن ساخته می‌شود.
attachmentsبدنهobject[]پیوست‌ها: {filename, contentBase64, contentType?, cid?} (حداکثر ۲۰ پیوست؛ مجموع طبق سقف بسته). با cid تصویر درون‌متنی می‌شود.
headersبدنهobjectسرایند دلخواه (حداکثر ۱۰)، مثل List-Unsubscribe.
tagsبدنهstring[]برچسب‌های آماری (حداکثر ۱۰).
scheduledAtبدنهstring (ISO 8601)ارسال در آینده (تا یک سال).
templateبدنهobject{name, variables} برای استفاده از قالب ذخیره‌شده.
Idempotency-Keyهدرstringکلید یکتا؛ تکرار درخواست نه دوباره می‌فرستد و نه دوباره هزینه می‌گیرد.

خطاهای خاص این endpoint

400bad_recipientنشانی گیرنده معتبر نیست.
402email_no_creditسهمیهٔ بسته، بستهٔ ارسال و موجودی کیف پول برای این ارسال کافی نیست.
403sender_not_allowedفرستنده متعلق به شما نیست.
403domain_not_verifiedدامنهٔ فرستنده هنوز تأیید نشده است.
403email_sending_blockedارسال حساب به‌علت نرخ بازگشت/شکایت بالا مسدود شده است.
422all_suppressedهمهٔ گیرندگان در فهرست ممنوعه‌اند.
429daily_limitسقف ارسال روزانهٔ بسته پر شده است.
401unauthorizedکلید API نامعتبر یا منقضی است.
403feature_disabledقابلیت ایمیل (یا دامنهٔ دسترسی لازم) برای کلید/حساب شما فعال نیست.

اجرای زنده (محیط تست)

باز کردن در کنسول کامل ←

این endpoint در محیط تست پشتیبانی نمی‌شود؛ برای اجرا، کلید واقعی را در حالت «اجرای واقعی» وارد کنید.

→ قبلی
اعتبار
بعدی ←
وضعیت و رویدادهای یک ایمیل
curl -X POST 'https://api.irnoti.com/v1/email/send' \
  -H "Authorization: Bearer $IRNOTI_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042' \
  -d '{
  "to": [
    "customer@gmail.com"
  ],
  "from": "noreply@example.ir",
  "html": "<p>سلام! سفارش <b>۱۰۴۲</b> ثبت شد.</p>",
  "tags": [
    "order"
  ],
  "subject": "سفارش شما ثبت شد",
  "fromName": "فروشگاه نمونه"
}'
پاسخ نمونه200 OK
{
  "id": "5012",
  "to": [
    "customer@gmail.com"
  ],
  "cost": "0",
  "from": "noreply@example.ir",
  "error": null,
  "sentAt": "2026-10-21T10:00:01.000Z",
  "status": "sent",
  "subject": "سفارش شما ثبت شد",
  "billedVia": "plan",
  "createdAt": "2026-10-21T10:00:00.000Z",
  "duplicate": false,
  "recipients": 1,
  "scheduledAt": null
}
ارسال ایمیل — مستندات API | ایران ناتیفیکیشن