# Hạ Tầng Email

Hạ Tầng Email gửi email giao dịch và email marketing từ chính tên miền của bạn. API giống hệt Resend, nên code đang dùng Resend chỉ cần đổi base URL và API key là chạy; thư được gửi đi qua Amazon SES. Trang này giải thích các thành phần ghép với nhau thế nào và hướng dẫn bạn gửi email đầu tiên.

## Bạn có gì

| Tính năng | Làm được gì | Hướng dẫn |
|---|---|---|
| Tên miền gửi | DKIM, SPF và return path riêng cho từng tên miền, cấu hình DNS một chạm ở các nhà cung cấp DNS hỗ trợ | [Tên miền](https://hatang.dev/vi/docs/guides/email/domains.md) |
| REST API | `POST /emails` và `POST /emails/batch`, hẹn giờ, idempotency, tag, tệp đính kèm | [Gửi email](https://hatang.dev/vi/docs/guides/email/sending.md) |
| SMTP relay | `smtp.hatang.dev:5870` dùng STARTTLS, cho framework và ứng dụng chỉ biết gửi qua SMTP | [SMTP relay](https://hatang.dev/vi/docs/guides/email/smtp.md) |
| Templates | Mẫu email có biến, gửi bằng id hoặc alias | [Templates](https://hatang.dev/vi/docs/guides/email/templates.md) |
| Theo dõi | Theo dõi lượt mở và lượt nhấp, có thể dùng tên miền phụ của bạn | [Theo dõi mở và nhấp](https://hatang.dev/vi/docs/guides/email/tracking.md) |
| Nhận email | Thư gửi tới tên miền của bạn thành webhook `email.received` | [Nhận email](https://hatang.dev/vi/docs/guides/email/receiving.md) |
| Danh sách nhận | Contact, segment, topic và thuộc tính tuỳ chỉnh | [Contacts, segments và topics](https://hatang.dev/vi/docs/guides/email/audiences.md) |
| Chiến dịch email | Email marketing gửi tới một segment, gửi ngay hoặc hẹn giờ, kèm trang tuỳ chọn nhận thư | [Chiến dịch email](https://hatang.dev/vi/docs/guides/email/broadcasts.md) |
| Automations | Chuỗi email cho từng contact, khởi động bằng sự kiện từ ứng dụng của bạn | [Automations](https://hatang.dev/vi/docs/guides/email/automations.md) |
| Danh sách chặn | Thư trả lại cứng, báo spam và huỷ đăng ký tự động chặn các lần gửi sau | [Danh sách chặn và thư trả lại](https://hatang.dev/vi/docs/guides/email/suppressions-and-bounces.md) |
| Số liệu và logs | Tỉ lệ tới hộp thư, mở, nhấp, bị trả lại, bị báo spam, cùng log mọi lệnh gọi API | [Số liệu và logs](https://hatang.dev/vi/docs/guides/email/metrics-and-logs.md) |

## Một email đi qua những đâu

```mermaid
flowchart LR
  A[Ứng dụng của bạn] -->|REST API hoặc SMTP| B[Hạ Tầng]
  B -->|kiểm tra: tên miền đã xác minh, danh sách chặn, hạn mức ngày| C[Hàng đợi gửi]
  C -->|ký DKIM bằng tên miền của bạn| D[Amazon SES]
  D --> E[Hộp thư người nhận]
  D -->|đã tới, bị trả lại, bị báo spam| B
  B -->|webhook| A
```

1. Ứng dụng gọi `POST /emails` hoặc gửi thư qua SMTP relay. Cả hai đi qua cùng một lớp kiểm tra.
2. Hạ Tầng kiểm tra tên miền của `From` đã xác minh và thuộc doanh nghiệp của bạn, bỏ qua người nhận nằm trong danh sách chặn và trừ một email vào hạn mức ngày. Hạ Tầng trả về `id` của email ngay lập tức.
3. Worker ký thư bằng khoá DKIM của tên miền, đặt địa chỉ nhận thư trả lại trên tên miền phụ return path (mặc định `send.`) rồi chuyển thư cho Amazon SES.
4. Amazon SES báo lại cho Hạ Tầng thư đã tới, bị trả lại hay bị báo spam. Hạ Tầng cập nhật trạng thái email, đưa địa chỉ trả lại cứng và báo spam vào danh sách chặn, rồi gửi webhook cho bạn.

## Trước khi bắt đầu

- Một doanh nghiệp trên Hạ Tầng đã bật module **Email**. Xem [Doanh nghiệp và module](https://hatang.dev/vi/help/getting-started/modules).
- Một tên miền bạn thêm được bản ghi DNS.
- Một API key. Xem [Xác thực](https://hatang.dev/vi/docs/guides/getting-started/authentication.md).

## Gửi email đầu tiên

### 1. Thêm và xác minh tên miền

Trong dashboard, mở **Email → Tên miền**, thêm tên miền (ví dụ `example.com` hoặc tên miền phụ như `updates.example.com`), thêm các bản ghi DNS được hiển thị rồi bấm **Xác minh bản ghi DNS**. Tên miền phải ở trạng thái **Đã xác minh** thì mới gửi được. Chi tiết ở trang [Tên miền](https://hatang.dev/vi/docs/guides/email/domains.md).

### 2. Tạo API key

Tạo key có phạm vi `email:send`. Chỉ giữ key trên server, không bao giờ đưa vào trình duyệt hay ứng dụng di động.

### 3. Gửi

**cURL**

```bash
curl -X POST https://api.hatang.dev/emails \
  -H "Authorization: Bearer $HATANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Shop <hello@shop.vn>",
    "to": ["khach@example.vn"],
    "subject": "Xác nhận đơn hàng",
    "html": "<p>Cảm ơn bạn đã đặt hàng!</p>"
  }'
```

**Node.js**

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

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

const { data, error } = await hatang.emails.send({
  from: "Shop <hello@shop.vn>",
  to: ["khach@example.vn"],
  subject: "Xác nhận đơn hàng",
  html: "<p>Cảm ơn bạn đã đặt hàng!</p>",
});
if (error) throw new Error(`${error.name}: ${error.message}`);
console.log(data.id);
```

**Python**

```python
from hatang import Hatang  # pip install hatang

hatang = Hatang()  # đọc HATANG_API_KEY
email = hatang.emails.send({
    "from": "Shop <hello@shop.vn>",
    "to": ["khach@example.vn"],
    "subject": "Xác nhận đơn hàng",
    "html": "<p>Cảm ơn bạn đã đặt hàng!</p>",
})
print(email["id"])
```

**PHP**

```php
<?php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.hatang.dev']);

$res = $client->post('/emails', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
    'json' => [
        'from' => 'Shop <hello@shop.vn>',
        'to' => ['khach@example.vn'],
        'subject' => 'Xác nhận đơn hàng',
        'html' => '<p>Cảm ơn bạn đã đặt hàng!</p>',
    ],
]);
echo json_decode($res->getBody(), true)['id'];
```

Response chứa id của email:

```json
{ "id": "0199e6c1-7a2b-7f00-9c1e-3f6a2b1d9e10" }
```

> **Note**
>
> SDK Node.js trả về `{ data, error }` và không bao giờ ném lỗi. Luôn truyền `baseUrl: "https://api.hatang.dev"` (hoặc đặt biến `HATANG_BASE_URL`), vì giá trị mặc định có sẵn trong SDK trỏ tới server phát triển ở máy local.

### 4. Theo dõi email

- Trong dashboard, **Email → Email** liệt kê mọi email kèm trạng thái, người nhận và sự kiện.
- `GET /emails/{id}` trả về email và `status`; `GET /emails/{id}/events` trả về từng sự kiện và trạng thái của từng người nhận.
- Muốn nhận cập nhật tức thì, đăng ký webhook cho `email.delivered`, `email.bounced` và các sự kiện khác. Xem [Webhook](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md).

## Các mục trong dashboard

| Mục trên thanh bên | Bạn làm gì ở đó |
|---|---|
| **Email** | Mọi email gửi qua API, SMTP relay hoặc chiến dịch email. Tab **Nhận về** liệt kê thư nhận được trên tên miền của bạn. |
| **Chiến dịch email** | Soạn, hẹn giờ và gửi email marketing tới một segment. |
| **Templates** | Sửa, gửi thử và publish template. |
| **Danh sách nhận** | Contacts, segments, topics, thuộc tính và danh sách chặn. |
| **Automations** | Chuỗi email theo sự kiện và các lượt chạy. |
| **Số liệu** | Lượng thư và các tỉ lệ theo ngày. |
| **Tên miền** | Tên miền gửi và nhận, bản ghi DNS, theo dõi. |
| **Logs** | Mọi lệnh gọi API bằng key của bạn. |
| **API Keys** | Tạo và thu hồi API key. |
| **Webhooks** | Các endpoint nhận sự kiện email. |
| **Cài đặt email** | Thông tin kết nối SMTP, hạn mức ngày, nút tạm dừng khẩn cấp và trang huỷ đăng ký. |

## Phạm vi của API key

Chỉ cấp cho mỗi key những phạm vi mà hệ thống dùng key đó cần:

| Endpoint | Phạm vi bắt buộc |
|---|---|
| `POST /emails`, `POST /emails/batch`, SMTP relay | `email:send` |
| `PATCH /emails/{id}`, `POST /emails/{id}/cancel` | `email:send` |
| `GET /emails`, `GET /emails/{id}`, `GET /emails/{id}/events` | `email:read` (hoặc `email:send` / `email:write`, vốn đã bao gồm quyền đọc) |
| Tên miền, templates, contacts, segments, topics, chiến dịch email, sự kiện, automations | `email:write` |
| `GET /emails/metrics` | `email:read` (hoặc `email:send` / `email:write`, vốn đã bao gồm quyền đọc) |
| `GET /emails/receiving/*` | `email:read` hoặc `email:write`, cấp trực tiếp. Chỉ có `email:send` thì không đọc được thư đến. |
| `GET /logs`, `GET /usage` | Bất kỳ phạm vi ghi nào |

Key cũng có thể bị giới hạn vào một tên miền gửi. Khi gửi từ tên miền khác, key đó nhận lỗi `401 restricted_api_key`.

## Giới hạn chính

| Giới hạn | Giá trị |
|---|---|
| Tốc độ gọi REST API | 10 request mỗi giây cho mỗi doanh nghiệp, dùng chung cho các endpoint email |
| Người nhận mỗi email | 50, tính chung `to`, `cc` và `bcc` |
| Email mỗi lệnh batch | 100 |
| Kích thước email | 40 MB, gồm cả nội dung và tệp đính kèm |
| Hẹn giờ | Tối đa 30 ngày tới |
| Hạn mức ngày | Đặt riêng cho từng doanh nghiệp, đặt lại lúc nửa đêm UTC. Xem ở **Cài đặt email** hoặc `GET /usage`. |

Danh sách đầy đủ ở [Giới hạn](https://hatang.dev/vi/docs/reference/limits.md), mọi mã lỗi ở [Lỗi](https://hatang.dev/vi/docs/reference/errors.md).

## Bước tiếp theo

- [Tên miền](https://hatang.dev/vi/docs/guides/email/domains.md): cấu hình DKIM, SPF và DMARC.
- [Gửi email](https://hatang.dev/vi/docs/guides/email/sending.md): mọi trường của `POST /emails`.
- [SMTP relay](https://hatang.dev/vi/docs/guides/email/smtp.md): kết nối WordPress, Laravel, Django và các nền tảng khác.
- [Chuyển từ Resend](https://hatang.dev/vi/docs/guides/email/migrate-from-resend.md): những gì thay đổi khi bạn chuyển sang.

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