REST API · JSON · v1

مستندات API پیامک

وب‌سرویس REST با بدنه JSON. هر کاری که در پنل انجام می‌دهید با API هم ممکن است. همه نمونه‌ها برای ۱۱ زبان تولید می‌شود و می‌توانید هر درخواست را همین‌جا با کلید آزمایشی اجرا کنید.

شروع سریع

۱در پنل ثبت‌نام کنید و از بخش «وب‌سرویس» یک کلید آزمایشی بسازید.
۲با lineId: "sandbox" یک پیام بفرستید — بدون هزینه و بدون ارسال واقعی.
۳پس از احراز هویت، کلید واقعی بسازید و شناسه خط واقعی را از خطوط من بگیرید.

برای شروع سریع‌تر می‌توانید از SDKها و پکیج‌های آماده استفاده کنید، به‌جای اینکه درخواست‌ها را از ابتدا بنویسید.

آدرس پایه

BASEhttps://api.irnoti.com/v1

احراز هویت

هر درخواست باید کلید دسترسی را در هدر Authorization: Bearer irn_live_… داشته باشد. کلید فقط هنگام ساخت یک‌بار نمایش داده می‌شود و در سرور ما فقط به‌صورت هش نگهداری می‌شود؛ آن را در کد سمت کاربر (مرورگر/اپ) قرار ندهید.

دسترسی (scope)	اجازه
sms.send	ارسال پیامک و پترن
sms.read	برآورد هزینه، گزارش پیام‌ها و خطوط
wallet.read	مشاهده اعتبار
phonebook.read	خواندن دفترچه تلفن
phonebook.write	ویرایش دفترچه تلفن
bot.send	ربات‌ساز: ارسال پیام و کد تأیید
bot.read	ربات‌ساز: مشاهده ربات‌ها و مشترکین
verify.send	تأیید با لینک: ساخت و لغو جلسه
verify.read	تأیید با لینک: مشاهده وضعیت
broker.read	بروکر رویداد: مشاهدهٔ لینک‌ها و وب‌هوک
broker.write	بروکر رویداد: ثبت، ویرایش و حذف لینک سرویس‌ها و تنظیم وب‌هوک
broker.request	بروکر رویداد: ارسال درخواست به تلگرام و دریافت آپدیت‌ها (ویژهٔ ربات تلگرام)
tts.say	تبدیل متن به گفتار (TTS) برای VoIP و IVR

برای هر کلید می‌توانید فهرست IP مجاز تعیین کنید؛ درخواست از IP دیگر ۴۰۱ می‌گیرد.
کلید آزمایشی با پیشوند irn_test_ شروع می‌شود و هرگز پیام واقعی نمی‌فرستد.
ساخت و حذف کلید فقط از پنل ممکن است، نه با خودِ کلید.

قراردادها

آدرس پایه: https://api.irnoti.com/v1
مبلغ‌ها عدد صحیح به ریال و به‌صورت رشته هستند (مثلا "1960")؛ هرگز اعشار نیستند.
شماره‌ها: 09121234567، +989121234567 و ارقام فارسی پذیرفته می‌شود.
زمان‌ها ISO 8601 در UTC هستند.
Idempotency: برای ارسال، هدر Idempotency-Key بفرستید تا تلاش دوباره (timeout، قطع اینترنت) پیام تکراری نسازد.
محدودیت نرخ: ارسال تا ۶۰۰ و پترن تا ۱۲۰۰ درخواست در دقیقه برای هر IP؛ پاسخ 429 یعنی کمی صبر کنید.

محدودیت نرخ

در صورت عبور از محدودیت، پاسخ 429 برگردانده می‌شود. محدودیت‌ها به‌ازای هر IP و در هر دقیقه‌اند.

ارسال پیامک600 req/min

ارسال پترن1200 req/min

خطاها

کد وضعیت HTTP نتیجه را مشخص می‌کند. بدنه خطا شامل message و گاهی code و details است.

400	درخواست نامعتبر (فیلد ناقص، شماره نامعتبر…)
401	کلید نامعتبر، حذف‌شده یا IP مجاز نیست
402	اعتبار کافی نیست
403	دسترسی (scope) یا احراز هویت حساب کافی نیست
404	منبع یافت نشد
409	تعارض (مثلا نام تکراری)
422	تعرفه تعریف نشده
429	تعداد درخواست زیاد
5xx	خطای سرور — با همان Idempotency-Key دوباره تلاش کنید

مرجع endpointها

POST/sms/sos

