Tổng quan API

Lấy mailbox_event_token từ JSON response hoặc header X-Mailbox-Event-Token của các action mailbox như get_email_address, set_email_user, open_email_address và get_email_list.

Kết nối này dùng chuẩn Server-Sent Events. Trình duyệt hoặc client SSE sẽ tự reconnect; server hiện gửi retry: 2000 để gợi ý reconnect sau 2 giây.

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();
  // Tạo lại session hoặc mở lại mailbox rồi lấy mailbox_event_token mới.
});

source.onerror = () => {
  // Nếu SSE bị gián đoạn lâu, fallback poll get_email_list mỗi 15-30 giây.
};

Khuyến nghị tích hợp: 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. Không nên vừa giữ SSE vừa poll dày liên tục.

Trả về danh sách domain khả dụng, domain mặc định và thời điểm cập nhật catalog domain gần nhất.

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

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

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

Lưu ý: sid_token chỉ đại diện cho phiên truy cập tạm. Khi phiên hết hạn, mailbox không bị xóa ngay khỏi máy chủ và vẫn có thể mở lại bằng open_email_address nếu email hoặc domain đó còn tồn tại.

{
  "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
}

Lấy danh sách email theo sid_token trong tham số body, hỗ trợ phân trang bằng offset.

Nên ưu tiên mailbox event stream cho cập nhật realtime. Chỉ dùng endpoint này để polling fallback, với chu kỳ khuyến nghị 15-30 giây thay vì poll dày liên tục.

Response cũng kèm catalog domain mới nhất để client đang hoạt động có thể đồng bộ ngay khi danh sách domain thay đổi.

Endpoint này đồng thời gia hạn session và trả cả session meta trong JSON response lẫn response header.

{
  "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
}

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

Nếu bật force_takeover và email mục tiêu đang do session khác giữ, API sẽ trả về session hiện đang sở hữu 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
}

Mở lại một mailbox cũ theo địa chỉ đầy đủ local@domain để đọc thư trên mailbox đó.

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

Response trả về dữ liệu session của mailbox đã mở lại, đồng thời kèm catalog domain mới nhất.

{
  "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
}

Trả về toàn bộ nội dung thư theo email_id, gồm body HTML và danh sách tệp đính kèm.

Response header cũng kèm session meta mới nhất. Xem mục Xác thực phiên để lấy các header X-Session-* và X-Mailbox-Event-Token.

{
  "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"
    }
  ]
}

Tải nhị phân tệp đính kèm từ một email cụ thể. API trả trực tiếp nội dung file.

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

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

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

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

{
  "deleted": 1
}