TempMail MMO - API Documentation

Quickstart #

Standard integration flow from mailbox creation to reading mail and downloading attachments.

Get domain list GET /tool/ajax.php?f=get_domains
Create session and temp email POST /tool/ajax.php?f=get_email_address
Customize username/domain Optional POST /tool/ajax.php?f=set_email_user
Reopen an existing mailbox Optional POST /tool/ajax.php?f=open_email_address
Poll the mail list POST /tool/ajax.php?f=get_email_list every 15 seconds, back off on 429/503.
Read mail details POST /tool/ajax.php?f=fetch_email
Download attachments POST /tool/ajax.php?f=fetch_attachment

Session Auth #

After get_email_address succeeds, the response returns a sid_token — required for all mailbox actions. Session-context responses also carry session metadata to track expiry.

Security: send sid_token as a body parameter, never in the URL query string.

Auth fields
Field	Required	Description
sid_token	Yes	48-character hex string representing the active session.
lang	No	Preferred language, supports `vi` or `en`.

Session meta in JSON response
Field	Type	Description
session_started_at	number	Unix timestamp (milliseconds) when the session was created.
session_expires_at	number	Unix timestamp (milliseconds) when the current session expires.
session_ttl_minutes	number	Configured session TTL in minutes (default 180, server-configurable).
welcome_created_at	number	Unix timestamp (milliseconds) when the welcome email was created for the current mailbox (0 if none).

Mailbox actions (get_email_list, fetch_email, del_email, fetch_attachment) send the latest session meta via response headers.

Response headers
Header	Type	Description
X-Session-Started-At	number	Unix timestamp (milliseconds) when the session was created.
X-Welcome-Created-At	number	Unix timestamp (milliseconds) when the welcome email was created (0 if none).
X-Session-Expires-At	number	Unix timestamp (milliseconds) when the most recently renewed session expires.
X-Session-Ttl-Minutes	number	Session TTL in minutes.

Mailbox Events #

SSE stream for the website or private deployments with mailbox events enabled. The tools process at /tool/ajax.php does not enable SSE — tool clients should use get_email_list polling every 15 seconds.

GET SSE /events/mailbox?token=MAILBOX_EVENT_TOKEN

Before connecting, call POST /ajax.php?f=get_mailbox_event_token (with sid_token in the body) to get an opaque 256-bit token, scope mailbox:events, TTL 5-10 minutes.

get_mailbox_event_token response

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

Server-Sent Events standard; clients reconnect automatically per retry: 2000.

Query parameters
Parameter	Required	Description
token	Yes	`mailbox_event_token` Token of the current mailbox session.

Event list
Event	When sent	Main payload
state	On connect or when the watcher changes state.	`ok` `email` `connected` `count` `connected_folders` `watched_folders` `folders` `ts` Optional: `error`, `token_expires_at` (first state event after connecting).
changed	When the mailbox count changes or new mail arrives.	`email` `reason` `connected` `count` `total_count` `connected_folders` `ts` Optional: `prevCount` `folder` `path`
ping	Periodic keepalive to keep the stream alive.	Same as `state`, plus `ping: true`.
session_lost	When the session expires or the token no longer matches the current mailbox.	`email` `ts`
token_expiring	When the SSE token is about to expire and the client should fetch a new one.	`email` `expires_at` `ts`
token_expired	When the token has expired or was revoked due to rotation/mailbox change.	`email` `ts`

Recommendation: only call get_email_list when first opening the mailbox, on changed events, or when SSE fails/is unavailable.

Security: the token is a temporary credential — use HTTPS only, never send the full URL to analytics. It cannot read/delete mail and is rotated on mailbox change, takeover, session rotation, or session end.

Common errors: 401 invalid token/lost session, 429 too many SSE connections from one IP, 503 event server saturated.

Get Domain List #

Available domains, the default domain, and when the catalog was last updated.

GET /tool/ajax.php?f=get_domains

