TempMail MMO - Tài liệu API

Bắt đầu nhanh #

Luồng tích hợp chuẩn từ tạo mailbox đến đọc thư và tải tệp đính kèm.

Lấy danh sách domain GET /tool/ajax.php?f=get_domains
Tạo session và email tạm POST /tool/ajax.php?f=get_email_address
Tùy chỉnh username/domain Tùy chọn POST /tool/ajax.php?f=set_email_user
Mở lại mailbox cũ Tùy chọn POST /tool/ajax.php?f=open_email_address
Polling danh sách thư POST /tool/ajax.php?f=get_email_list mỗi 15 giây, backoff khi nhận 429/503.
Đọc chi tiết thư POST /tool/ajax.php?f=fetch_email
Tải tệp đính kèm POST /tool/ajax.php?f=fetch_attachment

Xác thực phiên #

Sau khi get_email_address thành công, response trả về sid_token — bắt buộc cho mọi action mailbox. Các response kèm ngữ cảnh session cũng có metadata phiên để client theo dõi hạn dùng.

Bảo mật: gửi sid_token trong tham số body, không truyền trên query string URL.

Trường xác thực
Trường	Bắt buộc	Mô tả
sid_token	Có	Chuỗi 48 ký tự hex đại diện cho session đang hoạt động.
lang	Không	Ngôn ngữ gợi ý, hỗ trợ `vi` hoặc `en`.

Session meta trong JSON response
Trường	Kiểu	Mô tả
session_started_at	number	Unix timestamp (mili giây) thời điểm session được tạo.
session_expires_at	number	Unix timestamp (mili giây) thời điểm session hiện tại sẽ hết hạn.
session_ttl_minutes	number	TTL cấu hình của session theo phút (mặc định 180, tùy cấu hình máy chủ).
welcome_created_at	number	Unix timestamp (mili giây) email chào mừng được tạo cho mailbox hiện tại (0 nếu chưa có).

Các action mailbox (get_email_list, fetch_email, del_email, fetch_attachment) gửi session meta mới nhất qua response header.

Response header
Header	Kiểu	Mô tả
X-Session-Started-At	number	Unix timestamp (mili giây) thời điểm session được tạo.
X-Welcome-Created-At	number	Unix timestamp (mili giây) email chào mừng được tạo (0 nếu chưa có).
X-Session-Expires-At	number	Unix timestamp (mili giây) thời điểm session được gia hạn gần nhất sẽ hết hạn.
X-Session-Ttl-Minutes	number	TTL session theo phút.

Mailbox Events #

Luồng SSE dành cho website hoặc cấu hình riêng có bật mailbox events. Process tool tại /tool/ajax.php không bật SSE — tool client nên dùng get_email_list polling 15 giây.

GET SSE /events/mailbox?token=MAILBOX_EVENT_TOKEN

Trước khi kết nối, gọi POST /ajax.php?f=get_mailbox_event_token (kèm sid_token trong body) để lấy token opaque 256-bit, scope mailbox:events, TTL 5–10 phút.

Response của get_mailbox_event_token

email_addr sid_token session_started_at welcome_created_at session_expires_at session_ttl_minutes mailbox_event_token mailbox_event_token_scope mailbox_event_token_expires_at

Chuẩn Server-Sent Events; client tự reconnect theo retry: 2000.

Tham số query
Tham số	Bắt buộc	Mô tả
token	Có	`mailbox_event_token` Token của session mailbox hiện tại.

Danh sách event
Event	Khi nào gửi	Payload chính
state	Khi vừa kết nối hoặc khi watcher đổi trạng thái.	`ok` `email` `connected` `count` `connected_folders` `watched_folders` `folders` `ts` Tùy chọn: `error`, `token_expires_at` (event state đầu tiên sau khi kết nối).
changed	Khi mailbox có thay đổi số lượng thư hoặc có thư mới.	`email` `reason` `connected` `count` `total_count` `connected_folders` `ts` Tùy chọn: `prevCount` `folder` `path`
ping	Keepalive định kỳ để giữ stream hoạt động.	Giống `state`, thêm `ping: true`.
session_lost	Khi session hết hạn hoặc token không còn khớp mailbox hiện tại.	`email` `ts`
token_expiring	Khi token SSE sắp hết hạn và client nên lấy token mới.	`email` `expires_at` `ts`
token_expired	Khi token đã hết hạn hoặc bị thu hồi do rotate/đổi mailbox.	`email` `ts`

