ارسال ایمیل

مرجع POST /v1/emails، با همه‌ی فیلدها، قالب‌ها و پاسخ.

آخرین ویرایش: ۲۱ آبان ۱۴۰۵

با یک درخواست HTTP، یک ایمیل را به یک یا چند گیرنده بفرستید.

endpoint

POST https://api.sendak.ir/v1/emails
Authorization: Bearer sd_live_…
Content-Type: application/json

نمونه

cURL

curl https://api.sendak.ir/v1/emails \
  -H "Authorization: Bearer sd_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@shop.ir",
    "from_name": "فروشگاه",
    "to": ["ali@gmail.com"],
    "subject": "کد ورود شما",
    "text": "کد شما: 482913",
    "tags": ["otp"]
  }'

فیلدها

فیلد	نوع	توضیح
`from`	رشته، لازم	نشانی فرستنده روی دامنه‌ی تأییدشده
`from_name`	رشته	نام نمایشی، حداکثر ۱۰۰ نویسه
`to`	آرایه، لازم	گیرنده‌ها
`cc`، `bcc`	آرایه	رونوشت
`reply_to`	رشته	نشانی پاسخ
`subject`	رشته، لازم	حداکثر ۲۵۵ نویسه؛ با `template_id` اختیاری است
`text`	رشته	متن ساده
`html`	رشته	نسخه‌ی HTML
`template_id`	رشته	شناسه‌ی قالب، ۲۶ نویسه
`variables`	شیء	متغیرهای قالب، حداکثر ۲۰ مورد
`tags`	آرایه	برچسب، حداکثر ۱۰ مورد
`metadata`	شیء	داده‌ی دلخواه شما، حداکثر ۱۰ مورد
`category`	رشته	`transactional` یا `marketing`
`list_unsubscribe`	منطقی	پیوند لغو اشتراک اضافه شود
`attachments`	آرایه	پیوست، حداکثر ۱۰ مورد
`headers`	شیء	هدرهای دلخواه، حداکثر ۲۰ مورد

حداقل یکی از text یا html لازم است (مگر با قالب). مجموع گیرنده‌ها (to و cc و bcc) حداکثر ۵۰ است.

مقدارها و محدودیت‌ها

همه‌ی نشانی‌ها حداکثر ۲۵۴ نویسه و معتبر باشند.
subject، from_name، مقدار metadata و هدرها نباید نویسه‌ی کنترلی (مثل خط جدید) داشته باشند. این از تزریق هدر جلوگیری می‌کند.
tags: فقط حروف لاتین، رقم، _ و -، حداکثر ۳۲ نویسه.
metadata: مقدارها رشته‌اند و حداکثر ۲۰۰ نویسه.
اندازه‌ی بدنه‌ی پیام در API حداکثر ۱ مگابایت است (پیوست‌ها جدا حساب می‌شوند).

قالب

قالب را در پنل می‌سازید. در ارسال، template_id و variables را بدهید:

با قالب

{
  "from": "hello@shop.ir",
  "to": ["ali@gmail.com"],
  "template_id": "01JCX9ABCDEFGHJKMNPQRSTVWX",
  "variables": { "name": "علی", "code": "482913" }
}

در متن قالب، {{name}} با مقدار متغیر عوض می‌شود. نام متغیر با حرف یا _ شروع می‌شود و حروف لاتین، رقم و _ دارد. این قاعده‌ها برقرارند:

در HTML، مقدار متغیر escape می‌شود؛ مقدار حاوی <script> تبدیل به متن می‌شود.
خط جدید از مقدار حذف می‌شود، پس مقدار نمی‌تواند هدر تازه‌ای بسازد.
متغیری که نفرستاده‌اید خالی می‌شود، نه خطا.
اگر subject ندهید، موضوع قالب به کار می‌رود.

برچسب‌ها

tags و metadata در وب‌هوک به شما برمی‌گردند و برای دسته‌بندی در سمت خودتان‌اند. یک برچسب معنی ویژه دارد:

otp: ایمیل را کد یک‌بارمصرف می‌شمارد؛ ردیابی به آن اضافه نمی‌شود. راهنما: ارسال OTP.

پیش‌فرض ایمیل transactional است و به لغو اشتراک گیرنده‌ها توجه نمی‌کند. اگر category را marketing بگذارید (یا list_unsubscribe را true)، سندک هدر List-Unsubscribe و لغو با یک کلیک اضافه می‌کند و گیرنده‌ی لغوکرده را رد می‌کند.

هشدار: سندک برای ایمیل تراکنشی ساخته شده است. ارسال انبوه یک متن یکسان به تعداد زیادی گیرنده ممکن است حساب را برای بررسی نگه دارد و در صورت تکرار به تعلیق برسد. ببینید استفاده‌ی مجاز.

هدرهای دلخواه

فقط این‌ها مجازند: List-Unsubscribe، List-Unsubscribe-Post، In-Reply-To، References و هر هدری که با X- شروع شود. هدرهای X-Sendak-* برای سندک رزرو شده‌اند. مقدار In-Reply-To و References باید شناسه‌ی پیام باشد.

پاسخ

پاسخ موفق 202 Accepted است و یعنی پیام در صف قرار گرفت، نه اینکه تحویل شد. تحویل را از وب‌هوک یا صفحه‌ی «فعالیت» دنبال کنید.

202 Accepted

{
  "data": [
    { "to": "ali@gmail.com", "id": "01JCX9…", "status": "queued" }
  ]
}

برای هر گیرنده یک شناسه برمی‌گردد. اگر گیرنده در فهرست حذف باشد، status برابر suppressed و id برابر null است؛ آن گیرنده ارسال نمی‌شود و از سهمیه کم نمی‌شود.

برای خطاها خطاها و سقف‌ها را ببینید. برای جلوگیری از ارسال تکراری هنگام تلاش دوباره، کلید یکتایی درخواست را بخوانید.