API Overview

Read mailbox_event_token from the JSON response or the X-Mailbox-Event-Token header returned by mailbox actions such as get_email_address, set_email_user, open_email_address, and get_email_list.

This connection uses Server-Sent Events. Browsers and SSE clients reconnect automatically; the server currently sends retry: 2000 to suggest reconnecting after 2 seconds.

const sidToken = 'SID_TOKEN';
let mailboxEventToken = 'MAILBOX_EVENT_TOKEN';

async function refreshInbox() {
  const response = await fetch('/ajax.php?f=get_email_list', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ sid_token: sidToken, offset: '0' }),
  });
  const payload = await response.json();

  mailboxEventToken = payload.mailbox_event_token
    || response.headers.get('X-Mailbox-Event-Token')
    || mailboxEventToken;

  return payload;
}

const source = new EventSource(`/events/mailbox?token=${encodeURIComponent(mailboxEventToken)}`);

source.addEventListener('changed', async () => {
  await refreshInbox();
});

source.addEventListener('session_lost', () => {
  source.close();
  // Create a new session or reopen the mailbox, then read the next mailbox_event_token.
});

source.onerror = () => {
  // If SSE stays unavailable, fall back to polling get_email_list every 15-30 seconds.
};

Integration recommendation: call get_email_list when the mailbox opens, when a changed event arrives, or when SSE is unavailable. Do not keep SSE open and also run tight polling in parallel.

Returns the list of available domains, the default domain, and the latest domain catalog update timestamp.

{
  "domains": ["mailmmo.io.vn", "tempmailmmo.com"],
  "defaultDomain": "tempmailmmo.com",
  "domains_updated_at": 1710000000000
}

Creates a new mailbox, or restores the current session if a valid sid_token is sent in the request body.

The response also includes the current domain catalog so the client can refresh its domain selector without making a separate get_domains request.

Note: sid_token only represents a temporary access session. When the session expires, the mailbox is not immediately removed from the server and can still be reopened through open_email_address as long as that email address or domain still exists.

{
  "email_addr": "demo@tempmailmmo.com",
  "email_user": "demo123",
  "email_domain": "tempmailmmo.com",
  "sid_token": "0123456789abcdef0123456789abcdef0123456789abcdef",
  "alias": 0,
  "session_started_at": 1710000000000,
  "session_expires_at": 1710086400000,
  "session_ttl_minutes": 1440,
  "mailbox_event_token": "MAILBOX_EVENT_TOKEN",
  "domains": ["mailmmo.io.vn", "tempmailmmo.com"],
  "defaultDomain": "tempmailmmo.com",
  "domains_updated_at": 1710000000000
}

Returns the email list using sid_token from the request body, with optional pagination through offset.

Prefer the mailbox event stream for real-time updates. Use this endpoint as a polling fallback only, with a recommended 15-30 second interval instead of tight continuous polling.

The response also carries the latest domain catalog so active clients can stay in sync when domains are updated.

This endpoint also renews the session and returns session metadata in both the JSON response and the response headers.

{
  "list": [],
  "count": 0,
  "session_started_at": 1710000000000,
  "session_expires_at": 1710086400000,
  "session_ttl_minutes": 1440,
  "mailbox_event_token": "MAILBOX_EVENT_TOKEN",
  "domains": ["mailmmo.io.vn", "tempmailmmo.com"],
  "defaultDomain": "tempmailmmo.com",
  "domains_updated_at": 1710000000000
}

Updates the email address for the current session using the provided username and domain.

If force_takeover is enabled and the target email is currently held by another active session, the API returns the session that already owns that mailbox.

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

Reopens an existing mailbox by its full local@domain address so you can access emails already stored in that mailbox.

Important: This endpoint does not create a new mailbox. If the mailbox has already been deleted from the server or its domain no longer exists on the server, the API returns 404 MAILBOX_NOT_FOUND.

The response includes the reopened session data together with the latest domain catalog.

{
  "email_addr": "old_mailbox@tempmailmmo.com",
  "email_user": "old_mailbox",
  "email_domain": "tempmailmmo.com",
  "sid_token": "0123456789abcdef0123456789abcdef0123456789abcdef",
  "alias": 0,
  "session_started_at": 1710000000000,
  "session_expires_at": 1710086400000,
  "session_ttl_minutes": 1440,
  "mailbox_event_token": "MAILBOX_EVENT_TOKEN",
  "domains": ["mailmmo.io.vn", "tempmailmmo.com"],
  "defaultDomain": "tempmailmmo.com",
  "domains_updated_at": 1710000000000
}

Returns the full email content by email_id, including the HTML body and the attachment list.

The response headers also include the latest session metadata. See Session Authentication for the X-Session-* and X-Mailbox-Event-Token headers.

{
  "mail_id": "123",
  "mail_from": "Example Sender <sender@tempmailmmo.com>",
  "mail_subject": "Your OTP",
  "mail_body": "<html>...</html>",
  "mail_timestamp": "1710000000",
  "mail_attachments": [
    {
      "name": "otp.pdf",
      "size": 20480,
      "type": "application/pdf"
    }
  ]
}

Downloads a binary attachment from a specific email. The API returns the file content directly.

Because the response body is binary, the latest session metadata is delivered through response headers. See Session Authentication.

curl -X POST "https://your-domain.com/ajax.php?f=fetch_attachment" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "sid_token=YOUR_SID_TOKEN&email_id=123&file_name=otp.pdf" \
  --output otp.pdf

Deletes a single email or multiple emails by ID list.

This endpoint also renews the session and sends the latest session metadata through response headers. See Session Authentication.

{
  "deleted": 1
}