ارسال تضمین‌شده (SOS)

ارسال پیام حیاتی از مسیرهای پلتفرم با جایگزینی خودکار پرووایدر.

POST/sms/send

ارسال پیامک

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

POST/sms/quote

برآورد هزینه

هزینه دقیق یک ارسال را بدون ارسال و بدون کسر اعتبار برمی‌گرداند.

POST/sms/pattern

ارسال پترن (قالب)

ارسال پیام بر اساس یک قالب تأییدشده با جایگذاری پارامترها — مناسب کد تأیید و پیام‌های تراکنشی.

GET/sms/messages

فهرست پیام‌ها

پیام‌های ارسالی اخیر با وضعیت تحویل.

GET/sms/messages/{id}

جزئیات یک پیام

وضعیت و جزئیات یک پیام با شناسه.

GET/sms/lines

خطوط من

خطوطی که می‌توانید از آن‌ها ارسال کنید.

GET/broker/bots

فهرست ربات‌ها

فهرست رباتِ ثبت‌شده در بروکر با لینک اختصاصی و وضعیت.

GET/broker/bots/{id}

مشاهدهٔ یک ربات

جزئیات یک ربات شامل لینک و آدرس وب‌هوک ثبت‌شده.

POST/broker/bots

ثبت ربات

توکن ربات را ثبت کنید و لینک اختصاصی بگیرید.

PATCH/broker/bots/{id}

ویرایش نام

نام نمایشی ربات را عوض کنید.

PUT/broker/bots/{id}/token

تعویض توکن

بعد از ساخت توکن جدید در BotFather، آن را برای همین ربات جایگزین کنید.

POST/broker/bots/{id}/rotate

لینک جدید

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

DELETE/broker/bots/{id}

حذف ربات

ربات را از بروکر حذف کنید؛ لینک و ثبت بروکر پاک می‌شود.

POST/broker/bots/{id}/request

ارسال درخواست به تلگرام

هر متد Bot API (sendMessage، sendPhoto، getChat، …) را از طریق بروکر اجرا کنید.

POST/broker/bots/{id}/updates

دریافت درخواست‌ها (Polling)

پیام‌های رسیده به ربات را بخوانید (getUpdates)، بدون نیاز به سرور وب‌هوک.

GET/broker/bots/{id}/webhook

وضعیت وب‌هوک

آدرس بازگشتی (وب‌هوک) تنظیم‌شده و وضعیت تحویل آن.

PUT/broker/bots/{id}/webhook

تنظیم آدرس بازگشتی (وب‌هوک)

آدرس سرور خودتان را بدهید؛ آپدیت‌های تلگرام از طریق بروکر به همان آدرس POST می‌شوند.

DELETE/broker/bots/{id}/webhook

حذف وب‌هوک

وب‌هوک را بردارید (برای استفاده از getUpdates).

GET/phonebook/groups

گروه‌های دفترچه تلفن

فهرست گروه‌ها با تعداد مخاطبین.

POST/phonebook/groups

ساخت گروه

یک گروه جدید در دفترچه تلفن بسازید.

POST/phonebook/groups/{id}/contacts

افزودن مخاطب

افزودن چند مخاطب به یک گروه.

GET/wallet

اعتبار

موجودی کیف پول به ریال.

POST/email/send

ارسال ایمیل

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

GET/email/outbound/{id}

وضعیت و رویدادهای یک ایمیل

وضعیت ارسال و خط زمانی رویدادها (ارسال، تحویل، بازگشت، شکایت).

GET/email/outbound

فهرست ایمیل‌های ارسالی

ارسال‌های شما با فیلتر وضعیت و جستجو؛ صفحه‌بندی با `before`.

POST/email/outbound/{id}/cancel

لغو ایمیل زمان‌بندی‌شده

نامهٔ زمان‌بندی‌شدهٔ هنوز ارسال‌نشده را لغو و هزینه را برمی‌گرداند.

GET/email/otp

آخرین کدهای تأیید در صندوق

کدهای OTP که در نامه‌های رسیده شناسایی شده‌اند (جدیدترین اول).

GET/email/otp/wait

انتظار برای کد تأیید جدید

تا رسیدن کد جدید (حداکثر ۶۰ ثانیه) صندوق را بررسی می‌کند؛ مناسب تست خودکار ورود.

GET/email/messages

فهرست نامه‌های دریافتی

نامه‌های صندوق با پوشه، دسته، جستجو و صفحه‌بندی.

GET/email/messages/{id}

خواندن یک نامه

