REST API v1

Hướng dẫn dùng API

API của Free Domain Mail cho chương trình của bạn một hộp thư chỉ-nhận: tạo địa chỉ, chờ mã OTP hoặc link xác minh, đọc và xoá thư — không cần mở trình duyệt. Hợp với kiểm thử tự động (QA), kiểm thử luồng đăng ký và các script cần lấy mã từ email.

Tạo địa chỉTrên .info, .link, inboxlumo.com hoặc tên miền của bạn.
Chờ mã OTPMột lệnh, chờ tới 60 giây, trả về đúng mã.
Lấy link xác minhLink xác nhận được tách sẵn khỏi thư.

1. Bắt đầu nhanh (3 bước)

Bước 1 — Lấy khóa API

Tạo tài khoản miễn phí (vào dùng ngay, không cần xác minh email) hoặc đăng nhập.
Trong Hộp thư thành viên, kéo xuống mục Lấy mã tự động bằng API và bấm Tạo khóa API. Nếu bạn đã gắn tên miền riêng: Quản lý → API.
Đặt tên khóa (ví dụ CI runner) và sao chép khóa ngay — khóa chỉ hiện một lần.

Các ví dụ bên dưới đọc khóa từ biến môi trường FDM_KEY:

bash

export FDM_KEY="fdm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Bước 2 — Tạo một địa chỉ

Bỏ trống name để nhận một tên ngẫu nhiên dễ nhớ. Thư gửi tới địa chỉ này được giữ 7 ngày và chỉ khóa của bạn đọc được.

curl

curl -X POST https://freedomainmail.com/api/v1/addresses \
  -H "Authorization: Bearer $FDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "inboxlumo.com", "name": "qa.signup"}'

Kết quả:

201 Created

{
  "address": {
    "id": "5b1c2f0e-8a1d-4c3e-9f2a-7d6b1e0c4a91",
    "address": "qa.signup@inboxlumo.com",
    "domain": "inboxlumo.com",
    "created_at": "2026-10-31T08:00:00.000Z",
    "message_count": 0,
    "receiving": true
  }
}

Bước 3 — Chờ mã OTP

Dùng địa chỉ vừa tạo để đăng ký trên trang bạn đang kiểm thử, rồi gọi /code. Lệnh này chờ tối đa 30 giây và trả về ngay khi thư có mã tới.

curl

curl -G https://freedomainmail.com/api/v1/code \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com" \
  --data-urlencode "wait=30"

200 OK

{
  "code": "482913",
  "message_id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
  "from": "no-reply@shop.example",
  "subject": "Mã xác minh của bạn là 482913",
  "received_at": "2026-10-31T08:01:12.000Z"
}

Hết 30 giây mà chưa có thư → 404 với mã lỗi not_found. Gọi lại là được, xem Lỗi và cách xử lý.

2. Địa chỉ thành viên và tên miền riêng

Một khóa API đọc được thư của cả hai loại địa chỉ dưới đây. Các endpoint thư (/messages, /code, /links) dùng chung cho cả hai.

	Địa chỉ thành viên	Tên miền riêng của bạn
Tên miền	`freedomainmail.info`, `freedomainmail.link`, `inboxlumo.com`	Tên miền bạn sở hữu và đã gắn vào tài khoản
Địa chỉ nhận thư	Chỉ các địa chỉ bạn đã tạo (tối đa 100)	Mọi địa chỉ @tenmien (catch-all), không cần tạo trước
Thư được giữ	7 ngày	30 ngày
Tạo / xoá bằng API	`POST /addresses`, `DELETE /addresses/{id}`	Gắn tên miền trên web (cần bản ghi MX + TXT)

Địa chỉ mail tạm 10 phút (dùng không cần đăng ký) không gọi API được. Muốn dùng API với một địa chỉ đó, hãy giữ nó vào tài khoản: POST /addresses với đúng domain và name.

3. Xác thực

Mọi request gửi tới:

https://freedomainmail.com/api/v1

và phải có header Authorization chứa khóa API:

