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ó 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.

Trên một tên miền bạn sở hữu, hộp thư là riêng tư, nên các yêu cầu phải mang theo khóa — đó là thứ chứng minh hộp thư là của bạn. Khóa được cấp khi bạn xác minh tên miền, chỉ hiển thị một lần, và ở đây chỉ lưu dưới dạng hash:

Authorization: Bearer <your key>

Khóa sai hoặc thiếu trên một tên miền riêng tư 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.

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, và các hộp thư chỉ có thể đọc bằng khóa của bạn.

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