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

Mọi request cần kèm header X-API-Key.

X-API-Key: rmh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Để lấy API key, liên hệ qua Telegram @khommovn. Key có dạng rmh_... và giới hạn mặc định 100 request/phút.

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"

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" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "email": "yourmail@hotmail.com",
    "refreshToken": "M.C...",
    "clientId": "04b07795-...",
    "mode": "imap"
  }'

JavaScript (fetch)

const res = await fetch('https://getcode.khommo.vn/api/v1/read-mail', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    email: 'yourmail@hotmail.com',
    refreshToken: 'M.C...',
    clientId: '04b07795-...',
    mode: 'imap',
  }),
})

const data = await res.json()
if (data.success) {
  console.log(data.messages[0]?.extractedCode?.code)
}

Python (requests)

import requests

resp = requests.post(
    'https://getcode.khommo.vn/api/v1/read-mail',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
    },
    json={
        'email': 'yourmail@hotmail.com',
        'refreshToken': 'M.C...',
        'clientId': '04b07795-...',
        'mode': 'imap',
    },
    timeout=20,
)

data = resp.json()
if data['success']:
    print(data['messages'][0]['extractedCode']['code'])

Error Codes

HTTP Status	Code	Mô tả
401	Unauthorized	Thiếu hoặc sai X-API-Key
400	Bad Request	Thiếu email / refreshToken / clientId
429	Too Many Requests	Vượt rate limit
502	Bad Gateway	Không đọc được mail từ server

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 thất bại, thử lại với mode=graph.
·API key không được chia sẻ công khai. Mỗi key có rate limit riêng (mặc định 100 req/phút).