Developer

API Documentation

v1 · REST · JSON

Tích hợp đọc Hotmail/Outlook vào tool của bạn qua REST API.

Base URL

https://getcode.khommo.vn

Authentication

API này miễn phí, không cần API key — ai cũng gọi được trực tiếp.

Giới hạn 60 request/phút cho mỗi IP để tránh lạm dụng. Nếu cần rate limit cao hơn, liên hệ Telegram @khommovn.

POST/api/v1/read-mailĐọc email Hotmail/Outlook

Request Body (JSON)

Field	Type	Required	Mô tả
email	string	Bắt buộc	Địa chỉ email Hotmail/Outlook
refreshToken	string	Bắt buộc	OAuth2 refresh token
clientId	string	Bắt buộc	Client ID của app Azure
mode	"imap" \| "graph"	Tuỳ chọn	Mặc định: "imap". Nếu "imap" báo lỗi kết nối hoặc không đọc được, thử lại với "graph".
server	"server1" \| "server2"	Tuỳ chọn	Backend ưu tiên thử trước. Mặc định: "server2". Nếu server được chọn lỗi, hệ thống tự thử server còn lại.
password	string	Tuỳ chọn	Mật khẩu tài khoản, nếu có — cải thiện độ chính xác khi đọc qua Server 2

Response

Field	Type	Mô tả
success	boolean	true nếu đọc mail thành công
messages	MailMessage[]	Danh sách email, mới nhất trước
error	string?	Mô tả lỗi nếu success = false

MailMessage object

Field	Type	Mô tả
id	string	ID email
from	string	Người gửi: "Name <email>"
subject	string	Tiêu đề email
receivedAt	string	Thời gian nhận (ISO 8601)
snippet	string	Đoạn preview nội dung (≤200 ký tự)
body	string	Nội dung đầy đủ (có thể là HTML)
extractedCode	ExtractedCode?	Mã OTP/code tự động nhận diện

Response Example

{
  "success": true,
  "messages": [
    {
      "id": "1234",
      "from": "Microsoft <account-security-noreply@accountprotection.microsoft.com>",
      "subject": "Mã xác minh Microsoft của bạn",
      "receivedAt": "2025-05-27T10:30:00Z",
      "snippet": "Dùng mã xác minh này 847291...",
      "body": "<html>...</html>",
      "extractedCode": {
        "code": "847291",
        "confidence": "high",
        "source": "body",
        "matchedKeyword": "auto-detected"
      }
    }
  ]
}

Code Examples

cURL

curl -X POST https://getcode.khommo.vn/api/v1/read-mail \
  -H "Content-Type: application/json" \
  -d '{
    "email": "yourmail@hotmail.com",
    "refreshToken": "M.C...",
    "clientId": "04b07795-...",
    "mode": "imap",
    "server": "server2"
  }'

JavaScript (fetch)

const res = await fetch('https://getcode.khommo.vn/api/v1/read-mail', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'yourmail@hotmail.com',
    refreshToken: 'M.C...',
    clientId: '04b07795-...',
    mode: 'imap',
    server: 'server2', // 'server1' | 'server2' — mặc định 'server2', tự fallback nếu lỗi
  }),
})

const data = await res.json()
if (data.success) {
  console.log(data.messages[0]?.extractedCode?.code)
} else {
  // 'imap' bị lỗi kết nối hoặc không đọc được? thử lại với mode: 'graph'
  console.error(data.error)
}

Python (requests)

import requests

resp = requests.post(
    'https://getcode.khommo.vn/api/v1/read-mail',
    json={
        'email': 'yourmail@hotmail.com',
        'refreshToken': 'M.C...',
        'clientId': '04b07795-...',
        'mode': 'imap',
        'server': 'server2',  # 'server1' | 'server2' — mặc định 'server2', tự fallback nếu lỗi
    },
    timeout=20,
)

data = resp.json()
if data['success']:
    print(data['messages'][0]['extractedCode']['code'])
else:
    # 'imap' bị lỗi kết nối hoặc không đọc được? thử lại với mode: 'graph'
    print(data['error'])

Error Codes

HTTP Status	Code	Mô tả
400	Bad Request	Thiếu email / refreshToken / clientId
429	Too Many Requests	Vượt rate limit
502	Bad Gateway	Không đọc được mail — xem field "error" để biết lý do cụ thể

Lưu ý

·API không lưu email, refreshToken hay nội dung mail. Chỉ đếm lượt gọi cho thống kê.
·Timeout mặc định 15 giây mỗi request.
·Nếu mode=imap lỗi kết nối hoặc không đọc được, thử lại với mode=graph. Mọi lỗi đều được trả về rõ ràng trong field error, không bao giờ trả về thành công giả.
·Có 2 server đọc mail độc lập, mặc định dùng server2. Bạn có thể chỉ định server: "server1" nếu muốn ưu tiên server còn lại — nếu server được chọn lỗi, hệ thống tự động thử server kia trước khi trả lỗi.