Giới thiệu
Emails DichVuGame cung cấp REST API cho phép bạn đăng nhập mailbox, đọc hộp thư, và xem nội dung từng email. Phù hợp cho các use case như: bot xác thực OTP tự động, lưu trữ test mail cho QA, hoặc bất kỳ workflow nào cần một địa chỉ email tạm thời.
Base URL
https://your-domain.com
Format
JSON
Token TTL
7 ngày
Rate limit login
10 / 15 phút / IP
Authentication
Sau khi gọi /api/mailbox/login, server trả về một JWT token.
Gửi kèm token ở header Authorization cho các endpoint cần auth:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
Một số endpoint (như /api/mailbox/inbox) cũng chấp nhận
email + password trong JSON body để các client đơn giản không cần login bước riêng.
POST
/api/mailbox/login
Đăng nhập vào mailbox để lấy JWT token.
Request body
{
"email": "abc123@yourdomain.com",
"password": "your-password"
}
Response — 200 OK
{
"email": "abc123@yourdomain.com",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}
Ví dụ
curl -X POST https://your-domain.com/api/mailbox/login \
-H "Content-Type: application/json" \
-d '{"email":"abc123@yourdomain.com","password":"your-password"}'
const res = await fetch('https://your-domain.com/api/mailbox/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'abc123@yourdomain.com',
password: 'your-password',
}),
});
const { token } = await res.json();
import requests
r = requests.post('https://your-domain.com/api/mailbox/login', json={
'email': 'abc123@yourdomain.com',
'password': 'your-password',
})
token = r.json()['token']
GET
/api/mailbox/inbox
Trả về danh sách tối đa 20 message gần nhất. Không bao gồm body để response nhẹ — gọi /api/mailbox/message/:id để lấy nội dung.
Headers
Authorization: Bearer <token>
Hoặc dùng POST với email/password trong body (không cần login bước riêng):
{
"email": "abc123@yourdomain.com",
"password": "your-password"
}
Response — 200 OK
{
"email": "abc123@yourdomain.com",
"messages": [
{
"id": 42,
"from_addr": "noreply@shop.com",
"from_name": "Shop ABC",
"subject": "Mã xác thực của bạn là 123456",
"received_at": 1775638000000
},
{
"id": 41,
"from_addr": "team@service.io",
"from_name": "Service Team",
"subject": "Welcome!",
"received_at": 1775637000000
}
]
}
Schema
| Field | Kiểu | Mô tả |
|---|---|---|
| id | number | ID message, dùng cho endpoint đọc chi tiết |
| from_addr | string | Email người gửi |
| from_name | string | Tên hiển thị (có thể rỗng) |
| subject | string | Tiêu đề email |
| received_at | number | Unix timestamp (ms) |
Ví dụ
curl https://your-domain.com/api/mailbox/inbox \
-H "Authorization: Bearer eyJhbGciOi..."
const res = await fetch('https://your-domain.com/api/mailbox/inbox', {
headers: { Authorization: 'Bearer ' + token },
});
const { messages } = await res.json();
r = requests.get(
'https://your-domain.com/api/mailbox/inbox',
headers={'Authorization': f'Bearer {token}'},
)
messages = r.json()['messages']
GET
/api/mailbox/message/:id
Lấy full nội dung của một email cụ thể, bao gồm cả text và HTML body.
URL params
id— ID message từ inbox
Response — 200 OK
{
"id": 42,
"mailbox_id": 7,
"from_addr": "noreply@shop.com",
"from_name": "Shop ABC",
"subject": "Mã xác thực của bạn là 123456",
"text_body": "Ma xac thuc: 123456\nCo hieu luc trong 5 phut.",
"html_body": "<!doctype html><html><body><h2>OTP: <b>123456</b></h2></body></html>",
"size_bytes": 512,
"received_at": 1775638000000
}
Schema
| Field | Kiểu | Mô tả |
|---|---|---|
| id | number | ID message |
| from_addr | string | Email người gửi |
| from_name | string | Tên người gửi |
| subject | string | Tiêu đề |
| text_body | string | Phần text thuần |
| html_body | string | Phần HTML đầy đủ |
| size_bytes | number | Kích thước nội dung (bytes) |
| received_at | number | Unix timestamp (ms) |
Ví dụ
curl https://your-domain.com/api/mailbox/message/42 \
-H "Authorization: Bearer eyJhbGciOi..."
const res = await fetch('https://your-domain.com/api/mailbox/message/42', {
headers: { Authorization: 'Bearer ' + token },
});
const msg = await res.json();
console.log(msg.subject, msg.text_body);
r = requests.get(
f'https://your-domain.com/api/mailbox/message/{message_id}',
headers={'Authorization': f'Bearer {token}'},
)
msg = r.json()
print(msg['subject'])
print(msg['text_body'])
POST
/api/mailbox/change-password
Đổi mật khẩu mailbox. Yêu cầu cả mật khẩu hiện tại để xác minh.
Request body
{
"current_password": "your-current-password",
"new_password": "your-new-password"
}
Response — 200 OK
{ "ok": true }
Ví dụ — cURL
curl -X POST https://your-domain.com/api/mailbox/change-password \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"current_password":"old123","new_password":"newStrong456"}'
Ví dụ đầy đủ — bot lấy OTP tự động
Use case: đăng ký dịch vụ với mailbox tạm thời, script tự động poll inbox và parse mã OTP 6 số từ mail xác thực.
import requests, time, re
API = 'https://your-domain.com'
EMAIL = 'otp-bot@yourdomain.com'
PASSWORD = 'your-password'
# 1. Login
r = requests.post(f'{API}/api/mailbox/login',
json={'email': EMAIL, 'password': PASSWORD})
token = r.json()['token']
headers = {'Authorization': f'Bearer {token}'}
# 2. Poll inbox cho tới khi co mail OTP (toi da 60s)
print('Waiting for OTP mail...')
for _ in range(30):
r = requests.get(f'{API}/api/mailbox/inbox', headers=headers)
messages = r.json()['messages']
for m in messages:
subject = (m['subject'] or '').lower()
if 'otp' in subject or 'verification' in subject or 'xac thuc' in subject:
# 3. Doc full noi dung
full = requests.get(
f'{API}/api/mailbox/message/{m["id"]}',
headers=headers,
).json()
body = (full.get('text_body') or '') + (full.get('html_body') or '')
match = re.search(r'\b(\d{6})\b', body)
if match:
print('OTP:', match.group(1))
exit()
time.sleep(2)
print('Timeout: no OTP found')
const API = 'https://your-domain.com';
const EMAIL = 'otp-bot@yourdomain.com';
const PASSWORD = 'your-password';
async function getOtp() {
// 1. Login
const loginRes = await fetch(`${API}/api/mailbox/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
});
const { token } = await loginRes.json();
const auth = { Authorization: `Bearer ${token}` };
// 2. Poll inbox toi da 60s
for (let i = 0; i < 30; i++) {
const { messages } = await fetch(`${API}/api/mailbox/inbox`, { headers: auth })
.then(r => r.json());
for (const m of messages) {
if (/otp|verification|xac thuc/i.test(m.subject || '')) {
// 3. Doc full noi dung
const full = await fetch(`${API}/api/mailbox/message/${m.id}`, { headers: auth })
.then(r => r.json());
const body = (full.text_body || '') + (full.html_body || '');
const match = body.match(/\b(\d{6})\b/);
if (match) return match[1];
}
}
await new Promise(r => setTimeout(r, 2000));
}
throw new Error('No OTP received');
}
getOtp().then(console.log).catch(console.error);
Mã lỗi
| Code | Ý nghĩa | Khi nào |
|---|---|---|
| 200 | OK | Request thành công |
| 400 | Bad Request | Thiếu field hoặc dữ liệu sai format |
| 401 | Unauthorized | Sai mật khẩu, token hết hạn, hoặc thiếu Authorization header |
| 403 | Forbidden | Không có quyền (ví dụ tạo mailbox từ IP không whitelist) |
| 404 | Not Found | Message không tồn tại hoặc không thuộc mailbox của bạn |
| 429 | Too Many Requests | Vượt rate limit (10 login / 15 phút / IP) |
Lưu ý quan trọng
Token hết hạn 7 ngày — cache và tái sử dụng. Khi nhận 401, login lại để lấy token mới.
Chính sách lưu trữ:
- Mỗi mailbox chỉ giữ tối đa 20 message gần nhất — mail cũ bị đẩy khỏi hộp khi có mail mới đến.
- Mọi message cũ hơn 1 ngày (24 giờ) sẽ bị xóa tự động, kể cả chưa đầy 20.
- Tài khoản mailbox (email + password) được giữ 1 năm kể từ ngày tạo, sau đó sẽ bị xóa vĩnh viễn.
Cần gọi nhiều lần? Yêu cầu admin thêm IP của bot vào IP whitelist để bypass rate limit hoàn toàn.