مستندات Snad Mail API

توکن را در یکی از این دو هدر بفرستید:

X-API-Token: YOUR_TOKEN
Authorization: Bearer YOUR_TOKEN

منسوخ (Deprecated): فرستادن توکن در پارامتر token (در آدرس یا بدنه) هنوز کار می‌کند تا برنامه‌های قدیمی از کار نیفتند، ولی توکن را در لاگ سرور، تاریخچه مرورگر و Referer لو می‌دهد. پاسخ این درخواست‌ها هدر Deprecation: true دارد؛ لطفاً به هدر مهاجرت کنید. اگر هم هدر و هم پارامتر فرستاده شود، هدر ملاک است.

to: ایمیل گیرنده · subject: موضوع (حداکثر ۲۰۰ نویسه، بدون خط جدید) · message یا body: متن ساده ایمیل (حداکثر ۲۰۰۰۰ نویسه)

بدنه را می‌توانید به‌صورت JSON (Content-Type: application/json) یا فرم (application/x-www-form-urlencoded) بفرستید.

curl -X POST 'https://mr-amir.developer-noovin.ir/snad/email.php?api=send' \
  -H 'X-API-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"to":"recipient@example.com","subject":"سلام","message":"متن ایمیل"}'

curl -X POST 'https://mr-amir.developer-noovin.ir/snad/email.php?api=send' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d 'to=recipient@example.com' -d 'subject=Hello' -d 'message=Test'

$data = ['to' => 'recipient@example.com', 'subject' => 'سلام', 'message' => 'متن ایمیل'];
$ch = curl_init('https://mr-amir.developer-noovin.ir/snad/email.php?api=send');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-API-Token: YOUR_TOKEN'],
  CURLOPT_POSTFIELDS => json_encode($data),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 20,
]);
$res = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if (!$res['ok']) echo "خطا $status: " . $res['error'];

const r = await fetch('https://mr-amir.developer-noovin.ir/snad/email.php?api=send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Token': process.env.SNAD_TOKEN },
  body: JSON.stringify({ to: 'recipient@example.com', subject: 'سلام', message: 'متن ایمیل' })
});
console.log(r.status, await r.json());

توکن را هیچ‌وقت در کد سمت مرورگر (فرانت‌اند) قرار ندهید؛ هر کسی می‌تواند آن را ببیند.

curl -G 'https://mr-amir.developer-noovin.ir/snad/email.php?api=send' -H 'X-API-Token: YOUR_TOKEN' \
  --data-urlencode 'to=recipient@example.com' --data-urlencode 'subject=Hello' --data-urlencode 'message=Test'

روش قدیمی ...&token=YOUR_TOKEN&to=... هنوز پشتیبانی می‌شود ولی منسوخ است.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

{"ok":true,"message":"ایمیل به سرور SMTP تحویل داده شد.","credits_remaining":99}

همه خطاها JSON با "ok":false و یک کد ثابت در error هستند؛ برنامه را بر اساس error بنویسید، نه متن message.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{"ok":false,"error":"invalid_recipient","message":"آدرس گیرنده معتبر نیست."}

• هر توکن حداکثر ۲۰ درخواست در دقیقه می‌تواند بفرستد. هدرهای X-RateLimit-Limit و X-RateLimit-Remaining وضعیت فعلی را نشان می‌دهند.
• بعد از خطای 429 یا 503 با تأخیر افزایشی (مثلاً ۱، ۲، ۴ ثانیه) دوباره تلاش کنید؛ خطاهای 4xx دیگر را تکرار نکنید.
• هر ارسال موفق یک اعتبار مصرف می‌کند و در خطای SMTP اعتبار برمی‌گردد.
• فقط به گیرنده‌هایی ایمیل بفرستید که خودشان اجازه داده‌اند. ارسال هرزنامه، فیشینگ یا تبلیغات ناخواسته ممنوع است و باعث مسدود شدن حساب می‌شود.
• اگر توکن لو رفت، از پنل کاربری «ساخت توکن جدید» را بزنید؛ توکن قبلی فوراً از کار می‌افتد.