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

> **Tip: 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ợ](https://hatang.dev/vi/help/channels/email-channel) 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](https://hatang.dev/vi/docs/guides/email/domains.md).
- 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](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md).

## 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**

```bash
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**

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

**Python**

```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**

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

> **Caution: 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ư:

```json
{
  "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 <lan@example.vn>",
    "to": ["hotro@shop.vn"],
    "cc": [],
    "bcc": [],
    "message_id": "<CAF=abc@mail.gmail.com>",
    "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](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md).

## 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**

```bash
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**

```ts
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**

```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**

```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](https://hatang.dev/vi/docs/guides/email/groups.md): chuyển thư tới một địa chỉ như team@congty.vn cho nhiều người
- [Webhook](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md)
- [Kênh Email hỗ trợ](https://hatang.dev/vi/help/channels/email-channel)
- [Tên miền](https://hatang.dev/vi/docs/guides/email/domains.md)

Source: https://hatang.dev/vi/docs/guides/email/receiving