Authorization: Bearer fdm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request và response đều là JSON. Khóa sai, thiếu hoặc đã thu hồi → 401 unauthorized. Chúng tôi chỉ lưu bản băm của khóa; mất khóa thì tạo khóa mới và thu hồi khóa cũ. Đừng nhúng khóa vào code chạy trên trình duyệt hay ứng dụng di động.

4. Danh sách endpoint

Lệnh	Dùng để
`GET /addresses`	Liệt kê địa chỉ thành viên của bạn
`POST /addresses`	Tạo địa chỉ mới
`DELETE /addresses/{id}`	Xoá địa chỉ và toàn bộ thư của nó
`GET /domains`	Liệt kê tên miền riêng đã gắn
`GET /messages`	Danh sách thư, mới nhất trước
`GET /messages/{id}`	Đọc đầy đủ một thư
`DELETE /messages`	Xoá thư
`GET /code`	Chờ và lấy mã OTP mới nhất
`GET /links`	Chờ và lấy link xác minh mới nhất

GET `/api/v1/addresses`

Các địa chỉ thành viên bạn đang giữ, cùng danh sách tên miền tạo được địa chỉ và số địa chỉ tối đa. receiving = false nghĩa là tên miền đó đã ngừng nhận thư mới (thư cũ vẫn đọc được).

curl

curl https://freedomainmail.com/api/v1/addresses -H "Authorization: Bearer $FDM_KEY"

200 OK

{
  "addresses": [
    {
      "id": "5b1c2f0e-8a1d-4c3e-9f2a-7d6b1e0c4a91",
      "address": "qa.signup@inboxlumo.com",
      "domain": "inboxlumo.com",
      "created_at": "2026-10-31T08:00:00.000Z",
      "message_count": 3,
      "receiving": true
    }
  ],
  "domains": ["freedomainmail.info", "freedomainmail.link", "inboxlumo.com"],
  "limit": 100
}

POST `/api/v1/addresses`

Tạo một địa chỉ. Body JSON:

Trường	Ý nghĩa
`domain`	Một tên miền trong domains của GET /addresses. Bỏ trống → tên miền đầu tiên.
`name`	Phần trước @. Chữ, số, dấu chấm, gạch ngang, gạch dưới; 6–40 ký tự trên freedomainmail.info/.link, 4–40 ký tự trên inboxlumo.com. Bỏ trống → tên ngẫu nhiên dễ nhớ.

curl

curl -X POST https://freedomainmail.com/api/v1/addresses \
  -H "Authorization: Bearer $FDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "freedomainmail.info"}'

Trả về 201 và địa chỉ (giống một phần tử của GET /addresses). Lỗi hay gặp: name_taken (409, tên đã có người giữ hoặc vừa được giải phóng), name_invalid (400), name_busy (409, địa chỉ đang nhận mail tạm công khai — thử lại sau 10 phút), limit_reached (409, đã giữ đủ 100 địa chỉ), daily_limit (429, đã tạo đủ số địa chỉ trong ngày).

DELETE `/api/v1/addresses/{id}`

Xoá địa chỉ cùng toàn bộ thư của nó. Trả về 204. Tên đó bị khoá 90 ngày (không ai tạo lại được), nên với test chạy nhiều lần hãy giữ và dùng lại một địa chỉ thay vì tạo–xoá mỗi lần.

curl

curl -X DELETE https://freedomainmail.com/api/v1/addresses/5b1c2f0e-8a1d-4c3e-9f2a-7d6b1e0c4a91 \
  -H "Authorization: Bearer $FDM_KEY"

GET `/api/v1/domains`

Các tên miền riêng đã gắn vào tài khoản và trạng thái nhận thư. accepting_mail thành true khi bản ghi TXT và MX đã được xác minh.

200 OK

{
  "domains": [
    {
      "domain": "yourdomain.com",
      "dns_status": "verified",
      "mx_verified": true,
      "accepting_mail": true,
      "created_at": "2026-08-01T09:00:00.000Z"
    }
  ]
}

GET `/api/v1/messages`

Thư của mọi địa chỉ bạn đọc được, mới nhất trước, lọc bằng bộ lọc dùng chung. Mỗi trang tối đa 100 thư; còn nữa thì có next_cursor.

