Tài liệu tham khảo API

Tổng quan

Một hộp thư không bao giờ được tạo ra — nó tồn tại ngay khi một thư đến một địa chỉ, và biến mất 5 ngày sau đó. Không có gì để đăng ký, nên trên các tên miền công khai API không có khái niệm người dùng, dự án hay token.

• Mọi phản hồi đều là JSON, kể cả mọi lỗi.
• Mọi thời gian đều theo UTC ở dạng RFC 3339 — 2026-08-04T18:31:07Z.
• ID tin nhắn là chuỗi không có ý nghĩa cụ thể. Đừng phân tích chúng.
• Chỉ nhận. Không có endpoint nào để gửi thư, đây là chủ đích thiết kế.

URL cơ sở

Chỉ HTTPS; HTTP thuần được chuyển hướng. Phiên bản nằm trong đường dẫn, và v1 sẽ không thay đổi cấu trúc bất ngờ — một thay đổi phá vỡ tương thích sẽ nhận một số mới.

Xác thực: không cần

Không có gì trên các tên miền công khai. Bất kỳ ai biết một địa chỉ đều có thể đọc hộp thư của nó, qua API cũng như qua trang web. Đó là thỏa thuận của một dịch vụ dùng chung, tạm thời, nên đừng bao giờ gắn địa chỉ công khai cho bất cứ điều gì bạn quan tâm.

Một tên miền bạn trỏ về đây sẽ trả lời qua cùng các endpoint này, cũng không cần khóa nào cả. Trỏ MX về chúng tôi và thư đầu tiên sẽ kết nối nó; xem kết nối một tên miền. Các hộp thư trên đó có thể được đọc bởi bất kỳ ai biết địa chỉ, giống hệt như các tên miền công khai.

Có một trường hợp vẫn cần một header: một tên miền mà chúng tôi đã đóng theo yêu cầu sẽ được đọc bằng Authorization: Bearer <key>, và một khóa sai hoặc thiếu sẽ trả về 401 kèm unauthorized. Các khóa được so sánh trong thời gian không đổi, nên một khóa sai mất thời gian bị từ chối bằng thời gian một khóa đúng được chấp nhận.

Tên miền premium

Ngoại lệ duy nhất của quy tắc trên. Các tên miền công khai nằm trong danh sách chặn thư dùng một lần, nên biểu mẫu đăng ký đôi khi từ chối địa chỉ trên đó. Gói trả phí mở một pool gồm 92 tên miền .com riêng, được giữ ngoài các danh sách đó.

API không thay đổi gì cả. Cùng đường dẫn, cùng tham số, cùng dạng phản hồi. Khác biệt duy nhất là một header: địa chỉ premium được đọc bằng Authorization: Bearer gm_live_…, với khóa từ khóa API của bạn. Không có khóa hợp lệ, cùng yêu cầu đó trả về 402 hoặc 403 — không bao giờ là hộp thư.

# A public domain: no header at all.
curl -sG https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=a7f3k2@grabmail.io"

# A premium domain: the same call, plus a key.
curl -sG https://grabmail.io/api/v1/mailbox \
  -H "Authorization: Bearer gm_live_…" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

Các tên miền công cộng và tên miền của riêng bạn vẫn miễn phí, không cần khóa và không giới hạn ở mọi gói, kể cả gói miễn phí. Hạn mức chỉ tính các thư đến pool premium. Các gói và giá có trên trang các gói.

Các endpoint

$ curl -G https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=k7fq2m@grabmail.io"

{
  "address": "k7fq2m@grabmail.io",
  "count": 1,
  "next": null,
  "messages": [
    {
      "id": "01JR8W2K4Q",
      "from": "no-reply@example.com",
      "subject": "Your verification code",
      "date": "2026-08-04T18:31:07Z",
      "seen": false,
      "attachments": 0,
      "expires_at": "2026-08-09T18:31:07Z"
    }
  ]
}

$ curl -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "id": "01JR8W2K4Q",
  "from": "no-reply@example.com",
  "to": "k7fq2m@grabmail.io",
  "subject": "Your verification code",
  "date": "2026-08-04T18:31:07Z",
  "text": "Your code is 481920. It expires in 10 minutes.",
  "html": null,
  "attachments": []
}

$ curl -X DELETE -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "deleted": true,
  "id": "01JR8W2K4Q"
}

Tệp đính kèm

Mọi thư đều liệt kê tệp đính kèm của nó cùng một URL đã dựng sẵn. Hãy lấy tệp bằng cùng cách xác thực như với chính thư đó.

GET /api/v1/attachment/{id}?mailbox={address}

Nó luôn trả về application/octet-stream kèm Content-Disposition: attachment, dù người gửi gắn nhãn gì đi nữa. Đó là cố ý: lặp lại text/html của người lạ sẽ cho phép một tệp đính kèm chạy như một trang trên chính nguồn gốc này. Loại thật nằm trong JSON của thư, nơi nó là dữ liệu chứ không phải chỉ thị.

Lỗi

Mọi lỗi đều là JSON với cùng hai trường, nên client xử lý chúng ở một nơi duy nhất. Mã trạng thái mang loại lỗi, error là một slug ổn định để máy đọc, và message dành cho con người và có thể được viết lại bất cứ lúc nào.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "invalid_address",
  "message": "address must look like name@domain"
}

Đừng bao giờ rẽ nhánh dựa trên message. Các slug đang dùng là invalid_address, unknown_domain, not_found và rate_limited.

Giới hạn tần suất

Một yêu cầu mỗi giây, cho mỗi địa chỉ. Việc thăm dò hộp thư mỗi giây một lần là cách dùng dự kiến và không bao giờ bị giới hạn.

Vượt quá giới hạn bạn sẽ nhận 429 kèm Retry-After tính bằng giây. Không có hạn mức hằng ngày và không có tín dụng bùng nổ nào để quản lý.

Thời gian lưu trữ

Một thư bị xóa 5 ngày sau khi đến, dù đã đọc hay chưa. Mọi thư đều mang expires_at, nên bạn không bao giờ phải tự tính ngày đó.

Đây là giới hạn cứng, không phải một tùy chọn — không tham số nào kéo dài nó. Nếu một thư cần tồn tại lâu hơn khung thời gian đó, hãy lấy về và lưu trữ ở phía bạn.

Tên miền riêng của bạn

Trỏ MX của bạn tới smtp.grabmail.io và mọi địa chỉ trên tên miền của bạn sẽ trả lời qua cùng các endpoint này — không có API thứ hai để học, không cần đăng ký, và không cần khóa.

Kết nối một tên miền →