وثائق API

واجهة برمجة تطبيقات GPTMail

استخدم واجهة GPTMail API لإنشاء صناديق بريد مؤقتة، وعرض الرسائل وقراءتها، وحذف البريد عبر HTTPS باستخدام ترويسة X-API-Key. وهي مناسبة للاختبارات الآلية وخطوط CI/CD ومسارات عمل ضمان الجودة (QA).

كيفية الحصول على API Key

Buy API requests

Purchase API requests with GPTMail points. Earn points through daily check-ins and public domains, or buy points with LDC at a 1:1 rate.

Buy with points / add requests

الخيار 2: إضافة نطاقك الخاص

بعد اجتياز النطاق العام التحقق من MX: التقديم دون تسجيل الدخول ← مفتاح API ‏(20000 طلب)؛ التقديم أثناء تسجيل الدخول ← 200 نقطة. يحصل كل نطاق على مكافأة واحدة فقط. مهم: بعد الربط، تصبح لاحقة ذلك النطاق لاحقة عامة متاحة لجميع مستخدمي هذا الموقع، فيمكن للمستخدمين الآخرين أيضًا إنشاء عناوين بريد تحتها. بعد التفعيل، لا تحذف ولا تستبدل ولا تعدّل سجل MX الذي يوجّه هذا النطاق إلى خدمتنا؛ وإلا قد تعامل الفحوصات اللاحقة مع النطاق على أنه مُعدّ بشكل خاطئ. إذا وجد فحص لاحق أن سجل MX غير صالح، يُعطّل النطاق. إذا بقي سجل MX غير صالح لمدة 3 فحوصات متتالية، تُعطّل API key المرتبطة أيضًا. إذا أصبح سجل MX صالحًا مرة أخرى لاحقًا، يُعاد تفعيل النطاق تلقائيًا.

النطاقات

مفتاح الاختبار العام

للاختبار، أرسل المفتاح العام المشترك المعروض أدناه في ترويسة X-API-Key. يتغير هذا المفتاح كل يوم، وله حد يومي قدره 200,000 طلب يتشاركه جميع المستخدمين.

المتبقي اليوم

يُعاد التعيين خلال

جاري تحميل الحصة المباشرة للمفتاح العام...

يمكن نسخ مرجع API أدناه كـ Markdown لأدوات الذكاء الاصطناعي أو قواعد المعرفة أو README.

عنوان URL الأساسي: https://mail.chatgpt.org.uk

AI
llms.txt

·

llms-full.txt

(Markdown)

البدء السريع

  • X-API-Key: YOUR_KEY هو الخيار الأبسط. للاختبارات السريعة، استخدم المفتاح العام اليومي المعروض أعلاه بدلًا من YOUR_KEY.

  • معظم نقاط صندوق البريد تتطلب معلمة email، مثل ?email=demo@example.com.

  • تستخدم استجابات GPTMail API صيغة JSON مع الحقول success وdata وerror، بالإضافة إلى usage عند استخدام مفتاح API. قد تُرجع أخطاء Cloudflare، بما فيها استجابات تجاوز حد معدل الطلبات، صفحة HTML بدلًا من ذلك. تحقّق من حالة HTTP وقيمة Content-Type قبل تحليل JSON.

  • إذا كنت تعرف بالفعل نطاقًا مدعومًا حاليًا على هذا الموقع، لا حاجة لاستدعاء نقطة إنشاء البريد أولًا. يمكنك تكوين prefix@domain محليًا واستدعاء واجهات صندوق البريد مباشرة، ما يوفر طلب API واحدًا.

حدود معدل الطلبات وإعادة المحاولة

  • تتشارك طلبات GET و POST /api/generate-email حدًّا قدره 30 طلبًا كل 10 ثوانٍ لكل عنوان IP مصدر. ينطبق ذلك على مفاتيح API العامة والشخصية. وتتشارك المفاتيح والعملاء المختلفون خلف عنوان IP نفسه هذا الحد.

  • يؤدي تجاوز هذا الحد إلى إرجاع HTTP 429 وحظر طلبات إنشاء عناوين البريد لمدة 10 ثوانٍ. انتظر المدة المحددة في Retry-After قبل إعادة المحاولة. إذا غاب هذا الترويس، فانتظر 10 ثوانٍ على الأقل، ثم أعد المحاولة بفواصل زمنية متزايدة. تجنب إعادة المحاولة في الوقت نفسه من عملاء يتشاركون عنوان IP واحدًا.

  • لا تنطبق هذه القاعدة على عرض قائمة الرسائل في صندوق الوارد أو قراءة رسالة منفردة. تظل الحصص اليومية والإجمالية لمفتاح API سارية بشكل مستقل. الانتظار 10 ثوانٍ لا يعيد حصة المفتاح بعد نفادها.

