Gửi email bằng Brevo API khi VPS chặn cổng SMTP
Gửi email xác thực từ VPS qua Brevo HTTP API v3 (HTTPS, port 443) thay cho SMTP bị chặn: xác thực sender và domain (DKIM, SPF), lấy đúng API key, cấu hình .env và xử lý các lỗi thường gặp.
Mục lục
Một số nhà cung cấp VPS (như DigitalOcean, Vultr, Linode) mặc định chặn các cổng SMTP (465, 587) để chống spam, nên gửi email qua SMTP thông thường (ví dụ Gmail SMTP) từ VPS sẽ thất bại với lỗi timeout hoặc connection refused. Bài này dùng Brevo HTTP API v3 - giao tiếp qua HTTPS port 443 nên không bị chặn - để gửi email xác thực thay cho SMTP, đồng thời khắc phục lỗi hiển thị sai địa chỉ email người gửi.
Trong toàn bài, example.com là tên miền của bạn, [email protected] và
[email protected] là địa chỉ email gửi, MyApp là tên ứng dụng, <account-id> và
<brevo-code> là các mã do Brevo tự sinh. Thay bằng giá trị thật của bạn.
Tóm tắt nhanh
- Đăng ký: tạo tài khoản miễn phí trên Brevo.
- Xác thực email gửi: vào
Senders, Domains & Dedicated IPs>Senders, thêm email gửi và bấm link xác nhận trong hộp thư. - Xác thực domain (nếu dùng email tên miền riêng): vào tab
Domains, thêm domain rồi khai báo 3 bản ghi DNS:TXT (DKIM),TXT (SPF)vàCNAME (Return-Path). - Lấy API key: menu Profile >
SMTP & API> tabAPI keys & MCP, bấmGenerate a new API key(mã có dạngxkeysib-...). KHÔNG lấy SMTP key. - Cấu hình app: cập nhật
.envvới API key vừa sinh, rồi khởi động lại Docker (docker compose downvàdocker compose up -d --build).
Bước 1: Đăng ký tài khoản Brevo
Brevo có gói miễn phí vĩnh viễn cho phép gửi 300 email/ngày - dư dả cho việc gửi OTP hay email xác thực tài khoản.
- Truy cập trang chủ brevo.com.
- Bấm Sign up free ở góc trên bên phải.
- Đăng ký bằng Google cho nhanh, hoặc đăng ký bằng email bình thường.
- Điền các thông tin cá nhân/công ty được yêu cầu (không bắt buộc thẻ tín dụng).
Bước 2: Xác thực người gửi (sender)
Brevo KHÔNG cho phép gửi email bằng API nếu bạn chưa chứng minh mình là chủ sở hữu của địa chỉ email gửi đi.
- Tại dashboard Brevo, vào mục Senders, Domains & Dedicated IPs (menu bên phải dưới cùng, hoặc ở góc trên bên phải).
- Chọn tab Senders.
- Bấm Add a sender (thêm người gửi).
- Nhập thông tin:
- From Name: tên hiển thị của người gửi, ví dụ
MyApphoặcMyApp Admin. - From Email: địa chỉ email sẽ gửi thư, ví dụ
[email protected]hoặc[email protected].
- From Name: tên hiển thị của người gửi, ví dụ
- Mở hộp thư của bạn, tìm email từ Brevo và bấm nút/link Verify để xác minh.
- Đảm bảo trạng thái của sender trên Brevo chuyển thành Active/Verified.
Bước 3: Xác thực tên miền (domain)
Nếu bạn dùng email theo tên miền riêng (ví dụ [email protected]), người nhận thường sẽ
thấy người gửi là một địa chỉ lạ như
admin@<account-id>.brevosend.com thay vì email chính xác của bạn.
Lý do: domain của sender chưa được verify nên Brevo tự động route email qua domain phụ của họ để thư không rơi vào Spam.
Cách khắc phục:
- Vào
Settings > Senders & Domains(hoặc mục tương tự trên dashboard), chọn tab Domains. - Bấm Add a domain rồi nhập tên miền (ví dụ
example.com). - Thêm 3 bản ghi DNS mà Brevo yêu cầu (bảng bên dưới) vào trang quản lý DNS của tên miền (Cloudflare, MatBao, Tenten...).
- Cấu hình DNS xong, quay lại Brevo bấm Verify. Chờ vài phút (tối đa vài giờ) để DNS cập nhật.
- Sau khi verify thành công, thêm lại sender
[email protected]như Bước 2. Thư sẽ hiển thị đúng[email protected]và không bị rơi vào Spam.
Ba bản ghi DNS cần khai báo:
| Loại | Tên (Host/Name) | Mục đích |
|---|---|---|
| TXT (DKIM) | mail._domainkey.example.com | Xác thực email là của bạn |
| TXT (SPF) | example.com | Cho phép Brevo gửi email thay bạn |
| CNAME (Return-Path) | <brevo-code>.example.com | Theo dõi thư trả về (tracking bounces) |
Giá trị cụ thể của từng bản ghi hiển thị ngay trên trang domain của Brevo - copy nguyên văn sang trang quản lý DNS.
Bước 4: Lấy API key
Brevo có 2 loại key: SMTP key và API key. Bạn BẮT BUỘC phải lấy API key - SMTP key không dùng được với HTTP API.
| Loại key | Cách nhận biết | Dùng được không |
|---|---|---|
| SMTP key (SMTP password) | Bắt đầu bằng *** và kết thúc bằng vài chữ cái ngắn | Không |
| API key | Cực kỳ dài và luôn bắt đầu bằng xkeysib- | Có |
- Bấm vào Profile ở góc trên bên phải trang Brevo, chọn SMTP & API.
- Màn hình này có 2 tab: "SMTP" và "API keys & MCP".
- Chọn tab API keys & MCP.
- Bấm Generate a new API key.
- Đặt tên gợi nhớ (ví dụ
website-prod-api). - Bấm Generate.
- Copy ngay lập tức chuỗi mã này (
xkeysib-...). Mã chỉ hiện lên một lần duy nhất.
Bước 5: Cấu hình ứng dụng (.env)
Sau khi có đủ thông tin, trên VPS (hoặc máy local), mở file .env và cập nhật cấu hình.
Tên biến dưới đây theo ứng dụng mẫu - đổi cho khớp với ứng dụng của bạn:
# 1. Bật chế độ gửi qua HTTP API (brevo) thay cho SMTP truyền thống
Email__Provider=brevo
# 2. Dán API key (bắt đầu bằng xkeysib-) vừa lấy ở Bước 4 vào đây
Email__BrevoApiKey=xkeysib-<your-api-key>
# 3. Điền CHÍNH XÁC email đã verify ở Bước 2
Email__SenderEmail=[email protected]
# 4. Tên hiển thị người gửi (nên khớp với From Name ở Bước 2)
Email__SenderName=MyAppKhởi động lại ứng dụng Docker:
docker compose down
docker compose up -d --buildXử lý sự cố
| Triệu chứng | Cách xử lý |
|---|---|
| Frontend báo lỗi (xoay vòng mãi) và log backend báo "Unauthorized" | Bạn đã dán nhầm SMTP password thay vì API key của Brevo. Xem lại Bước 4, đảm bảo lấy đúng key bắt đầu bằng xkeysib- |
| Log báo API thành công (201 Created) nhưng KHÔNG nhận được thư | Chưa làm Bước 2 (xác thực sender email) nên Brevo chặn. Cũng có thể thư bị bộ lọc kiểm duyệt của Brevo giữ lại (nghi spam/phishing) - vào Email Log trên dashboard Brevo để xem kết quả chi tiết |
| Thư vào mục Spam/Thư rác | Gửi lần đầu thì hộp thư (như Gmail) chưa "quen" - nhờ người nhận mở mục thư rác và đánh dấu Not spam / Báo cáo không phải thư rác vài lần để tăng độ uy tín (deliverability). Đồng thời chắc chắn đã cấu hình DNS DKIM/SPF ở Bước 3 |
Thư hiển thị sai email gửi dạng admin@<account-id>.brevosend.com | Chưa xác thực domain (Bước 3). Phải xác thực domain trên trang Brevo thì mới dùng được địa chỉ email theo tên miền riêng |