Khuyến nghị: chỉ gọi get_email_list khi vừa mở mailbox, khi nhận event changed, hoặc khi SSE lỗi/không khả dụng.

Bảo mật: token là credential tạm thời — chỉ dùng qua HTTPS, không gửi full URL vào analytics. Token không thể đọc/xóa mail và bị rotate khi đổi mailbox, takeover, session rotation hoặc hết phiên.

Lỗi thường gặp: 401 token không hợp lệ/session mất, 429 quá nhiều kết nối SSE cùng IP, 503 server event đầy tải.

Lấy danh sách domain #

Danh sách domain khả dụng, domain mặc định và thời điểm cập nhật catalog.

GET /tool/ajax.php?f=get_domains

Schema response
Trường	Kiểu	Mô tả
domains	string[]	Danh sách domain khả dụng.
defaultDomain	string	Domain mặc định được chọn khi không chỉ định domain.
domains_updated_at	number	Unix timestamp (mili giây) của lần đồng bộ catalog domain gần nhất.
domain_expiry_lookup_enabled	boolean	Cờ bật/tắt kiểm tra hạn domain (WHOIS/RDAP).
domain_expiry_source	string	Nguồn dữ liệu hạn domain, ví dụ `rdap` hoặc `whois`.
domain_expiry_checked_at	number	Unix timestamp (mili giây) lần kiểm tra hạn domain gần nhất.
domain_expiry_warning_days	number	Số ngày cảnh báo trước khi domain hết hạn.
delete_data_on_domain_expiry	boolean	Có tự xóa dữ liệu mailbox khi domain hết hạn hay không.
domain_expiry_statuses	object[]	Trạng thái hạn của từng domain (chỉ khi bật lookup).
domain_expiry_alerts	object[]	Danh sách cảnh báo domain sắp/nhận hết hạn.

Kiểm tra hạn domain #

Trạng thái hạn của một domain hoặc toàn bộ catalog domain.

GET /tool/ajax.php?f=get_domain_expiry

Tham số query
Tham số	Bắt buộc	Mô tả
domain	Không	Domain cần tra cứu. Bỏ trống để lấy trạng thái toàn bộ catalog.
force	Không	`1` để bỏ qua cache và tra cứu mới.

Schema response
Trường	Kiểu	Mô tả
domain	string	Domain được tra cứu (chỉ khi gửi `domain`).
domain_expiry_lookup_enabled / domain_expiry_source / domain_expiry_warning_days / delete_data_on_domain_expiry	mixed	Cấu hình expiry hiện tại. Xem get_domains.
expires_at / lookup_status / message	mixed	Trạng thái hạn của domain (khi tra cứu 1 domain).
alerts / statuses	object[]	Cảnh báo và trạng thái từng domain (khi bỏ trống `domain`).

Tạo mailbox tạm hoặc lấy lại session #

Tạo mailbox mới, hoặc lấy lại session nếu gửi sid_token hợp lệ trong body.

POST /tool/ajax.php?f=get_email_address

Response kèm catalog domain hiện tại để client đồng bộ mà không cần gọi riêng get_domains.

Lưu ý: sid_token chỉ đại diện phiên truy cập tạm. Khi phiên hết hạn, mailbox vẫn có thể mở lại bằng open_email_address nếu còn tồn tại trên máy chủ.

Tham số body
Tham số	Bắt buộc	Mô tả
email_domain	Không	Domain mong muốn, nếu không có sẽ dùng `defaultDomain`.
lang	Không	Ngôn ngữ phiên, ví dụ `vi` hoặc `en`.
sid_token	Không	Gửi token cũ trong tham số body để lấy lại phiên nếu còn hiệu lực.
request_id	Không	Idempotency key 16-128 ký tự (`A-Za-z0-9_-`). Retry với cùng `request_id` trả về mailbox đã tạo, tránh tạo trùng.

