مستندات API

API GPTMail

با API سرویس GPTMail می‌توانید از طریق HTTPS و با سرآیند X-API-Key صندوق‌های ورودی موقت بسازید، پیام‌ها را فهرست کنید و بخوانید و ایمیل‌ها را حذف کنید. این API برای آزمون‌های خودکار، خطوط 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

گزینه ۲: افزودن دامنهٔ خود

پس از تأیید MX دامنهٔ عمومی: ثبت بدون ورود به حساب ← کلید API ‏(20000 درخواست)؛ ثبت در حالت واردشده ← 200 امتیاز. هر دامنه فقط یک پاداش می‌گیرد. مهم: پس از اتصال، پسوند آن دامنه به‌صورت public suffix در دسترس همهٔ کاربران این سایت است و دیگران هم می‌توانند زیر آن آدرس بسازند. پس از فعال‌سازی، رکورد MX که این دامنه را به سرویس ما نشان می‌دهد را حذف، جایگزین یا تغییر ندهید؛ در غیر این صورت بررسی‌های بعدی ممکن است دامنه را misconfigured ببیند. اگر در بررسی بعدی MX نامعتبر باشد، دامنه غیرفعال می‌شود. اگر MX برای 3 بررسی پیاپی نامعتبر بماند، API key مرتبط هم غیرفعال می‌شود. اگر بعداً MX دوباره معتبر شود، دامنه به‌طور خودکار فعال می‌گردد.

دامنه‌ها

کلید عمومی آزمایشی

برای آزمایش، کلید عمومی مشترکی را که در زیر نمایش داده شده است در سرآیند X-API-Key ارسال کنید. این کلید هر روز تغییر می‌کند و سقف روزانهٔ آن 200,000 درخواست است که میان همهٔ کاربران مشترک است.

باقی‌مانده امروز

زمان تا ریست

در حال بارگذاری سهمیهٔ زنده برای کلید عمومی...

مرجع API زیر را می‌توان به‌صورت Markdown برای ابزارهای AI، پایگاه دانش یا README کپی کرد.

آدرس پایه API: https://mail.chatgpt.org.uk

AI
llms.txt

·

llms-full.txt

(Markdown)

شروع سریع

  • X-API-Key: YOUR_KEY ساده‌ترین گزینه است. برای آزمایش سریع، کلید عمومی روزانه‌ای را که در بالا نمایش داده شده است به‌جای YOUR_KEY به کار ببرید.

  • بیشتر نقاط صندوق به پارامتر email نیاز دارند، مثلاً ?email=demo@example.com.

  • پاسخ‌های API سرویس GPTMail از JSON با فیلدهای success، data و error استفاده می‌کنند و هنگام استفاده از کلید API، فیلد usage نیز دارند. خطاهای Cloudflare، از جمله پاسخ‌های محدودیت نرخ، ممکن است به‌جای آن HTML برگردانند. پیش از تجزیهٔ JSON، وضعیت HTTP و Content-Type را بررسی کنید.

  • اگر دامنهٔ پشتیبانی‌شدهٔ فعلی را می‌دانید، لازم نیست ابتدا endpoint ساخت email را صدا بزنید؛ می‌توانید prefix@domain را محلی بسازید و مستقیماً APIهای صندوق را بزنید و یک درخواست 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=...

حذف یک ایمیل با ID.

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

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

GET
/api/stats

خواندن آمار در سطح کل سایت.

جریان نمونه

دو الگوی رایج در زیر است: بگذارید سرویس برایتان صندوق بسازد، یا پیشوند ثابت بخواهید. اگر هم‌اکنون دامنهٔ پشتیبانی‌شده را می‌دانید، می‌توانید صندوق را به‌صورت محلی بسازید و مستقیماً query بزنید.

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) فهرست ایمیل‌ها در inbox

اگر دامنهٔ پشتیبانی‌شده را می‌دانید، گام ۱ را رد کنید و مستقیماً query بزنید.

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 ارسال کنید (برای حذف و دانلود پیوست‌ها نیز): در این صورت ایمیل مستقیماً از صندوق خودش خوانده می‌شود و نیازی به جست‌وجو بر اساس ID نیست. با کلید 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) حذف یک ایمیل با ID

با کلید 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) خالی کردن کل inbox — همهٔ ایمیل‌های این آدرس حذف می‌شود

هر فراخوانی یک دسته را حذف می‌کند. تا زمانی که پاسخ شامل "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