Mail Tạm Thời cung cấp REST API để tạo địa chỉ email tạm, đọc hộp thư và xem nội dung từng email.
Phù hợp cho: bot nhận OTP tự động, lưu test mail cho QA, hoặc bất kỳ workflow nào cần email dùng một lần.
Phiên bản này không dùng mật khẩu cho mailbox. Truy cập hộp thư bằng token (trả về khi tạo)
hoặc chỉ bằng chính địa chỉ email. Ai biết địa chỉ đều đọc được thư — chỉ dùng cho mục đích 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
Xác thực
Khi tạo mailbox hoặc gọi /api/mailbox/login,
server trả về một JWT token. Gửi kèm token ở header cho các endpoint cần xác thực:
Tạo mailbox mới trên một domain đang hoạt động. Phần tên (local part) luôn được sinh ngẫu nhiên — không thể tự chọn.
Response trả về địa chỉ email và một JWT token dùng được ngay.
import requests
r = requests.post('https://your-domain.com/api/mailbox/create', json={
'domain': 'yourdomain.com',
})
data = r.json()
print(data['email'])
token = data['token'] # dùng luôn, không cần login lại
POST
/api/mailbox/login
Lấy JWT token cho một địa chỉ. Chỉ cần email — không cần mật khẩu. Nếu địa chỉ chưa tồn tại thì server tự tạo
(miễn là domain đang hoạt động) rồi trả token luôn.
Use case: tạo mailbox tạm, dùng địa chỉ đó đi đăng ký dịch vụ, rồi script tự poll inbox và bắt mã OTP 6 số.
import requests, time, re
API = 'https://your-domain.com'
# 1. Tao mailbox moi (tra ve email + token)
r = requests.post(f'{API}/api/mailbox/create', json={'domain': 'yourdomain.com'})
data = r.json()
email, token = data['email'], data['token']
headers = {'Authorization': f'Bearer {token}'}
print('Mailbox:', email) # dung email nay di dang ky dich vu
# 2. Poll inbox cho toi khi co mail OTP (toi da 60s)
for _ in range(30):
messages = requests.get(f'{API}/api/mailbox/inbox', headers=headers).json()['messages']
for m in messages:
subject = (m['subject'] or '').lower()
if 'otp' in subject or 'verification' in subject or 'xac thuc' in subject:
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';
async function getOtp() {
// 1. Tao mailbox moi
const { email, token } = await fetch(`${API}/api/mailbox/create`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ domain: 'yourdomain.com' }),
}).then(r => r.json());
const auth = { Authorization: `Bearer ${token}` };
console.log('Mailbox:', email);
// 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 || '')) {
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 (vd domain không tồn tại)
401
Unauthorized
Thiếu/sai token, token hết hạn, hoặc email không tồn tại
404
Not Found
Email chưa tồn tại (login), hoặc message không thuộc mailbox của bạn
429
Too Many Requests
Vượt rate limit login (10 / 15 phút / IP)
Lưu ý quan trọng
Token hết hạn sau 7 ngày — cache và tái sử dụng. Khi nhận 401, gọi lại /login với email để 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 ra khi có mail mới đến.
Mọi message cũ hơn 1 ngày (24 giờ) bị xóa tự động, kể cả chưa đầy 20.
Địa chỉ mailbox được giữ 1 năm kể từ ngày tạo, sau đó bị xóa vĩnh viễn.
Không có mật khẩu: bất kỳ ai biết địa chỉ email đều đọc được inbox. Đừng dùng địa chỉ này cho thông tin nhạy cảm.
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.