curl

curl -G https://freedomainmail.com/api/v1/messages \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com" \
  --data-urlencode "limit=20"

200 OK

{
  "messages": [
    {
      "id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
      "recipient": "qa.signup@inboxlumo.com",
      "domain": "inboxlumo.com",
      "from_address": "security@facebookmail.com",
      "from_name": "Facebook",
      "subject": "Your confirmation code is 482913",
      "received_at": "2026-10-31T08:01:12.000Z",
      "expires_at": "2026-11-07T08:01:12.000Z",
      "otp_code": "482913",
      "primary_link": null
    }
  ],
  "next_cursor": null
}

GET `/api/v1/messages/{id}`

Đọc đầy đủ một thư: nội dung text, HTML đã làm sạch, header, thông tin tệp đính kèm và các link tách được. Ảnh từ xa trong HTML bị chặn mặc định; thêm ?images=1 để giữ.

200 OK

{
  "message": {
    "id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
    "recipient": "qa.signup@inboxlumo.com",
    "domain": "inboxlumo.com",
    "from_address": "security@facebookmail.com",
    "from_name": "Facebook",
    "subject": "Your confirmation code is 482913",
    "received_at": "2026-10-31T08:01:12.000Z",
    "expires_at": "2026-11-07T08:01:12.000Z",
    "otp_code": "482913",
    "primary_link": null,
    "text": "Your confirmation code is 482913.",
    "html": "<p>Your confirmation code is 482913.</p>",
    "blocked_images": 0,
    "headers": { "message-id": "<abc@mail.facebookmail.com>" },
    "attachments": [],
    "links": []
  }
}

DELETE `/api/v1/messages/{id}` · `/api/v1/messages?address=`

Xoá một thư (trả về 204 No Content), hoặc xoá mọi thư của một địa chỉ — tiện để làm sạch hộp thư giữa các lần chạy test. Địa chỉ vẫn được giữ.

curl

curl -X DELETE -G https://freedomainmail.com/api/v1/messages \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com"

200 OK

{ "deleted": 3 }

GET `/api/v1/code`

Chờ và trả về mã OTP mới nhất gửi tới một địa chỉ. Bắt buộc có address.

wait: số giây chờ, 0–60 (lớn hơn sẽ tính là 60). Lệnh trả về ngay khi thư có mã tới; hết giờ → 404 not_found.
since: chỉ lấy thư nhận từ thời điểm này — đặt bằng lúc bạn bấm “Gửi mã” để không lấy nhầm mã cũ.
pattern (tuỳ chọn): khi mã không được tự nhận ra, chỉ chỗ mã nằm trong thư bằng {code} (3–16 chữ/số) hoặc {digits} (3–12 chữ số). Ví dụ thư có key là : 5599292 → pattern=key là : {code} trả về 5599292. Không phải regex, không phân biệt hoa thường, tối đa 200 ký tự.

curl

curl -G https://freedomainmail.com/api/v1/code \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com" \
  --data-urlencode "wait=30" \
  --data-urlencode "pattern=key là : {code}"

200 OK

{
  "code": "482913",
  "message_id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
  "from": "security@facebookmail.com",
  "subject": "Your confirmation code is 482913",
  "received_at": "2026-10-31T08:01:12.000Z"
}

GET `/api/v1/links`

Giống /code (cùng address, wait, since) nhưng chờ và trả về link xác minh mới nhất. primary là link chúng tôi đoán là link xác nhận; links là mọi link xác minh tìm được.

curl

curl -G https://freedomainmail.com/api/v1/links \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com" \
  --data-urlencode "wait=30"

200 OK

{
  "primary": "https://yourapp.example/verify?token=abc123",
  "links": ["https://yourapp.example/verify?token=abc123"],
  "message_id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
  "received_at": "2026-10-31T08:01:12.000Z"
}

5. Bộ lọc dùng chung

GET /messages, /code và /links dùng chung các tham số dưới đây. /code và /links luôn trả về đúng 1 thư mới nhất nên bỏ qua limit và cursor.