Response schema
Field	Type	Description
domains	string[]	List of available domains.
defaultDomain	string	Default domain selected when none is specified.
domains_updated_at	number	Unix timestamp (milliseconds) of the latest domain catalog sync.
domain_expiry_lookup_enabled	boolean	Whether domain expiry checks (WHOIS/RDAP) are enabled.
domain_expiry_source	string	Expiry data source, e.g. `rdap` or `whois`.
domain_expiry_checked_at	number	Unix timestamp (milliseconds) of the latest expiry check.
domain_expiry_warning_days	number	Warning window in days before domain expiry.
delete_data_on_domain_expiry	boolean	Whether mailbox data is auto-deleted when the domain expires.
domain_expiry_statuses	object[]	Per-domain expiry status (only when lookup is enabled).
domain_expiry_alerts	object[]	Alerts for domains nearing expiry.

Check Domain Expiry #

Expiry status for a specific domain or the whole catalog.

GET /tool/ajax.php?f=get_domain_expiry

Query parameters
Parameter	Required	Description
domain	No	Domain to look up. Omit to get the whole catalog status.
force	No	`1` to bypass cache and force a fresh lookup.

Response schema
Field	Type	Description
domain	string	The looked-up domain (only when `domain` is sent).
domain_expiry_lookup_enabled / domain_expiry_source / domain_expiry_warning_days / delete_data_on_domain_expiry	mixed	Current expiry config. See get_domains.
expires_at / lookup_status / message	mixed	Expiry status of the domain (single-domain lookup).
alerts / statuses	object[]	Alerts and per-domain statuses (when `domain` is omitted).

Create Temp Mailbox or Resume Session #

Creates a new mailbox, or resumes the session when a valid sid_token is sent in the body.

POST /tool/ajax.php?f=get_email_address

The response also includes the current domain catalog so clients can sync without a separate get_domains call.

Note: sid_token only represents a temporary access session. When the session expires, the mailbox can still be reopened via open_email_address if it still exists on the server.

Body parameters
Parameter	Required	Description
email_domain	No	Desired domain; falls back to `defaultDomain` if omitted.
lang	No	Session language, e.g. `vi` or `en`.
sid_token	No	Send an old token as a body parameter to resume the session if still valid.
request_id	No	Idempotency key, 16-128 chars (`A-Za-z0-9_-`). Retrying with the same `request_id` returns the already-created mailbox instead of creating a duplicate.

Response schema
Field	Type	Description
email_addr	string	Full email address `local@domain`.
email_user	string	Local-part of the email.
email_domain	string	Current session domain.
sid_token	string (48 hex)	Session token for mailbox actions.
alias	number	Compatibility flag, currently returns 0.
session_started_at / welcome_created_at / session_expires_at / session_ttl_minutes	number	Standard session meta group. See Session Auth.
list / count / list_source / list_cached_at	mixed	Cached mail list (if available): `list_source` is `live`, `cache`, or `stale`; `list_cached_at` is the cache timestamp.
domains / defaultDomain / domains_updated_at	mixed	Latest domain catalog. See get_domains.

Set Custom Username/Domain #

Updates the email address with a specified username and domain for the current session.

POST /tool/ajax.php?f=set_email_user

If force_takeover is enabled and the target email is held by another session: the old session is revoked, sid_token is rotated (the old token dies immediately), and the response returns the new session holding that mailbox.

Body parameters
Parameter	Required	Description
sid_token	Yes	Active session token.
email_user	Yes	Username of 3-64 characters, only `a-z`, `0-9`, dots, underscores, hyphens.
email_domain	No	Target domain. Falls back to the default domain if invalid.
create_only	No	`1/true` to only allow setting a brand-new email. Existing emails return `409 EMAIL_ADDRESS_EXISTS`.
force_takeover	No	`1/true` to take over the target email if held by another session.
lang	No	Session language, supports `vi` or `en`.

Response schema
Field	Type	Description
email_addr	string	New email address after update.
email_user	string	Current username.
email_domain	string	Current domain.
sid_token	string (48 hex)	Session token remains unchanged.
alias	number	Compatibility flag, currently returns 0.
session_started_at / welcome_created_at / session_expires_at / session_ttl_minutes	number	Standard session meta group. See Session Auth.
list / count / list_source / list_cached_at	mixed	Cached mail list (if available): `list_source` is `live`, `cache`, or `stale`.
domains / defaultDomain / domains_updated_at	mixed	Latest domain catalog. See 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"

Reopen Existing Mailbox #

Reopens an old mailbox by full address local@domain to read mail.

POST /tool/ajax.php?f=open_email_address

