پیامک را با چند خط کد به نرمافزارتان وصل کنید
API استاندارد REST با پاسخ JSON، احراز هویت Bearer و کد نمونه آماده برای PHP، Node.js، Python و cURL — از ارسال تا گزارش تحویل، همهچیز مستند شده است.
1curl -X POST "https://api.mrsms.ir/v2/sms/send" \2 -H "Authorization: Bearer MRSM_API_KEY" \3 -H "Content-Type: application/json" \4 -d '{5 "to": ["09121234567"],6 "from": "9830005500",7 "text": "سلام از MrSMS!"8 }'910# → {"status":"ok","data":{"message_id":84521,"parts":1}}شروع سریع
در سه قدم اولین پیامک API خود را بفرستید — کل فرآیند کمتر از ۵ دقیقه طول میکشد.
کلید API بگیرید
ثبتنام کنید و از مسیر تنظیمات ← کلیدهای API یک کلید جدید بسازید. کلید را مثل رمز عبور نگه دارید.
درخواست بفرستید
با یک POST ساده به sms/send و هدر Authorization، اولین پیامک را ارسال کنید و message_id بگیرید.
تحویل را چک کنید
با sms/status و همان message_id وضعیت لحظهای تحویل هر گیرنده را استعلام کنید.
احراز هویت
همه درخواستها باید هدر Authorization با کلید API شما را داشته باشند.
هدر استاندارد Bearer
کلید API را در هدر Authorization با پیشوند Bearer بفرستید. ارتباط شما با سرور همیشه با رمزنگاری TLS امن میماند.
1Authorization: Bearer MRSM_API_KEY2Content-Type: application/jsonنکات امنیتی مهم
- کلید API را هرگز در کد سمتکلاینت (مرورگر/اپ موبایل) قرار ندهید — همیشه از سرور درخواست بفرستید.
- برای هر محیط (توسعه/تولید) یک کلید جدا بسازید تا در صورت لو رفتن، بقیه سرویس سالم بماند.
- محدودسازی IP را فعال کنید تا کلید فقط از سرورهای شما قابل استفاده باشد.
- اگر کلیدی لو رفت، بلافاصله از پنل حذف یا بازتولید (Rotate) کنید.
مرجع Endpointها
سه نقطه اتصال اصلی — روی هر کارت کلیک کنید تا پارامترها، نمونه پاسخ و خطاها باز شود.
1{2 "status": "ok",3 "data": {4 "message_id": 84521,5 "parts": 1,6 "cost": 1290,7 "balance_after": 1485008 }9}INVALID_NUMBERفرمت شماره گیرنده اشتباه است
INSUFFICIENT_CREDITاعتبار حساب برای ارسال کافی نیست
TEXT_TOO_LONGمتن پیام بیش از ۱۰ بخش است
1{2 "status": "ok",3 "data": {4 "message_id": 84521,5 "delivery": "delivered",6 "delivered_at": "2026-09-10T14:32:05+03:30",7 "recipients": [8 { "to": "09121234567", "delivery": "delivered" }9 ]10 }11}NOT_FOUNDپیامی با این message_id یافت نشد
این endpoint پارامتری ندارد — فقط هدر Authorization کافی است.
1{2 "status": "ok",3 "data": {4 "credit": 148500,5 "currency": "IRR",6 "sms_count": 11507 }8}خطای اختصاصی ندارد؛ فقط خطاهای عمومی (۴۰۱ و ۴۲۹) ممکن است رخ دهد.
کد نمونه — سناریوی کامل
ارسال + استعلام تحویل در چهار زبان؛ کافی است MRSM_API_KEY را با کلید خودتان جایگزین کنید.
1# ۱) ارسال2curl -X POST "https://api.mrsms.ir/v2/sms/send" \3 -H "Authorization: Bearer MRSM_API_KEY" \4 -H "Content-Type: application/json" \5 -d '{"to":["09121234567"],"from":"9830005500","text":"سلام از MrSMS!"}'67# ۲) استعلام وضعیت8curl "https://api.mrsms.ir/v2/sms/status?message_id=84521" \9 -H "Authorization: Bearer MRSM_API_KEY"وضعیتهای تحویل
مقادیر فیلد delivery در پاسخ sms/status و معنی هرکدام.
deliveredتحویلشدهپیام با موفقیت به گوشی گیرنده رسیده است
sentارسالشده به اپراتورپیام به اپراتور تحویل شده و در انتظار پاسخ تحویل است
pendingدر صف ارسالپیام در صف MrSMS است و بهزودی ارسال میشود
failedناموفقارسال ناموفق — شماره اشتباه، خارج از سرویس یا مسدود
expiredمنقضیشدهپیام در بازه اعتبار (معمولاً ۲۴ ساعت) تحویل نشد
وضعیت هر پیام معمولاً در کمتر از ۳۰ ثانیه نهایی میشود؛ برای استعلام، فاصله ۵ تا ۱۰ ثانیهای کافی است.
کدهای خطا
همه خطاها با کد HTTP استاندارد و بدنه JSON برمیگردند.
1{2 "status": "error",3 "error": {4 "code": "INSUFFICIENT_CREDIT",5 "message": "اعتبار حساب برای ارسال کافی نیست"6 }7}محدودیت نرخ فراخوانی
برای پایداری سرویس، هر کلید API محدودیت نرخ دارد؛ هدرهای X-RateLimit در هر پاسخ برگردانده میشوند.
۱۰ درخواست / ثانیه
نرخ پایدار هر کلید API در بازههای یکثانیهای
۶۰ درخواست / دقیقه
سقف انفجاری (Burst) برای رگبار درخواستهای کوتاه
Retry با Backoff
در خطای ۴۲۹ طبق هدر Retry-After و با فاصله نمایی تلاش کنید
برای ارسالهای سازمانی با نرخ بالاتر، پشتیبانی میتواند سقف اختصاصی برای کلید شما تنظیم کند — کافی است از بخش تماس درخواست دهید.
سوالات متداول توسعهدهندگان
پاسخ سریع رایجترین سوالات فنی درباره وبسرویس.
ثبتنام کنید، از بخش تنظیمات پنل گزینه «کلیدهای API» را انتخاب و یک کلید جدید بسازید. میتوانید برای هر محیط کلید جداگانه بسازید و محدودیت IP فعال کنید.
هر کلید ۱۰ درخواست در ثانیه و سقف انفجاری ۶۰ درخواست در دقیقه دارد. برای حجم بالاتر، پشتیبانی سقف اختصاصی تنظیم میکند.
API کاملاً REST و استاندارد است و با هر زبانی که HTTP client دارد کار میکند. کد آماده برای PHP، Node.js، Python و cURL در همین صفحه موجود است.
پس از ارسال، message_id یکتا میگیرید. با sms/status وضعیت لحظهای (تحویلشده، در صف، ناموفق و…) را استعلام کنید؛ وضعیت معمولاً زیر ۳۰ ثانیه نهایی میشود.
کلید API نامعتبر یا حذف شده، یا هدر Authorization غلط تنظیم شده است. فرمت صحیح: Authorization: Bearer YOUR_KEY — حتماً فاصله بعد از Bearer را رعایت کنید.
بله؛ فیلد اختیاری send_at را با تاریخ ISO 8601 بفرستید تا پیام در زمان مشخصشده ارسال شود. تا لحظه ارسال میتوانید اعتبار را آزاد نکنید و پیام در صف میماند.