Tham số	Ý nghĩa
`address`	Địa chỉ nhận đầy đủ, ví dụ qa.signup@inboxlumo.com.
`domain`	Chỉ lấy thư của một tên miền.
`from`	Người gửi. Địa chỉ đầy đủ → khớp chính xác. Chỉ tên miền → khớp tên miền đó và tên miền con: `from=facebookmail.com` khớp `security@facebookmail.com`, nhưng `from=facebook.com` không khớp `@facebookmail.com`.
`subject`	Tiêu đề có chứa chuỗi này (không phân biệt hoa thường).
`q`	Tìm trong tiêu đề, người gửi, tên người gửi và địa chỉ nhận.
`since`	Thời điểm ISO 8601 (2026-10-31T08:00:00Z) hoặc Unix time (giây hoặc mili-giây). Chỉ lấy thư nhận từ lúc này. So với giờ server lúc nhận thư, nên trừ hao vài giây nếu đồng hồ máy bạn lệch.
`limit`	Số thư mỗi trang, tối đa 100, mặc định 50. Chỉ cho GET /messages.
`cursor`	Gửi lại next_cursor của lần trước để lấy trang tiếp. Chỉ cho GET /messages.

6. Ví dụ hoàn chỉnh

Kịch bản: kiểm thử luồng đăng ký có mã OTP. Dùng lại một địa chỉ đã tạo (biến FDM_ADDRESS), ghi lại thời điểm bắt đầu (since), bấm gửi mã trên trang của bạn, rồi chờ mã tối đa 30 giây.

import os
import sys
import time
import requests

API = "https://freedomainmail.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["FDM_KEY"]}
ADDRESS = os.environ["FDM_ADDRESS"]  # ví dụ ci.signup@inboxlumo.com

# 1. Ghi lại thời điểm bắt đầu để không lấy nhầm mã cũ
since = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

# 2. ... điền ADDRESS vào form đăng ký và bấm "Gửi mã" trên trang của bạn ...

# 3. Chờ mã tối đa 30 giây
response = requests.get(
    API + "/code",
    headers=HEADERS,
    params={"address": ADDRESS, "since": since, "wait": 30},
    timeout=40,
)
if response.status_code == 200:
    print("Mã:", response.json()["code"])
elif response.status_code == 404:
    sys.exit("Chưa có mã sau 30 giây")
elif response.status_code == 429:
    sys.exit("Gọi quá nhanh, chờ " + response.headers.get("Retry-After", "?") + "s")
else:
    error = response.json()["error"]
    sys.exit(f"{response.status_code} {error['code']}: {error['message']}")

Tạo địa chỉ một lần, dùng mãi

Chạy một lần để lấy địa chỉ cho biến FDM_ADDRESS. Thư cũ không làm sai kết quả vì mỗi lần chạy đều lọc bằng since.

bash