نقاط النهاية الأساسية

POST / GET
/api/generate-email

إنشاء صندوق بريد مؤقت. استخدم GET لأبسط تدفق لصندوق عشوائي، أو POST مع prefix وdomain عندما تريد تحكمًا صريحًا.

GET
/api/emails?email=...

جلب رسائل البريد لصندوق بريد.

GET
/api/email/{id}?email=...

جلب رسالة بريد واحدة، بما في ذلك النص وHTML والترويسات الخام والبيانات الوصفية.

DELETE
/api/email/{id}?email=...

حذف رسالة واحدة حسب المعرّف.

DELETE
/api/emails/clear?email=...

حذف جميع الرسائل في صندوق البريد.

GET
/api/stats

قراءة إحصائيات على مستوى الموقع.

مثال على التدفق

أدناه نمطان شائعان: اترك الخدمة تنشئ صندوق بريد لك، أو اطلب بادئة ثابتة. إذا كنت تعرف بالفعل نطاقًا مدعومًا حاليًا، يمكنك أيضًا تكوين صندوق البريد محليًا والاستعلام عنه مباشرة.

1) إنشاء عنوان بريد مؤقت عشوائي

curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: PUBLIC_API_KEY'
مثال على الاستجابة
{
  "success": true,
  "data": {
    "email": "a3f9c2b1@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

2) إنشاء ببادئة ثابتة (مثل demo@example.com)

curl -X POST 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: PUBLIC_API_KEY' \
  -d '{"prefix":"demo"}'
مثال على الاستجابة
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 2,
    "remaining_today": 199998
  }
}

3) عرض رسائل البريد في صندوق الوارد

إذا كنت تعرف نطاقًا مدعومًا، تخطَّ الخطوة 1 واستعلم مباشرة.

curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
مثال على الاستجابة
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "e5a7f3...",
        "email_address": "demo@example.com",
        "from_address": "noreply@github.com",
        "subject": "Your code: 654321",
        "content": "Your verification code is 654321",
        "html_content": "...",
        "has_html": true,
        "timestamp": 1709654321,
        "created_at": "2024-03-05T12:18:41Z"
      }
    ],
    "count": 1
  }
}

4) قراءة رسالة واحدة — يتضمن نصًا عاديًا وHTML والبيانات الوصفية

استبدل EMAIL_ID بمعرّف (id) أُعيد في الخطوة 3. ومرّر أيضًا عنوان صندوق البريد في المعلمة email (عند الحذف وتنزيل المرفقات أيضًا): عندئذٍ تُقرأ الرسالة مباشرةً من صندوقها بدلًا من البحث عنها بالمعرّف. عند استخدام مفتاح API تكون المعلمة email اختيارية، لكن إرسالها يجعل البحث أسرع.

curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
مثال على الاستجابة
{
  "success": true,
  "data": {
    "id": "e5a7f3...",
    "email_address": "demo@example.com",
    "from_address": "noreply@github.com",
    "subject": "Your code: 654321",
    "content": "Your verification code is 654321",
    "html_content": "<p>Your code is 654321</p>",
    "has_html": true,
    "timestamp": 1709654321,
    "raw_size": 2048,
    "created_at": "2024-03-05T12:18:41Z"
  }
}

5) حذف رسالة واحدة حسب المعرّف

عند استخدام مفتاح API تكون المعلمة email اختيارية، لكن إرسالها يجعل البحث أسرع.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
مثال على الاستجابة
{
  "success": true,
  "data": {
    "message": "Email deleted"
  }
}

6) إفراغ صندوق الوارد بالكامل — يحذف كل الرسائل لهذا العنوان

كل استدعاء يحذف دفعة واحدة. ما دامت الاستجابة تحتوي على "has_more": true، استدعِه مرة أخرى حتى يُرجع false.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/emails/clear?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
مثال على الاستجابة
{
  "success": true,
  "data": {
    "message": "Deleted 3 emails",
    "count": 3,
    "has_more": false
  }
}

شكل الاستجابة

تبدو الاستجابات الناجحة عادة هكذا. إذا صادقت باستخدام API key، انتبه لمعلومات الحصة داخل usage.

{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

إحصائيات موسعة

  • /api/statistics/24h يعيد نافذة توزيع بالساعة لمدة 24 ساعة؛ استخدم offset=1,2,... للنوافذ الأقدم.
  • /api/statistics/top-subjects يُرجع أكثر مواضيع الرسائل تكرارًا.
  • /api/statistics/top-domains يعيد أكثر النطاقات نشاطًا.
  • /api/statistics/top-senders يعيد أكثر المرسلين نشاطًا.
GPTMail