متن کامل نامه با HTML امن‌شده و فهرست پیوست‌ها.

POST/email/messages/actions

عملیات روی نامه‌ها

خوانده/ستاره/انتقال/حذف/هرزنامه/برچسب برای چند نامه.

GET/email/domains

فهرست دامنه‌ها

دامنه‌های شما با وضعیت تأیید و شمار صندوق.

POST/email/domains

افزودن دامنه

دامنه را ثبت و رکوردهای DNS لازم را برمی‌گرداند.

POST/email/domains/{id}/check

بررسی رکوردهای DNS

DNS را بررسی و در صورت کامل بودن دامنه را تأیید می‌کند.

POST/email/mailboxes

ساخت صندوق سازمانی

برای دامنهٔ خود صندوق (و زیرمجموعه) بسازید.

PUT/email/templates

ساخت یا بروزرسانی قالب

قالب ایمیل تراکنشی با متغیر `{{name}}`.

POST/email/suppressions

افزودن به فهرست ممنوعه

به نشانی اضافه‌شده دیگر ایمیل ارسال نمی‌شود.

GET/email/me

وضعیت اشتراک و مصرف ایمیل

اشتراک فعال، سقف‌ها، سهمیهٔ ماهانه، بستهٔ ارسال و موجودی کیف پول برای ایمیل.

GET/email/info

نشانی SMTP و رویدادهای وب‌هوک

میزبان و پورت درگاه SMTP و فهرست رویدادهایی که می‌توان به آن‌ها مشترک شد.

GET/email/report

گزارش مصرف و کیفیت ارسال

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

GET/email/outbound.csv

خروجی CSV ارسال‌ها

همان فهرست ارسال‌ها با فیلترهای یکسان، به‌صورت فایل CSV.

GET/email/counts

تعداد خوانده‌نشده‌ها

تعداد نامهٔ خوانده‌نشده به تفکیک پوشه و دسته، به‌همراه ستاره‌دارها و پیش‌نویس‌ها.

GET/email/threads/{threadId}

رشتهٔ گفتگو

همهٔ نامه‌های یک گفتگو به ترتیب زمان.

POST/email/messages/{id}/check-sender

بررسی اصالت فرستنده

سرایند احراز هویت همان نامه را از سرور دوباره می‌خواند و می‌گوید چرا «تیک آبی» ندارد یا دارد.

POST/email/drafts

ذخیرهٔ پیش‌نویس

پیش‌نویس جدید می‌سازد یا با `id` پیش‌نویس موجود را ویرایش می‌کند.

POST/email/messages/empty

خالی‌کردن سطل زباله یا هرزنامه

همهٔ نامه‌های پوشهٔ `trash` یا `spam` را برای همیشه حذف می‌کند.

POST/email/sync

همگام‌سازی فوری صندوق

نامه‌های جدید را همین الان از سرور می‌گیرد، به‌جای انتظار برای همگام‌سازی دوره‌ای.

GET/email/mailboxes

فهرست صندوق‌ها

صندوق‌های سازمانی و حساب‌های شخصی متصل‌شدهٔ شما، و صندوق‌هایی که به شما تخصیص داده شده است.

GET/email/mailboxes/{id}/settings

تنظیمات اتصال نرم‌افزار ایمیل

میزبان، پورت و امنیت IMAP، POP3 و SMTP برای وصل‌کردن Outlook، Thunderbird یا موبایل.

PATCH/email/mailboxes/{id}

ویرایش صندوق

نام نمایشی، امضا، پاسخ خودکار، تخصیص به همکار و سهمیهٔ فضا را تغییر می‌دهد.

POST/email/mailboxes/{id}/password

رمز جدید صندوق

برای صندوق سازمانی رمز تازه می‌سازد (یا رمز دلخواه شما را می‌گذارد) و همان‌جا یک‌بار برمی‌گرداند.

DELETE/email/mailboxes/{id}

حذف صندوق

صندوق و همهٔ نامه‌های آن را حذف می‌کند.

GET/email/domains/{id}

جزئیات دامنه و رکوردهای DNS

وضعیت دامنه و رکوردهای DNS که باید بسازید (تأیید مالکیت، MX، SPF، DKIM، DMARC).

PUT/email/domains/{id}/catch-all

تنظیم Catch-all

نامهٔ ارسال‌شده به هر نشانی ناموجود دامنه را به یک صندوق می‌رساند.

DELETE/email/domains/{id}

حذف دامنه