curl -s -X POST https://freedomainmail.com/api/v1/addresses \
  -H "Authorization: Bearer $FDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "inboxlumo.com", "name": "ci.signup"}' | grep -o '"address":"[^"]*"'

export FDM_ADDRESS="ci.signup@inboxlumo.com"

7. Giới hạn

60 request mỗi phút cho mỗi khóa. Vượt quá → 429 rate_limited kèm header Retry-After (số giây cần chờ).
5 lệnh wait chạy cùng lúc cho mỗi khóa. Lệnh thứ 6 → 429 too_many_waits.
Khóa sai bị đếm theo IP: 20 lần sai trong 1 phút thì mọi request từ IP đó (kể cả khóa đúng) bị 429 tới hết phút.
Địa chỉ thành viên: giữ tối đa 100 địa chỉ, tạo mới tối đa 20 địa chỉ mỗi ngày cho mỗi tài khoản (40 mỗi IP). Tên đã xoá bị khoá 90 ngày.
Thư địa chỉ thành viên giữ 7 ngày, thư tên miền riêng giữ 30 ngày, sau đó tự xoá.

8. Lỗi và cách xử lý

Mọi lỗi có cùng dạng JSON:

{
  "error": {
    "code": "not_found",
    "message": "No matching message."
  }
}

HTTP	Mã lỗi	Nghĩa là / nên làm gì
401	`unauthorized`	Thiếu khóa, sai khóa hoặc khóa đã bị thu hồi. Kiểm tra header Authorization.
404	`not_found`	Chưa có thư phù hợp, hết thời gian wait, hoặc địa chỉ không thuộc tài khoản. Gọi lại hoặc kiểm tra địa chỉ.
400	`invalid_request`	Tham số thiếu hoặc sai định dạng (ví dụ thiếu address, since sai, pattern sai).
429	`rate_limited`	Gọi quá nhanh. Chờ đúng số giây trong header Retry-After.
429	`too_many_waits`	Quá 5 lệnh wait cùng lúc cho một khóa. Chạy ít song song hơn hoặc dùng thêm khóa.
409 / 400 / 429	`name_taken`, `name_busy`, `name_invalid`, `limit_reached`, `daily_limit`	Chỉ khi tạo địa chỉ — xem POST /addresses.
500	`internal_error`	Lỗi phía chúng tôi. Có thể gọi lại an toàn.

9. Câu hỏi thường gặp

Vì sao /code trả về 404?

Thường là thư chưa tới trong thời gian wait (hãy tăng wait hoặc gọi lại), since đặt muộn hơn lúc thư tới, gõ sai địa chỉ, hoặc địa chỉ không thuộc tài khoản của khóa này. Mở Hộp thư thành viên trên web để xem thư đã về chưa.

Mã OTP có trong thư nhưng /code không nhận ra?

Thêm tham số pattern để chỉ chỗ mã nằm, ví dụ pattern=Mã của bạn: {code}. Hoặc đọc thư bằng GET /messages/{id} và tự tách mã.

Có gửi thư bằng API được không?

Không. Dịch vụ chỉ nhận thư, không bao giờ gửi thư đi.

Một khóa API dùng cho mấy địa chỉ?

Mọi địa chỉ thành viên bạn giữ và mọi địa chỉ trên tên miền riêng của bạn. Có thể tạo tối đa 10 khóa, ví dụ mỗi môi trường CI một khóa.

Lộ khóa API thì làm sao?

Vào trang Khóa API, bấm Thu hồi khóa đó rồi tạo khóa mới. Khóa đã thu hồi ngừng hoạt động ngay.

Thư giữ bao lâu?

7 ngày với địa chỉ thành viên, 30 ngày với tên miền riêng. Muốn xoá sớm thì dùng DELETE /messages.

10. Quy định sử dụng

Chỉ dùng API cho mục đích kiểm thử và bảo vệ quyền riêng tư hợp pháp: QA, kiểm thử luồng đăng ký, lấy mã OTP hay link xác minh tự động. Dùng API để lừa đảo hoặc vi phạm điều khoản của bên thứ ba sẽ bị khoá tài khoản. Xem đầy đủ quy định sử dụng.

Hướng dẫn dùng API

1. Bắt đầu nhanh (3 bước)

Bước 1 — Lấy khóa API

Bước 2 — Tạo một địa chỉ

Bước 3 — Chờ mã OTP

2. Địa chỉ thành viên và tên miền riêng

3. Xác thực

4. Danh sách endpoint

GET /api/v1/addresses

POST /api/v1/addresses

DELETE /api/v1/addresses/{id}

GET /api/v1/domains

GET /api/v1/messages

GET /api/v1/messages/{id}

DELETE /api/v1/messages/{id} · /api/v1/messages?address=

GET /api/v1/code

GET /api/v1/links

5. Bộ lọc dùng chung

6. Ví dụ hoàn chỉnh

Tạo địa chỉ một lần, dùng mãi

7. Giới hạn

8. Lỗi và cách xử lý

9. Câu hỏi thường gặp

10. Quy định sử dụng

GET `/api/v1/addresses`

POST `/api/v1/addresses`

DELETE `/api/v1/addresses/{id}`

GET `/api/v1/domains`

GET `/api/v1/messages`

GET `/api/v1/messages/{id}`

DELETE `/api/v1/messages/{id}` · `/api/v1/messages?address=`

GET `/api/v1/code`

GET `/api/v1/links`