Important: this endpoint does not create a new mailbox. If the mailbox was deleted from the server or the domain no longer exists, the API returns 404 MAILBOX_NOT_FOUND.

The response returns the reopened mailbox's session data, plus the latest domain catalog.

Body parameters
Parameter	Required	Description
email_addr	Yes	Mailbox address to reopen, e.g. `test@tempmailmmo.com`.
force_takeover	No	`1/true` to take over if the mailbox is held by another session.
sid_token	No	Current session token, used to prefer resume/takeover in the right context.
lang	No	Session language, supports `vi` or `en`.

Response schema
Field	Type	Description
email_addr	string	Reopened mailbox address.
email_user	string	Local-part of the reopened mailbox.
email_domain	string	Domain of the reopened mailbox.
sid_token	string (48 hex)	Session token for mailbox actions.
alias	number	Compatibility flag, currently returns 0.
session_started_at / welcome_created_at / session_expires_at / session_ttl_minutes	number	Standard session meta group. See Session Auth.
list / count / list_source / list_cached_at	mixed	Cached mail list (if available): `list_source` is `live` (fresh fetch), `cache`, or `stale` (old cache when the mail server fails).
domains / defaultDomain / domains_updated_at	mixed	Latest domain catalog. See get_domains.

Common errors
Error	HTTP	Description
Mailbox not found on server	404	Mailbox was deleted or no longer exists on the server.
Email address is already in use by another session	409	Mailbox is in use by another session and takeover is not enabled.
Invalid or unsupported email address	400	Malformed address, or domain not owned by the system (including retired domains when mailbox retention is off).

Response 200