Schema response
Trường	Kiểu	Mô tả
email_addr	string	Địa chỉ email đầy đủ `local@domain`.
email_user	string	Phần local-part của email.
email_domain	string	Domain hiện tại của phiên.
sid_token	string (48 hex)	Token phiên dùng cho các action mailbox.
alias	number	Cờ tương thích, hiện trả 0.
session_started_at / welcome_created_at / session_expires_at / session_ttl_minutes	number	Nhóm session meta chuẩn. Xem mục Xác thực phiên.
list / count / list_source / list_cached_at	mixed	Danh sách thư cache (nếu có): `list_source` là `live`, `cache` hoặc `stale`; `list_cached_at` là timestamp bản cache.
domains / defaultDomain / domains_updated_at	mixed	Catalog domain mới nhất. Xem get_domains.

Đặt username/domain theo ý muốn #

Cập nhật địa chỉ email theo username và domain cho session hiện tại.

POST /tool/ajax.php?f=set_email_user

Nếu bật force_takeover và email mục tiêu đang do session khác giữ: session cũ bị thu hồi, sid_token được rotate (token cũ chết ngay) và response trả về session mới giữ mailbox đó.

Tham số body
Tham số	Bắt buộc	Mô tả
sid_token	Có	Token phiên đang hoạt động.
email_user	Có	Username 3-64 ký tự, chỉ gồm `a-z`, `0-9`, dấu chấm, gạch dưới, gạch ngang.
email_domain	Không	Domain mục tiêu. Nếu không hợp lệ sẽ dùng domain mặc định.
force_takeover	Không	`1/true` để takeover email mục tiêu nếu email đó đang bị session khác giữ.
create_only	Không	`1/true` để chỉ cho phép đặt email mới (chưa tồn tại). Email đã tồn tại trả `409 EMAIL_ADDRESS_EXISTS`.
lang	Không	Ngôn ngữ phiên, hỗ trợ `vi` hoặc `en`.

Schema response
Trường	Kiểu	Mô tả
email_addr	string	Địa chỉ email mới sau khi cập nhật.
email_user	string	Username hiện tại.
email_domain	string	Domain hiện tại.
sid_token	string (48 hex)	Token phiên giữ nguyên.
alias	number	Cờ tương thích, hiện trả 0.
session_started_at / welcome_created_at / session_expires_at / session_ttl_minutes	number	Nhóm session meta chuẩn. Xem mục Xác thực phiên.
list / count / list_source / list_cached_at	mixed	Danh sách thư cache (nếu có). Xem get_email_address.
domains / defaultDomain / domains_updated_at	mixed	Catalog domain mới nhất. Xem get_domains.

Response 200

{
  "email_addr": "custom_name@tempmailmmo.com",
  "email_user": "custom_name",
  "email_domain": "tempmailmmo.com",
  "sid_token": "0123456789abcdef0123456789abcdef0123456789abcdef",
  "alias": 0,
  "session_started_at": 1710000000000,
  "welcome_created_at": 1710000000000,
  "session_expires_at": 1710108000000,
  "session_ttl_minutes": 180,
  "domains": ["mailmmo.io.vn", "tempmailmmo.com"],
  "defaultDomain": "tempmailmmo.com",
  "domains_updated_at": 1710000000000
}

cURL

curl -X POST "https://your-domain.com/tool/ajax.php?f=set_email_user" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "sid_token=YOUR_SID_TOKEN&email_user=custom_name&email_domain=tempmailmmo.com"

Mở lại mailbox cũ đã tồn tại #

Mở lại mailbox cũ theo địa chỉ đầy đủ local@domain để đọc thư.

POST /tool/ajax.php?f=open_email_address

Quan trọng: Endpoint này không tự tạo mailbox mới. Nếu mailbox đã bị xóa hoặc domain không còn tồn tại, API trả 404 MAILBOX_NOT_FOUND.

Response trả về session của mailbox đã mở lại, kèm catalog domain mới nhất.

