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
REST API	`POST /emails` và `POST /emails/batch`, hẹn giờ, idempotency, tag, tệp đính kèm	Gửi email
SMTP relay	`smtp.hatang.dev:5870` dùng STARTTLS, cho framework và ứng dụng chỉ biết gửi qua SMTP	SMTP relay
Templates	Mẫu email có biến, gửi bằng id hoặc alias	Templates
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
Nhận email	Thư gửi tới tên miền của bạn thành webhook `email.received`	Nhận email
Danh sách nhận	Contact, segment, topic và thuộc tính tuỳ chỉnh	Contacts, segments và topics
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
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
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
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

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

Ứ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.
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.
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.
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.
Một tên miền bạn thêm được bản ghi DNS.
Một API key. Xem Xác thực.

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.

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
Node.js
Python
PHP

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

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 <[email protected]>",
  to: ["[email protected]"],
  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);

from hatang import Hatang  # pip install hatang

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

<?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 <[email protected]>',
        'to' => ['[email protected]'],
        '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:

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

ghi chú

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.

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, mọi mã lỗi ở Lỗi.

Bước tiếp theo

Tên miền: cấu hình DKIM, SPF và DMARC.
Gửi email: mọi trường của POST /emails.
SMTP relay: kết nối WordPress, Laravel, Django và các nền tảng khác.
Chuyển từ Resend: những gì thay đổi khi bạn chuyển sang.

Xem trang này dạng Markdown

Bạn có gì​

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

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

Gửi email đầu tiên​

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

2. Tạo API key​

3. Gửi​

4. Theo dõi email​

Các mục trong dashboard​

Phạm vi của API key​

Giới hạn chính​

Bước tiếp theo​