کلید یکتایی درخواست

اگر درخواست را فرستادید ولی پاسخی نگرفتید (قطع شبکه، مهلت تمام‌شده)، نمی‌دانید ایمیل صف شد یا نه. دوباره فرستادن می‌تواند یک ایمیل را دو بار بفرستد. Idempotency-Key این مشکل را حل می‌کند.

چطور کار می‌کند

برای هر ارسال یک مقدار یکتا در هدر بگذارید:

curl https://api.sendak.ir/v1/emails \
  -H "Authorization: Bearer sd_live_…" \
  -H "Idempotency-Key: reset-order-1201-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"from":"hello@shop.ir","to":["ali@gmail.com"],"subject":"سلام","text":"متن"}'

• بار اول، ایمیل صف می‌شود و پاسخ ذخیره می‌شود.
• اگر همان کلید با همان بدنه دوباره بیاید، همان پاسخ ذخیره‌شده برمی‌گردد، با کد 200 و هدر Idempotent-Replayed: true. ایمیل دوباره نمی‌رود.
• اگر همان کلید با بدنه‌ی دیگر بیاید، خطای idempotency_key_reused (۴۲۲) می‌گیرید.

قاعده‌ی کلید

۱ تا ۱۰۰ نویسه از حروف لاتین، رقم و _ . : -. کلید نامعتبر خطای bad_idempotency_key (۴۲۲) می‌دهد.

مدت نگهداری

پاسخ ذخیره‌شده ۲۴ ساعت می‌ماند. هدف کلید محافظت از تلاش‌های فوری مشتری است، نه جلوگیری از ارسال دوباره بعد از چند روز. پاسخ ذخیره‌شده فهرست گیرنده‌ها را دارد و به همین دلیل بیشتر از این نگه داشته نمی‌شود.

چه کلیدی بگذارم؟

کلید باید برای هر ایمیل منطقی یکتا باشد و در تلاش‌های دوباره همان بماند. معمولاً ترکیب نوع ایمیل و شناسه‌ی موضوع خوب است:

هشدار: برای هر تلاش کلید تازه نسازید (مثلاً UUID جدید در هر بار). آن‌وقت کلید هیچ کاری نمی‌کند. کلید را یک بار بسازید و در تلاش‌های دوباره همان را بفرستید.

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

ارسال دسته‌ای هم همین هدر را می‌پذیرد و کل درخواست را یک واحد می‌بیند.

SMTP

این سازوکار فقط در API است. در SMTP چنین هدری وجود ندارد.