# Gửi qua SMTP relay

Kết nối WordPress, phần mềm bán hàng hoặc bất kỳ ứng dụng nào gửi email qua SMTP với Hạ Tầng bằng smtp.hatang.dev, cổng 5870 và một API key.

Nhiều công cụ gửi được email nhưng không gọi được API: WordPress và WooCommerce, phần mềm kế toán, phần mềm bán hàng, form liên hệ trên website, máy scan. Trỏ chúng tới SMTP relay của Hạ Tầng là email được gửi từ tên miền đã xác minh của bạn, với cùng cơ chế chuyển phát, theo dõi và nhật ký như mọi email khác. Mỗi thư hiện ở **Email → Email** kèm trạng thái.

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

- Một **tên miền gửi đã xác minh**. Relay chỉ nhận địa chỉ người gửi thuộc tên miền đã xác minh trong doanh nghiệp của bạn. Xem [Thêm và xác minh tên miền gửi](https://hatang.dev/vi/help/email/add-domain).
- Một **API key có quyền Gửi**. Key này chính là mật khẩu SMTP. Tạo key cần quyền **Developer** trong doanh nghiệp; xem [API key](https://hatang.dev/vi/help/integrations/api-keys).

## Thông số kết nối

| Thông số | Giá trị |
|---|---|
| Máy chủ SMTP (host) | `smtp.hatang.dev` |
| Cổng | `5870` |
| Mã hoá | **STARTTLS** (một số ứng dụng gọi là "TLS") |
| Tên đăng nhập | `hatang` |
| Mật khẩu | API key của bạn (bắt đầu bằng `ht_`) |
| Xác thực | Bật (`PLAIN` hoặc `LOGIN`) |

Host, cổng, tên đăng nhập và **Mã hoá** (**STARTTLS**) cũng có ở **Email → Cài đặt email → Thông tin kết nối**, kèm khối cấu hình để sao chép. Trong mã nguồn, STARTTLS nghĩa là `secure: false` (`SMTP_SECURE=false`): kết nối vẫn được mã hoá, chỉ là bắt đầu bằng kết nối thường.

> [!WARNING]
> Cổng 5870 bắt đầu bằng kết nối thường rồi nâng cấp lên mã hoá bằng STARTTLS. Đừng chọn **SSL**, **implicit TLS** hay tuỳ chọn kết nối "secure": ứng dụng sẽ chờ một lời chào đã mã hoá không bao giờ tới và báo quá thời gian. Hạ Tầng không mở cổng 465 hay 587; hãy dùng 5870.

Relay từ chối đăng nhập khi kết nối chưa được mã hoá, nên API key của bạn không bao giờ đi qua mạng ở dạng đọc được.

## Tạo key

1. Mở **Email → API Keys** và bấm **Tạo key**.
2. Đặt tên theo ứng dụng sẽ dùng key, ví dụ `Website WordPress`.
3. Trong **Key này có thể làm gì**, chỉ tích **Gửi** của Email. Key chỉ có quyền gửi thì dù bị lộ cũng không đọc được danh sách liên hệ hay sửa tên miền của bạn.
4. Nếu muốn, giới hạn **Tên miền gửi** ở đúng tên miền ứng dụng này dùng.
5. Bấm **Tạo key** và sao chép key ngay: key sẽ không hiển thị lại.

Mỗi ứng dụng nên có key riêng, để khi cần thu hồi một key thì các ứng dụng khác không bị ảnh hưởng.

## WordPress với WP Mail SMTP

1. Cài plugin **WP Mail SMTP** rồi mở **WP Mail SMTP → Settings**.
2. Đặt **From Email** là một địa chỉ thuộc tên miền đã xác minh, ví dụ `don-hang@mochuong.vn`, và bật **Force From Email**.
3. Ở **Mailer**, chọn **Other SMTP**.
4. Điền:

   | Ô | Giá trị |
   |---|---|
   | SMTP Host | `smtp.hatang.dev` |
   | Encryption | **TLS** (trong WP Mail SMTP đây chính là STARTTLS) |
   | SMTP Port | `5870` |
   | Auto TLS | Bật |
   | Authentication | Bật |
   | SMTP Username | `hatang` |
   | SMTP Password | API key của bạn |

5. Lưu, rồi gửi thử ở **WP Mail SMTP → Tools → Email Test**.

Vài giây sau, thư thử hiện ở **Email → Email**. Từ đó email đơn hàng của WooCommerce cũng đi qua Hạ Tầng.

## Ứng dụng khác

Tìm phần cài đặt "SMTP", "thư đi" hoặc "máy chủ thư" và nhập các giá trị trong bảng trên. Những điểm cần kiểm tra:

- **Địa chỉ người gửi**: luôn là địa chỉ thuộc tên miền đã xác minh. Ứng dụng gửi bằng `wordpress@tenhosting` hay `root@localhost` sẽ bị từ chối cho tới khi bạn đổi địa chỉ.
- **Mã hoá**: STARTTLS hoặc "TLS", không dùng SSL.
- **Người nhận**: luôn có ít nhất một địa chỉ ở ô **To**. Nếu thư chỉ có người nhận Bcc, Hạ Tầng chuyển người đầu tiên sang **To**, và những người còn lại sẽ thấy địa chỉ đó.

Lập trình viên có sẵn cấu hình cho Laravel, Django, Rails, Spring Boot, Nodemailer, PHPMailer và Postfix trong [hướng dẫn SMTP ở trang dành cho lập trình viên](https://hatang.dev/vi/docs/guides/email/smtp).

## Giới hạn

| Giới hạn | Giá trị |
|---|---|
| Người nhận mỗi thư | 50 |
| Dung lượng thư | 40 MB |
| Đăng nhập sai | Sau 10 lần đăng nhập sai từ một địa chỉ IP, địa chỉ đó bị từ chối đăng nhập trong 15 phút |
| Hạn mức hằng ngày | Dùng chung với mọi email khác bạn gửi: mỗi thư tính là một email. Xem **Cài đặt email** |

## Khi không gửi được

| Ứng dụng báo | Nguyên nhân | Cách xử lý |
|---|---|---|
| Quá thời gian kết nối | Sai cổng, hoặc chọn SSL/implicit TLS | Dùng cổng `5870` với STARTTLS |
| `535` xác thực thất bại | Mật khẩu không phải API key hợp lệ, hoặc key đã bị thu hồi | Dán lại key, hoặc tạo key mới |
| `421` quá nhiều lần xác thực sai | 10 lần đăng nhập sai từ địa chỉ máy chủ của bạn | Sửa mật khẩu, chờ 15 phút rồi thử lại |
| `550` kèm "domain is not verified" | Địa chỉ người gửi không thuộc tên miền đã xác minh của doanh nghiệp này | Xác minh tên miền, hoặc đổi địa chỉ người gửi |
| `550` kèm "does not have the email:send scope" | Key không có quyền **Gửi** | Tạo key có quyền **Gửi** |
| `550` vì đang tạm dừng gửi | Có người đã tạm dừng gửi ở **Cài đặt email** | Bấm **Tiếp tục gửi** khi đã an toàn |
| `452` quá nhiều người nhận | Một thư có hơn 50 người nhận | Tách thành nhiều thư |
| `451` lỗi tạm thời | Sự cố tạm thời, ví dụ đã dùng hết hạn mức trong ngày | Thử lại sau; các máy chủ thư tự thử lại |

Mọi thư relay đã nhận đều có trong **Email → Email** với nguồn **SMTP**. Nếu không thấy thư ở đó, ứng dụng chưa hề kết nối được tới Hạ Tầng: xem nhật ký của ứng dụng để tìm một trong các mã lỗi ở trên.