Mail1s.net – Dịch Vụ Temp-Mail Bảo Vệ Quyền Riêng Tư

API Mail1s

REST API tạo địa chỉ tạm, đọc thư, quản lý hộp thư từ script / server của bạn.

Xác thực

Mọi request phải có 1 trong 2 header sau:

  • Authorization: Bearer <api_key> — chuẩn OAuth, ưu tiên dùng.
  • X-API-Key: <api_key> — tiện cho công cụ không nhận Bearer.

Bạn chưa có API key. Tạo ngay tại Profile — chỉ tốn 1 click.

Mọi endpoint trả JSON. Lỗi có dạng { "error": "..." } với HTTP status thích hợp (401 sai key, 403 không đủ quyền, 404 không tìm thấy, 429 vượt quota, 400 sai dữ liệu).

CORS bật * — gọi được trực tiếp từ trình duyệt nếu bạn muốn.

Endpoints
GET/api/v1/domains

Danh sách domain dùng được

Trả các domain mà API key của bạn có quyền tạo địa chỉ (theo gói trả phí + quyền riêng tư).

Curl

curl -X GET 'https://your-host/api/v1/domains' \
  -H 'Authorization: Bearer <API_KEY>'

Response (200 OK)

{
  "domains": [
    { "id": "65f0…", "domain": "mail1s.net", "isPrivate": false, "paidPlanOnly": false }
  ]
}
POST/api/v1/addresses

Tạo địa chỉ tạm

Tạo (và lưu) một địa chỉ tạm trên domain bạn chọn. Có thể truyền `domainId` hoặc `domain`. Nếu bỏ trống `localPart`, server sinh ngẫu nhiên 10 ký tự.

  • Body JSON: { domainId?: string, domain?: string, localPart?: string | null }
  • Trả luôn id (để xoá địa chỉ sau này) và address.
  • Idempotent: gọi lại với cùng localPart + domain sẽ trả về địa chỉ đã tồn tại thay vì tạo trùng.

Curl

curl -X POST 'https://your-host/api/v1/addresses' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "domain": "mail1s.net", "localPart": "demo123" }'

Response (200 OK)

{
  "id": "66ab…",
  "address": "[email protected]",
  "domain": "mail1s.net",
  "domainId": "65f0…",
  "createdAt": "2026-05-07T08:30:00.000Z"
}
GET/api/v1/addresses

Danh sách mail đã tạo

Trả các địa chỉ tạm bạn đã tạo qua API/web. Thêm `?withCounts=1` để kèm tổng số thư và số chưa đọc cho mỗi hộp.

Curl

curl -X GET 'https://your-host/api/v1/addresses?withCounts=1' \
  -H 'Authorization: Bearer <API_KEY>'

Response (200 OK)

{
  "addresses": [
    {
      "id": "66ab…",
      "address": "[email protected]",
      "domain": "mail1s.net",
      "domainId": "65f0…",
      "createdAt": "2026-05-07T08:30:00.000Z",
      "total": 4,
      "unread": 1
    }
  ]
}
DELETE/api/v1/addresses/{address}

Xoá địa chỉ tạm

Xoá địa chỉ khỏi danh sách của bạn. Mặc định xoá luôn các thư đã nhận; truyền `?keepMessages=1` để giữ lại thư.

Curl

curl -X DELETE 'https://your-host/api/v1/addresses/[email protected]' \
  -H 'Authorization: Bearer <API_KEY>'

Response (200 OK)

{ "ok": true, "address": "[email protected]", "deletedMessages": 4 }
GET/api/v1/addresses/{address}/messages

Lấy hòm thư

Liệt kê thư đã nhận trong một hộp. Tham số: `?limit=` (1–200, mặc định 80) và `?unreadOnly=1`.

Curl

curl -X GET 'https://your-host/api/v1/addresses/[email protected]/messages?limit=20' \
  -H 'Authorization: Bearer <API_KEY>'

Response (200 OK)

{
  "address": "[email protected]",
  "count": 1,
  "messages": [
    {
      "id": "68bf…",
      "from": "[email protected]",
      "subject": "Bank receipt",
      "snippet": "You have transferred 100,000 VND…",
      "date": "2026-05-07T08:35:11.000Z",
      "read": false
    }
  ]
}
GET/api/v1/addresses/{address}/messages/{id}

Đọc 1 hòm thư

Trả nội dung đầy đủ của thư (text + html). Tự đánh dấu đã đọc, trừ khi truyền `?markRead=0`.

Curl

curl -X GET 'https://your-host/api/v1/addresses/[email protected]/messages/68bf…' \
  -H 'Authorization: Bearer <API_KEY>'

Response (200 OK)

{
  "id": "68bf…",
  "address": "[email protected]",
  "from": "[email protected]",
  "subject": "Bank receipt",
  "date": "2026-05-07T08:35:11.000Z",
  "text": "You have transferred …",
  "html": "<table>…</table>",
  "read": true
}
DELETE/api/v1/addresses/{address}/messages/{id}

Xoá 1 thư

Xoá vĩnh viễn một thư khỏi hộp.

Curl

curl -X DELETE 'https://your-host/api/v1/addresses/[email protected]/messages/68bf…' \
  -H 'Authorization: Bearer <API_KEY>'

Response (200 OK)

{ "ok": true, "id": "68bf…" }
DELETE/api/v1/addresses/{address}/messages

Xoá toàn bộ thư trong hộp

Xoá tất cả thư trong một hộp nhưng giữ lại địa chỉ.

Curl

curl -X DELETE 'https://your-host/api/v1/addresses/[email protected]/messages' \
  -H 'Authorization: Bearer <API_KEY>'

Response (200 OK)

{ "ok": true, "address": "[email protected]", "deleted": 4 }

Ví dụ Node.js (fetch)

const API_KEY = '<API_KEY>';
const BASE = 'https://your-host';

async function api(path, init = {}) {
  const r = await fetch(BASE + path, {
    ...init,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...(init.headers || {}),
    },
  });
  if (!r.ok) throw new Error((await r.json()).error || r.statusText);
  return r.json();
}

// 1. Tạo địa chỉ
const addr = await api('/api/v1/addresses', {
  method: 'POST',
  body: JSON.stringify({ domain: 'mail1s.net' }),
});
console.log('Tạo:', addr.address);

// 2. Đợi vài giây để có thư về…
await new Promise((r) => setTimeout(r, 5000));

// 3. Liệt kê hòm thư
const inbox = await api(`/api/v1/addresses/${encodeURIComponent(addr.address)}/messages`);
console.log('Số thư:', inbox.count);

// 4. Đọc thư mới nhất
if (inbox.messages[0]) {
  const msg = await api(
    `/api/v1/addresses/${encodeURIComponent(addr.address)}/messages/${inbox.messages[0].id}`,
  );
  console.log('From:', msg.from, '— Subject:', msg.subject);
}

// 5. Xoá địa chỉ + sạch hòm thư
await api(`/api/v1/addresses/${encodeURIComponent(addr.address)}`, { method: 'DELETE' });

Hạn mức (số mail tạo/ngày, số địa chỉ lưu) tuân theo gói trả phí trong /upgrade.

Quảng cáo

Quảng cáo