Tham số body
Tham số	Bắt buộc	Mô tả
email_addr	Có	Địa chỉ mailbox cần mở lại, dạng `test@tempmailmmo.com`.
force_takeover	Không	`1/true` để takeover nếu mailbox đang bị session khác giữ.
sid_token	Không	Token phiên hiện tại, dùng để ưu tiên resume/takeover đúng ngữ cảnh.
lang	Không	Ngôn ngữ phiên, hỗ trợ `vi` hoặc `en`.

Schema response
Trường	Kiểu	Mô tả
email_addr	string	Địa chỉ mailbox đã mở lại.
email_user	string	Phần local-part của mailbox đã mở lại.
email_domain	string	Domain của mailbox đã mở lại.
sid_token	string (48 hex)	Token phiên dùng cho các action mailbox.
alias	number	Cờ tương thích, hiện trả 0.
session_started_at / welcome_created_at / session_expires_at / session_ttl_minutes	number	Nhóm session meta chuẩn. Xem mục Xác thực phiên.
list / count / list_source / list_cached_at	mixed	Danh sách thư của mailbox mở lại: `list_source` là `live` (fetch mới), `cache` hoặc `stale` (cache cũ khi máy chủ thư lỗi).
domains / defaultDomain / domains_updated_at	mixed	Catalog domain mới nhất. Xem get_domains.

Lỗi thường gặp
Lỗi	HTTP	Mô tả
Invalid or unsupported email address	400	Địa chỉ sai định dạng, hoặc domain không thuộc hệ thống (kể cả domain đã ngừng hoạt động nếu không giữ lại mailbox).
Mailbox not found on server	404	Mailbox đã bị xóa hoặc không còn tồn tại trên máy chủ.
Email address is already in use by another session	409	Mailbox đang được session khác sử dụng và chưa bật takeover.

Response 200

{
  "email_addr": "old_mailbox@tempmailmmo.com",
  "email_user": "old_mailbox",
  "email_domain": "tempmailmmo.com",
  "sid_token": "0123456789abcdef0123456789abcdef0123456789abcdef",
  "alias": 0,
  "list": [],
  "count": 0,
  "list_source": "live",
  "session_started_at": 1710000000000,
  "welcome_created_at": 1710000000000,
  "session_expires_at": 1710108000000,
  "session_ttl_minutes": 180,
  "domains": ["mailmmo.io.vn", "tempmailmmo.com"],
  "defaultDomain": "tempmailmmo.com",
  "domains_updated_at": 1710000000000
}

cURL

curl -X POST "https://your-domain.com/tool/ajax.php?f=open_email_address" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "email_addr=oldbox@mailmmo.io.vn&force_takeover=1&lang=vi"

Lấy danh sách email #

Lấy danh sách email theo sid_token, phân trang bằng offset.

POST /tool/ajax.php?f=get_email_list

Poll mỗi 15 giây, backoff khi quá tải. Response kèm catalog domain mới nhất, gia hạn session và trả session meta trong cả JSON response lẫn response header.

Tham số body
Tham số	Bắt buộc	Mô tả
sid_token	Có	Token phiên đang hoạt động (gửi trong tham số body).
offset	Không	Vị trí bắt đầu lấy dữ liệu, mặc định là 0.
force_sync	Không	`1` để bỏ qua cache và đồng bộ mới từ máy chủ thư.
domains_updated_at	Không	Timestamp catalog domain client đang giữ. Nếu trùng với server, response bỏ trường `domains` để tiết kiệm băng thông.

Schema response
Trường	Kiểu	Mô tả
list	object[]	Danh sách email theo trang.
count	number	Số phần tử hiện có trong list.
offset / limit	number	Vị trí trang hiện tại và kích thước trang thực tế.
has_more	boolean	Còn trang kế tiếp hay không.
scan_limit / scan_limit_reached	number / boolean	Giới hạn quét hộp thư (mặc định 2000). Vượt giới hạn trả list rỗng và `scan_limit_reached: true`.
session_started_at / welcome_created_at / session_expires_at / session_ttl_minutes	number	Nhóm session meta chuẩn. Xem mục Xác thực phiên.
domains	string[]	Danh sách domain khả dụng hiện tại (bỏ qua khi client gửi `domains_updated_at` khớp server).
defaultDomain	string	Domain mặc định hiện tại của hệ thống.
domains_updated_at	number	Unix timestamp (mili giây) của lần đồng bộ catalog domain gần nhất.

