Tài liệu API

API GPTMail

Dùng GPTMail API để tạo hộp thư tạm thời, liệt kê và đọc thư, cũng như xóa thư qua HTTPS với header X-API-Key. API phù hợp cho kiểm thử tự động, pipeline CI/CD và quy trình QA.

Cách lấy 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

Tuỳ chọn 2: Thêm domain của bạn

Sau khi tên miền công khai vượt qua xác minh MX: gửi khi chưa đăng nhập → khóa API (20000 yêu cầu); gửi khi đã đăng nhập → 200 điểm. Mỗi tên miền chỉ nhận một phần thưởng. Quan trọng: sau khi kết nối, hậu tố domain đó trở thành public suffix dùng chung cho mọi người dùng trên site, nên người khác cũng có thể tạo địa chỉ mailbox dưới hậu tố đó. Sau khi kích hoạt, đừng xoá, thay thế hay sửa bản ghi MX trỏ domain này tới dịch vụ của chúng tôi; nếu không, các lần kiểm tra sau có thể coi domain bị cấu hình sai. Nếu lần kiểm tra sau thấy MX không hợp lệ, domain sẽ bị vô hiệu hoá. Nếu MX không hợp lệ trong 3 lần kiểm tra liên tiếp, API key liên quan cũng bị vô hiệu hoá. Nếu MX hợp lệ trở lại sau đó, domain sẽ được kích hoạt lại tự động.

Tên miền

Khóa kiểm thử công khai

Để kiểm thử, hãy gửi khóa công khai dùng chung hiển thị bên dưới trong header X-API-Key. Khóa này thay đổi mỗi ngày và có giới hạn 200.000 yêu cầu mỗi ngày, dùng chung cho tất cả người dùng.

Còn lại hôm nay

Sẽ reset sau

Đang tải quota trực tiếp cho public key...

Tham chiếu API bên dưới có thể sao chép dạng Markdown cho công cụ AI, kho kiến thức hoặc README.

URL cơ sở: https://mail.chatgpt.org.uk

AI
llms.txt

·

llms-full.txt

(Markdown)

Bắt đầu nhanh

  • X-API-Key: YOUR_KEY là cách đơn giản nhất. Để kiểm thử nhanh, hãy dùng khóa công khai hằng ngày hiển thị ở trên thay cho YOUR_KEY.

  • Hầu hết endpoint mailbox cần tham số email, ví dụ ?email=demo@example.com.

  • Phản hồi của GPTMail API dùng JSON với các trường success, data và error, cùng usage khi dùng khóa API. Lỗi Cloudflare, kể cả phản hồi khi vượt giới hạn tốc độ, có thể trả về HTML. Hãy kiểm tra mã trạng thái HTTP và Content-Type trước khi phân tích JSON.

  • Nếu bạn đã biết domain đang được hỗ trợ trên site, không cần gọi endpoint tạo email trước. Bạn có thể ghép prefix@domain cục bộ và gọi mailbox APIs trực tiếp, tiết kiệm một API request.

Giới hạn tốc độ và thử lại

  • GET và POST /api/generate-email dùng chung giới hạn 30 yêu cầu mỗi 10 giây cho mỗi IP nguồn. Giới hạn này áp dụng cho cả khóa API công khai và khóa cá nhân. Các khóa và client khác nhau dùng chung một IP sẽ chia sẻ giới hạn này.

  • Vượt quá giới hạn này sẽ trả về HTTP 429 và chặn việc tạo email trong 10 giây. Hãy đợi hết thời gian Retry-After trước khi thử lại. Nếu không có header này, hãy đợi ít nhất 10 giây rồi thử lại với khoảng chờ tăng dần. Tránh để các client dùng chung một IP thử lại cùng lúc.

  • Quy tắc này không áp dụng cho việc liệt kê hộp thư hoặc đọc từng email. Hạn mức hằng ngày và tổng hạn mức của khóa API vẫn áp dụng độc lập. Đợi 10 giây không khôi phục hạn mức đã dùng hết của khóa.

Endpoints cốt lõi

POST / GET
/api/generate-email

Tạo hộp thư tạm thời. Dùng GET cho luồng inbox ngẫu nhiên đơn giản nhất, hoặc POST với prefix và domain khi bạn muốn kiểm soát rõ ràng.

GET
/api/emails?email=...

Lấy email cho một mailbox.

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

Lấy một email, gồm văn bản, HTML, header thô và metadata.

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

DELETE một email theo ID.

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

DELETE mọi email trong mailbox.

GET
/api/stats

Đọc thống kê toàn site.

Luồng ví dụ

Dưới đây là hai mẫu phổ biến: để dịch vụ tạo inbox cho bạn, hoặc yêu cầu prefix cố định. Nếu bạn đã biết domain đang được hỗ trợ, bạn cũng có thể ghép mailbox cục bộ và truy vấn trực tiếp.

1) Tạo địa chỉ email tạm ngẫu nhiên

curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ví dụ phản hồi
{
  "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) Tạo với prefix cố định (ví dụ 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"}'
Ví dụ phản hồi
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 2,
    "remaining_today": 199998
  }
}

3) Liệt kê email trong inbox

Nếu biết domain được hỗ trợ, bỏ qua bước 1 và truy vấn trực tiếp.

curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ví dụ phản hồi
{
  "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) Đọc một email — gồm văn bản thuần, thân HTML và metadata

Thay EMAIL_ID bằng id trả về ở bước 3. Hãy truyền thêm địa chỉ hộp thư dưới dạng email (kể cả khi xóa thư và tải tệp đính kèm): khi đó email được đọc trực tiếp từ hộp thư của nó thay vì được tìm theo ID. Khi có khóa API, tham số email là tùy chọn, nhưng gửi kèm sẽ giúp tra cứu nhanh hơn.

curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ví dụ phản hồi
{
  "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) DELETE một email theo ID

Khi có khóa API, tham số email là tùy chọn, nhưng gửi kèm sẽ giúp tra cứu nhanh hơn.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ví dụ phản hồi
{
  "success": true,
  "data": {
    "message": "Email deleted"
  }
}

6) Xoá sạch inbox — xoá mọi email của địa chỉ này

Mỗi lần gọi xóa một lô. Khi phản hồi còn "has_more": true, hãy gọi lại cho đến khi trả về false.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/emails/clear?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ví dụ phản hồi
{
  "success": true,
  "data": {
    "message": "Deleted 3 emails",
    "count": 3,
    "has_more": false
  }
}

Cấu trúc phản hồi

Phản hồi thành công thường trông như sau. Nếu xác thực bằng API Key, chú ý thông tin quota trong 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
  }
}

Thống kê mở rộng

  • /api/statistics/24h trả về một khung phân bố theo giờ dài 24 giờ; dùng offset=1,2,... cho các khung cũ hơn.
  • /api/statistics/top-subjects trả về các tiêu đề email phổ biến nhất.
  • /api/statistics/top-domains trả về các domains hoạt động nhất.
  • /api/statistics/top-senders trả về các senders hoạt động nhất.
GPTMail