MailSMMO
تسجيل الدخول

// REST API

توثيق REST API

تستخدم نقاط النهاية المخصصة للأدوات الطريقة GET وتُرجع JSON بالشكل ⁦{ "status": "success", "data": … }⁩. تتم المصادقة بالمعامل ⁦?api_key=⁩ المتاح في صفحة «توثيق API» بعد تسجيل الدخول.

نقاط النهاية

عنوان URL الأساسي: https://mailsmmo.com

GET/api/v1/services

الخدمات — السعر والمخزون

بدون ⁦?service=⁩ يُرجع القائمة كاملة. مع ⁦?service=⁩ يُرجع سعر ومخزون خدمة واحدة. لا حاجة إلى API key.

بدون مصادقة

  • service (اختياري) — اتركه فارغًا للقائمة كاملة؛ الرمز يُرجع خدمة واحدة (تُقبل الرموز المختصرة مثل facebook)

نجاح

{ "status": "success", "data": { "services": [
    { "code": "otp_gmail_facebook", "name": "Facebook", "price": 5000, "stock": 42 }
  ] } }

GET/api/v1/me

معلومات الحساب

المعرّف والبريد الإلكتروني والرصيد لصاحب API key الذي يُجري الاستدعاء.

يتطلب API key

نجاح

{ "status": "success", "data": { "id": "b7e5...-uuid", "email": "demo@mailsmmo.com", "balance": 1000000, "created_at": "2026-01-15T08:30:00Z" } }

GET/api/v1/orders

إنشاء طلب

نقطة نهاية واحدة للحالتين: رمز Gmail OTP (otp_gmail_*) يُصدر صندوق بريد OTP واحدًا؛ ورمز منتج المخزون (hotmail_*…) يشتري حسب الكمية. يُخصم السعر المُعلن من الرصيد.

يتطلب API key

  • service — رمز خدمة OTP (otp_gmail_*) أو رمز منتج المخزون (مثل hotmail_imap_12m_36m)
  • quantity (اختياري) — فقط للبريد المُباع لمرة واحدة — الكمية (الافتراضي 1)
  • unique_key (اختياري) — UUID تُنشئه بنفسك — إعادة الإرسال لن تُنشئ الطلب أو تخصم مرتين

نجاح

{ "status": "success", "data": {
    "id": "b7e5a1c2-3d4e-4f60-8a91-2c3d4e5f6a7b", "email": "zurhansuzu@gmail.com",
    "service": "otp_gmail_facebook", "amount": 5000
  } }

GET/api/v1/orders/otp

الحصول على OTP حسب الطلب

يقرأ OTP لطلب واحد. لا حاجة إلى API key — رمز الطلب (order_id) هو مفتاح الوصول.

بدون مصادقة

  • order_id — رمز الطلب (يُرجع عند إنشاء الطلب)
  • unique_key (اختياري) — UUID جديد تُنشئه بنفسك لكل استدعاء
  • from (اختياري) — ثوانٍ Unix — لا يُرجع otp/received_at إلا إذا وُجد رمز أحدث

نجاح

{ "status": "success", "data": {
    "otp": "481253", "amount": 5000, "received_at": 1732000000,
    "from": "security@facebookmail.com", "otp_history": [
      { "value": "481253", "received_at": 1732000000 }
    ] } }

GET/api/v1/otp/orders

قائمة طلبات OTP

طلبات Gmail OTP المستأجرة، مقسّمة إلى صفحات، مع أحدث OTP لكل طلب.

يتطلب API key

  • page (اختياري) — الصفحة (الافتراضي 1)
  • page_size (اختياري) — عدد الصفوف في الصفحة (الافتراضي 20، الحد الأقصى 200)

نجاح

{ "status": "success", "data": { "orders": [
    { "id": "b7e5a1c2-3d4e-4f60-8a91-2c3d4e5f6a7b", "email": "...", "service": "otp_gmail_facebook",
      "latest_otp": "481253", "latest_link": null }
  ], "page": 1, "page_size": 20, "total": 137 } }

GET/api/v1/mail

قراءة كل الرسائل

كل رسائل صندوق بريد واحد، مع OTP/الرابط المستخرج.

يتطلب API key

  • order_id — رمز الطلب

نجاح

{ "status": "success", "data": { "count": 1, "messages": [
    { "id": 88, "from": "...", "subject": "...", "otp": "481253", "received_at": "..." }
  ] } }

رموز الأخطاء الشائعة

{ "status": "error", "message": "out_of_stock", "retryable": true }
  • unauthorized — API key غير صالح أو مفقود (HTTP 401)
  • invalid_request — معاملات الطلب غير صالحة (HTTP 400)
  • not_found — الخدمة أو الطلب أو نقطة النهاية غير موجودة (HTTP 404)
  • insufficient_balance — الرصيد غير كافٍ (HTTP 402)
  • out_of_stock — نفد المخزون (HTTP 409) — Gmail OTP: قابل لإعادة المحاولة، أعد المحاولة بعد بضع ثوانٍ؛ البريد المُباع نهائيًا: انتظر إعادة التزويد
  • service_unavailable — تعذّر على الخادم إتمام الطلب الآن — أعد المحاولة بنفس unique_key (HTTP 503، قابل لإعادة المحاولة)
  • in_progress — الطلب قيد الإتمام أو ربما موجود بالفعل لدى المزوّد — أعد المحاولة بنفس unique_key (HTTP 409، قابل لإعادة المحاولة)
  • forbidden — لا صلاحية على هذا المورد (HTTP 403)
  • idempotency_mismatch — استُخدم unique_key لطلب مختلف — استخدم unique_key جديدًا (HTTP 422)
  • order_cancelled — أُلغي الطلب قبل الخصم، ولم يُخصم شيء — أعد المحاولة (HTTP 409، قابل لإعادة المحاولة)
  • too_many_requests — طلبات كثيرة جدًا — انتظر ثم أعد المحاولة (HTTP 429، قابل لإعادة المحاولة)
  • auth_unavailable — تعذّر التحقق من API key الآن، والمفتاح سليم — أعد المحاولة (HTTP 503، قابل لإعادة المحاولة)
  • shutting_down — يُعاد تشغيل الخادم — أعد المحاولة بعد بضع ثوانٍ (HTTP 503، قابل لإعادة المحاولة)
  • payload_too_large — جسم الطلب كبير جدًا (HTTP 413)
  • internal_server_error — خطأ في الخادم، يرجى المحاولة لاحقًا (HTTP 500)

توثيق للذكاء الاصطناعي والأدوات

التوثيق الكامل بصيغة Markdown متاح على ⁦https://mailsmmo.com/llms.txt⁩ — الصقه في Cursor أو Claude أو ChatGPT لتوليد شيفرة التكامل.

إعادة المحاولة بأمان مع unique_key

أرسل unique_key (معرّف UUID تولّده بنفسك) مع كل طلب. إذا انقطع الاتصال، أعد المحاولة بنفس unique_key: ستحصل على الطلب نفسه، دون إنشاء طلب جديد ودون خصم ثانٍ.

صيغة الأخطاء

عند حدوث خطأ، لا تحتوي الاستجابة إلا على status وmessage (رمز خطأ بصيغة snake_case) وretryable، الذي يخبرك هل ينبغي إعادة المحاولة.

ابدأ مع MailSMMO

سجّل مجانًا، واشحن محفظتك، واستأجر أول بريد لك في دقائق.

إنشاء حساب →