Schema item trong list[]
Trường	Kiểu	Mô tả
mail_id	string	ID thư (ví dụ `123` hoặc `Junk:123`).
mail_from	string	Người gửi.
mail_subject	string	Tiêu đề thư.
mail_excerpt	string	Đoạn trích tối đa 140 ký tự.
mail_timestamp	string	Unix timestamp (giây) dạng chuỗi.
mail_read	number	1 = đã đọc, 0 = chưa đọc.
attached	number	1 = có tệp đính kèm, 0 = không.

Lấy chi tiết email #

Trả về toàn bộ nội dung thư theo email_id: body HTML và tệp đính kèm.

POST /tool/ajax.php?f=fetch_email

Response header kèm session meta. Xem mục Xác thực phiên.

Thư được tự động đánh dấu đã đọc khi fetch. Ảnh nội tuyến CID (cid:) trong mail_body được nhúng sẵn thành data URI nên hiển thị ngay.

Tham số body
Tham số	Bắt buộc	Mô tả
sid_token	Có	Token phiên đang hoạt động (gửi trong tham số body).
email_id	Có	Mã email lấy từ danh sách `list[].mail_id`.

Schema response
Trường	Kiểu	Mô tả
mail_id	string	ID thư.
mail_from	string	Người gửi.
mail_subject	string	Tiêu đề thư.
mail_body	string (HTML)	Nội dung thư dạng HTML đã xử lý.
mail_timestamp	string	Unix timestamp (giây) dạng chuỗi.
mail_attachments	object[]	Danh sách tệp đính kèm.

Schema item trong mail_attachments[]
Trường	Kiểu	Mô tả
name	string	Tên file.
size	number	Kích thước file (bytes).
type	string	MIME type của file.

Tải tệp đính kèm #

Tải nhị phân tệp đính kèm từ một email cụ thể.

POST /tool/ajax.php?f=fetch_attachment

Response body là binary nên session meta mới nhất được gửi qua response header. Xem mục Xác thực phiên.

Tham số body
Tham số	Bắt buộc	Mô tả
sid_token	Có	Token phiên đang hoạt động.
email_id	Có	Mã email lấy từ danh sách thư hoặc `fetch_email`.
file_name	Có	Tên file cần tải, khớp với trường `name` trong `mail_attachments`.

Kết quả response
Thành phần	Giá trị	Mô tả
Body	binary	Nội dung tệp đính kèm.
Content-Type	application/octet-stream	Kiểu nội dung tải về.
Content-Disposition	attachment	Ép trình duyệt tải file.

Xóa email #

Xóa một hoặc nhiều email theo danh sách id.

POST /tool/ajax.php?f=del_email

Endpoint này cũng gia hạn session và gửi session meta qua response header. Xem mục Xác thực phiên.

Tham số body
Tham số	Bắt buộc	Mô tả
sid_token	Có	Token phiên đang hoạt động (gửi trong tham số body).
email_id hoặc email_ids[]	Không	ID email cần xóa. Chấp nhận nhiều giá trị: `email_ids[]=1&email_ids[]=2` hoặc chuỗi phân tách bằng dấu phẩy `email_id=1,2,3` (tối đa 100 ID/request). Nếu bỏ trống, API trả `deleted: 0`.

Schema response
Trường	Kiểu	Mô tả
deleted	number	Số email đã xóa thành công.

Address Generator API #

Sinh dữ liệu địa chỉ/nhân vật giả theo quốc gia.

GET /api/tools/address/countries

Trả về countries[] gồm code, name, hasPostalCodes, postalCodeFormat, kèm total.

GET /api/tools/address/generate?countryCode=US

Tham số query
Tham số	Bắt buộc	Mô tả
countryCode	Có	Mã quốc gia 2 chữ cái, ví dụ `US`, `JP`, `VN`.