{
  "email_addr": "old_mailbox@tempmailmmo.com",
  "email_user": "old_mailbox",
  "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,
  "list": [],
  "count": 0,
  "list_source": "live",
  "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=en"

Get Email List #

Fetches the email list using sid_token, paginated via offset.

POST /tool/ajax.php?f=get_email_list

Poll every 15 seconds with backoff under load. The response includes the latest domain catalog, extends the session, and returns session meta in both the JSON body and response headers.

Body parameters
Parameter	Required	Description
sid_token	Yes	Active session token (sent as a body parameter).
offset	No	Starting position, defaults to 0.
force_sync	No	`1` to bypass the cache and sync fresh from the mail server.
domains_updated_at	No	The catalog timestamp the client holds. When it matches the server, the `domains` field is omitted to save bandwidth.

Response schema
Field	Type	Description
list	object[]	Paginated email list.
count	number	Number of items currently in list.
offset / limit	number	Current page position and page size.
has_more	boolean	Whether more pages exist beyond the current one.
scan_limit / scan_limit_reached	number / boolean	Mailbox scan cap (default 2000). Beyond it the list is empty with `scan_limit_reached: true`.
session_started_at / welcome_created_at	number	Unix timestamp (milliseconds) when the session was created / welcome email created.
session_expires_at	number	Unix timestamp (milliseconds) when the renewed session expires.
session_ttl_minutes	number	Configured session TTL in minutes.
domains	string[]	Current list of available domains. Omitted when the client's `domains_updated_at` matches the server.
defaultDomain	string	Current system default domain.
domains_updated_at	number	Unix timestamp (milliseconds) of the latest domain catalog sync.

Item schema in list[]
Field	Type	Description
mail_id	string	Mail ID (e.g. `123` or `Junk:123`).
mail_from	string	Sender.
mail_subject	string	Subject.
mail_excerpt	string	Short content excerpt, up to 140 characters.
mail_timestamp	string	Unix timestamp (seconds) as string.
mail_read	number	1 = read, 0 = unread.
attached	number	1 = has attachments, 0 = none.

Fetch Email Details #

Returns full message content by email_id: HTML body and attachments.

POST /tool/ajax.php?f=fetch_email

Response headers carry session meta. See Session Auth.

Mail is automatically marked as read on fetch. Inline CID images (cid:) in mail_body are embedded as data URIs so they render immediately.

Body parameters
Parameter	Required	Description
sid_token	Yes	Active session token (sent as a body parameter).
email_id	Yes	Mail ID from the list `list[].mail_id`.

Response schema
Field	Type	Description
mail_id	string	Mail ID.
mail_from	string	Sender.
mail_subject	string	Subject.
mail_body	string (HTML)	Processed HTML message body.
mail_timestamp	string	Unix timestamp (seconds) as string.
mail_attachments	object[]	Attachment list.

Item schema in mail_attachments[]
Field	Type	Description
name	string	File name.
size	number	File size (bytes).
type	string	File MIME type.

Download Attachment #

Downloads attachment binary from a specific email.

POST /tool/ajax.php?f=fetch_attachment

The response body is binary, so the latest session meta is sent via response headers. See Session Auth.

Body parameters
Parameter	Required	Description
sid_token	Yes	Active session token.
email_id	Yes	Mail ID from the list or `fetch_email`.
file_name	Yes	File name to download, matching the `name` field in `mail_attachments`.

Response result
Component	Value	Description
Body	binary	Attachment file content.
Content-Type	application/octet-stream	Download content type.
Content-Disposition	attachment	Forces browser file download.

Delete Email #

Deletes one or more emails by ID list.

POST /tool/ajax.php?f=del_email

This endpoint also renews the session and sends session meta via response headers. See Session Auth.

Body parameters
Parameter	Required	Description
sid_token	Yes	Active session token (sent as a body parameter).
email_id or email_ids[]	No	Email ID(s) to delete. Accepts multiple values: `email_ids[]=1&email_ids[]=2` or a comma-separated string `email_id=1,2,3` (max 100 IDs per request). If empty, the API returns `deleted: 0`.

Response schema
Field	Type	Description
deleted	number	Number of emails successfully deleted.

Address Generator API #

Generates fake address/profile data per country.

GET /api/tools/address/countries

Returns countries[] with code, name, hasPostalCodes, postalCodeFormat, plus total.

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

Query parameters
Parameter	Required	Description
countryCode	Yes	2-letter country code, e.g. `US`, `JP`, `VN`.

Response schema
Field	Type	Description
country	object	Country info: `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	Data sources (`faker`, `zippopotam`, `google_geocoding`) and provider status.
generatedAt	string	ISO 8601 timestamp.

Errors: 400 missing/invalid country code, 404 unsupported country, 502 provider failure.

Health #

Check whether the server is up.

GET /health

Returns {"ok":true} when the server responds.

Limits & Integration Notes #

Operational constraints to know when integrating tools.

Item	Value	Notes
HTTP method for mailbox actions	POST	Mailbox actions via GET are rejected (405).
sid_token format	48 hex characters	Example: `012345...abcdef`.
offset	0 → scan_limit	Beyond `scan_limit` the list is empty with `scan_limit_reached: true`.
scan_limit	Default 2000	See `scan_limit` in the `get_email_list` response.
Mail list page size	Max 500 (default 50)	Depends on server configuration.
email_id count for del_email	Max 100 IDs/request	Accepts `email_ids[]` or a comma-separated string.
Attachment download size	Max 5MB	Exceeding the limit returns 413.
Rate limit	Per server configuration	Exceeding returns `429` with `Retry-After`.
Session lifetime	Default 180 minutes	Use `session_expires_at` to track the actual expiry.
Mailbox event token	5-10 minutes	Short-lived token, auto-rotated on mailbox change/takeover.

Common Error Codes #

All errors are returned as JSON: {"error":"..."}.

400

Missing parameter, invalid action, or malformed data (including sid_token in the query string).

401

Invalid sid_token or expired session.

403

Request rejected. Tool clients must use /tool/ajax.php.

404

Email or attachment does not exist.

405

Wrong HTTP method for the action.

409

Email already in use by another session.

413

Attachment too large (exceeds server limit).

429

Rate limit exceeded; retry per Retry-After.

500

Internal server processing error.

502

Upstream service temporarily unavailable.

503

Service not fully configured (e.g. missing domains).

Recommendation: 15 second timeout, retry with backoff on network errors, recreate the session on 401. Business errors may include a detailed code, e.g. {"error":"Mailbox not found on server","code":"MAILBOX_NOT_FOUND"}.

API Overview

Quickstart #

Session Auth #

Mailbox Events #

Get Domain List #

Check Domain Expiry #

Create Temp Mailbox or Resume Session #

Set Custom Username/Domain #

Reopen Existing Mailbox #

Get Email List #

Fetch Email Details #

Download Attachment #

Delete Email #

Address Generator API #

Health #

Limits & Integration Notes #

Common Error Codes #