دامنه با همهٔ صندوق‌ها، نام‌های مستعار و نامه‌هایش حذف می‌شود.

GET/email/domains/{id}/aliases

فهرست نام‌های مستعار

نام‌های مستعار (فوروارد) یک دامنه.

POST/email/domains/{id}/aliases

افزودن نام مستعار

نشانی تازه می‌سازد که نامه‌هایش به صندوق‌های مقصد می‌رسد.

PATCH/email/aliases/{id}

ویرایش مقصدهای نام مستعار

فهرست مقصدهای یک نام مستعار را جایگزین می‌کند.

DELETE/email/aliases/{id}

حذف نام مستعار

نام مستعار را حذف می‌کند.

GET/email/contacts

فهرست مخاطبین

مخاطبین ایمیل با جستجو و فیلتر گروه.

POST/email/contacts

افزودن مخاطب

مخاطب جدید می‌سازد.

PATCH/email/contacts/{id}

ویرایش مخاطب

فقط فیلدهای ارسال‌شده تغییر می‌کنند.

DELETE/email/contacts/{id}

حذف مخاطب

مخاطب را حذف می‌کند.

GET/email/contacts.csv

خروجی CSV مخاطبین

همهٔ مخاطبین به‌صورت فایل CSV.

POST/email/contacts/import/csv

ورود مخاطبین از CSV

متن CSV را می‌خواند و مخاطبین تازه را اضافه می‌کند.

POST/email/contacts/import/vcard

ورود مخاطبین از vCard

فایل vCard (‎.vcf) را می‌خواند و مخاطبین را اضافه می‌کند.

برچسب‌های شما.

برچسب جدید.

PATCH/email/labels/{id}

ویرایش برچسب

نام یا رنگ برچسب.

DELETE/email/labels/{id}

حذف برچسب

برچسب را از همهٔ نامه‌ها برمی‌دارد.

GET/email/rules

فهرست قوانین

قوانین خودکار پردازش نامهٔ ورودی.

POST/email/rules

ساخت قانون

قانون جدید برای نامه‌های ورودی.

PATCH/email/rules/{id}

ویرایش قانون

فقط فیلدهای ارسال‌شده تغییر می‌کنند.

DELETE/email/rules/{id}

حذف قانون

قانون را حذف می‌کند.

GET/email/templates

فهرست قالب‌ها

قالب‌های ذخیره‌شدهٔ ارسال.

DELETE/email/templates/{id}

حذف قالب

قالب را حذف می‌کند.

GET/email/suppressions

فهرست ممنوعه

نشانی‌هایی که ارسال به آن‌ها انجام نمی‌شود.

DELETE/email/suppressions

خارج‌کردن از فهرست ممنوعه

یک نشانی را دوباره مجاز می‌کند.

GET/email/otp-relays

فهرست بازارسال کد تأیید

قوانینی که کد تأیید رسیده به ایمیل را به پیامک، بله یا تلگرام می‌فرستند.

POST/email/otp-relays

ساخت بازارسال کد تأیید

کد OTP تشخیص‌داده‌شده در صندوق را خودکار به مقصد دلخواه می‌فرستد.

POST/email/otp-relays/{id}/verify

تأیید مقصد بازارسال

کد ۶ رقمی رسیده به مقصد را تأیید می‌کند.

POST/email/otp-relays/{id}/resend

ارسال دوباره کد تأیید مقصد

کد تأیید مقصد را دوباره می‌فرستد.

POST/email/otp-relays/{id}/test

ارسال آزمایشی

یک کد نمونه به مقصد می‌فرستد تا مسیر را امتحان کنید.

PATCH/email/otp-relays/{id}

روشن یا خاموش کردن بازارسال

بازارسال را بدون حذف فعال یا غیرفعال می‌کند.

DELETE/email/otp-relays/{id}

حذف بازارسال

بازارسال را حذف می‌کند.

GET/tts/say

تبدیل متن به گفتار (GET)

متن فارسی ← فایل صوتی ۸ کیلوهرتز برای IVR و VoIP؛ مناسب آدرس ttsUrl سانترال.

POST/tts/say

تبدیل متن به گفتار (POST)

همان عملیات GET با بدنهٔ JSON؛ برای متن‌های بلند یا وقتی نمی‌خواهید متن در آدرس بیاید.

GET/public/tts/info

صداها، قالب‌ها و تعرفهٔ TTS

فهرست صداها و قالب‌های در دسترس، سقف‌ها و تعرفهٔ پایه؛ بدون کلید.

بعدی ←