Schema response
Trường	Kiểu	Mô tả
country	object	`code`, `name`, `nativeName`, `dialCode`, `postalCodeFormat`, `hasPostalCodes`.
address	object	`street`, `addressLine2`, `district`, `city`, `region`, `postalCode`, `phoneNumber`, `landmark`, `country`, `formatted`.
profile	object	`fullName`, `firstName`, `middleName`, `lastName`, `gender`, `birthday`, `age`, `nationalId`, `username`, `email`, `company`.
meta	object	Nguồn dữ liệu từng trường (`faker`, `zippopotam`, `google_geocoding`) và trạng thái provider.
generatedAt	string	Thời điểm sinh dữ liệu (ISO 8601).

Lỗi: 400 thiếu/sai mã quốc gia, 404 quốc gia không hỗ trợ, 502 provider lỗi.

Health #

Kiểm tra server còn hoạt động.

GET /health

Trả {"ok":true} khi server phản hồi.

Giới hạn & lưu ý tích hợp #

Các ràng buộc vận hành cần biết khi tích hợp tool.

Hạng mục	Giá trị	Ghi chú
HTTP method cho action mailbox	POST	Các action mailbox dùng GET sẽ bị từ chối (405).
sid_token format	48 ký tự hex	Ví dụ: `012345...abcdef`.
offset	0 → scan_limit	Vượt `scan_limit` trả list rỗng kèm `scan_limit_reached: true`.
scan_limit	Mặc định 2000	Xem `scan_limit` trong response `get_email_list`.
Kích thước trang list mail	Tối đa 500 (mặc định 50)	Phụ thuộc cấu hình server.
Số email_id cho del_email	Tối đa 100 ID/request	Chấp nhận `email_ids[]` hoặc chuỗi phân tách dấu phẩy.
Kích thước tệp đính kèm tải về	Tối đa 5MB	Vượt giới hạn trả 413.
Rate limit	Theo cấu hình máy chủ	Vượt giới hạn trả `429` kèm `Retry-After`.
Thời gian sống của session	Mặc định 180 phút	Dùng `session_expires_at` trong response để theo dõi thời điểm hết hạn thực tế.
Mailbox event token (SSE)	5–10 phút	Token ngắn hạn, tự rotate khi đổi mailbox/takeover.

Mã lỗi thường gặp #

Tất cả lỗi trả về dạng JSON: {"error":"..."}.

400

Thiếu tham số, action không hợp lệ, hoặc format dữ liệu sai (gồm cả sid_token trên query string).

401

sid_token không hợp lệ hoặc phiên đã hết hạn.

403

Yêu cầu bị từ chối. Tool client vui lòng dùng /tool/ajax.php.

404

Email hoặc tệp đính kèm không tồn tại.

405

Gọi sai HTTP method cho action tương ứng.

409

Email đã được session khác sử dụng.

413

Tệp đính kèm quá lớn (vượt giới hạn server).

429

Vượt giới hạn tần suất request, cần retry theo Retry-After.

500

Lỗi xử lý nội bộ server.

502

Dịch vụ upstream tạm thời không khả dụng.

503

Service chưa được cấu hình đầy đủ (ví dụ thiếu domain).

Khuyến nghị: timeout 15 giây, retry backoff cho lỗi mạng, tái tạo session khi nhận 401. Một số lỗi nghiệp vụ kèm mã chi tiết, ví dụ: {"error":"Mailbox not found on server","code":"MAILBOX_NOT_FOUND"}.

Tổng quan API

Bắt đầu nhanh #

Xác thực phiên #

Mailbox Events #

Lấy danh sách domain #

Kiểm tra hạn domain #

Tạo mailbox tạm hoặc lấy lại session #

Đặt username/domain theo ý muốn #

Mở lại mailbox cũ đã tồn tại #

Lấy danh sách email #

Lấy chi tiết email #

Tải tệp đính kèm #

Xóa email #

Address Generator API #

Health #

Giới hạn & lưu ý tích hợp #

Mã lỗi thường gặp #