Nhận email

Bật nhận email cho một tên miền đã xác minh, mọi thư gửi tới bất kỳ địa chỉ @ tên miền đó sẽ được Hạ Tầng lưu lại và báo cho bạn qua webhook email.received. Sau đó bạn đọc nội dung, header và tệp đính kèm qua API. Cách làm giống Resend Receiving, nên code viết cho Resend chỉ cần đổi base URL và key.

Hỗ trợ khách qua email?

Nếu muốn cả đội đọc và trả lời thư của khách trong một hộp thư chung, dùng kênh Email hỗ trợ thay vì tự xử lý webhook.

Trước khi bắt đầu

• Một tên miền đã xác minh. Xem Tên miền.
• API key được cấp trực tiếp email:read hoặc email:write. Key chỉ có email:send không đọc được thư đến, vì đó là thư của người khác.
• Một endpoint nhận webhook. Xem Webhook.

1. Bật nhận email

Trong dashboard, mở Email → Tên miền, chọn tên miền và bật Nhận email. Hoặc dùng API:

cURL

curl -X PATCH https://api.hatang.dev/domains/$DOMAIN_ID \
  -H "Authorization: Bearer $HATANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "capabilities": { "receiving": "enabled" } }'

Node.js

await hatang.domains.update({ id: domainId, capabilities: { receiving: "enabled" } });

Python

requests.patch(
    f"https://api.hatang.dev/domains/{domain_id}",
    headers={"Authorization": f"Bearer {os.environ['HATANG_API_KEY']}"},
    json={"capabilities": {"receiving": "enabled"}},
)

PHP

$client->patch("/domains/$domainId", [
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
    'json' => ['capabilities' => ['receiving' => 'enabled']],
]);

2. Thêm bản ghi MX

Bảng bản ghi của tên miền có thêm dòng Nhận thư: một bản ghi MX ưu tiên 10 đặt trên chính tên miền. Thêm bản ghi đó ở nhà cung cấp DNS. Hạ Tầng kiểm tra bản ghi này cùng các bản ghi khác; nó không ảnh hưởng tới việc gửi.

Tên miền đang nhận thư ở nơi khác

Bản ghi MX quyết định toàn bộ thư của tên miền đi đâu. Hạ Tầng không cho bật nhận email với tên miền có MX đang trỏ tới dịch vụ thư khác (Google Workspace, Microsoft 365…), để bạn không mất hộp thư hiện có, và với tên miền mà một hộp thư hỗ trợ trong Chat đang nhận. Hãy thêm một tên miền phụ như inbound.shop.vn ở Email → Tên miền, xác minh, rồi nhận thư ở đó.

3. Xử lý webhook email.received

Tạo webhook (mục Webhooks trong dashboard, hoặc POST /webhooks) đăng ký sự kiện email.received. Webhook chỉ mang thông tin tóm tắt, không có nội dung thư:

{
  "type": "email.received",
  "created_at": "2026-10-14T09:12:03.000Z",
  "data": {
    "email_id": "0199e6c1-7a2b-7f00-9c1e-3f6a2b1d9e10",
    "created_at": "2026-10-14T09:12:03.000Z",
    "from": "Trần Lan <[email protected]>",
    "to": ["[email protected]"],
    "cc": [],
    "bcc": [],
    "message_id": "<[email protected]>",
    "subject": "Đơn #1024 chưa nhận được",
    "attachments": [
      { "id": "att_…", "filename": "hoa-don.pdf", "content_type": "application/pdf", "content_disposition": "attachment", "content_id": null, "size": 48213 }
    ]
  }
}

• bcc là các địa chỉ trên tên miền của bạn đã nhận thư mà không có trong To hay Cc.
• Thư bị dịch vụ nhận thư đánh dấu là spam vẫn được lưu (có spam: true khi đọc) nhưng không bắn webhook, giống thư mục spam. Thư có virus bị bỏ.
• Webhook được ký như mọi webhook khác của Hạ Tầng. Hãy xác minh chữ ký trước khi tin; xem Webhook.

4. Đọc thư

Endpoint	Trả về
GET /emails/receiving	Danh sách thư đến, mới nhất trước (limit, after, before).
GET /emails/receiving/{id}	Một thư: text, html, headers, reply_to, in_reply_to, spam và các tệp đính kèm.
GET /emails/receiving/{id}/attachments	Các tệp đính kèm, mỗi tệp có download_url.
GET /emails/receiving/{id}/attachments/{attachment_id}	Một tệp kèm download_url.

cURL

curl https://api.hatang.dev/emails/receiving/$EMAIL_ID -H "Authorization: Bearer $HATANG_API_KEY"
curl https://api.hatang.dev/emails/receiving/$EMAIL_ID/attachments -H "Authorization: Bearer $HATANG_API_KEY"

Node.js

import { Hatang } from "@hatang/sdk";

const hatang = new Hatang(process.env.HATANG_API_KEY, { baseUrl: "https://api.hatang.dev" });

// Trong handler của webhook email.received:
const { data: email } = await hatang.emails.receiving.get(event.data.email_id);
console.log(email.subject, email.text);

const { data: files } = await hatang.emails.receiving.attachments.list(email.id);
for (const file of files.data) {
  const res = await fetch(file.download_url!);
  // lưu res.body vào nơi lưu trữ của bạn
}

Python

headers = {"Authorization": f"Bearer {os.environ['HATANG_API_KEY']}"}
email = requests.get(f"https://api.hatang.dev/emails/receiving/{email_id}", headers=headers).json()
files = requests.get(f"https://api.hatang.dev/emails/receiving/{email_id}/attachments", headers=headers).json()
for f in files["data"]:
    content = requests.get(f["download_url"]).content

PHP

$headers = ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')];
$email = json_decode($client->get("/emails/receiving/$emailId", ['headers' => $headers])->getBody(), true);
$files = json_decode($client->get("/emails/receiving/$emailId/attachments", ['headers' => $headers])->getBody(), true);

download_url tải được mà không cần API key và hết hạn một giờ sau khi bạn lấy (expires_at), nên có thể chuyển thẳng cho trình duyệt hay một worker khác. Gọi lại endpoint tệp đính kèm để lấy URL mới.

Trong dashboard, thư đến nằm ở Email → Email → Nhận về.

Lưu trữ

Thư đến và tệp đính kèm được giữ 30 ngày rồi tự xoá. Muốn giữ lâu hơn, hãy chép sang nơi lưu trữ của bạn khi nhận webhook.

Bước tiếp theo

• Nhóm email: chuyển thư tới một địa chỉ như [email protected] cho nhiều người
• Webhook
• Kênh Email hỗ trợ
• Tên miền