Tạo khoá API để gửi thư
Chọn đúng loại khoá cho từng ứng dụng, lưu mã khoá ngay ở lần hiển thị duy nhất, và thu hồi đúng cách khi khoá bị lộ.
Khoá API là thứ ứng dụng của bạn dùng để chứng minh danh tính khi gọi lệnh gửi thư. Không có khoá thì không gửi được gì.
Chuẩn bị
- Ít nhất một tên miền đã kích hoạt trong Email API. Xem Cắm bản ghi cho tên miền gửi
- Chỗ lưu bí mật an toàn — trình quản lý mật khẩu, hoặc kho biến môi trường của hệ thống triển khai
Chưa có tên miền nào kích hoạt thì trang khoá hiện thẳng thông báo Chưa thể tạo khoá API kèm liên kết sang trang tên miền. Đó không phải lỗi, chỉ là thứ tự bắt buộc.
Hai loại khoá
Vào Email API → Khóa API. Trang có hai thẻ, mỗi thẻ một loại khoá với hạn mức riêng.
| Sending Key | Account Key | |
|---|---|---|
| Gắn với một tên miền | có, bắt buộc | không |
| Gửi được thư từ | đúng tên miền đó | mọi tên miền của tài khoản |
| Dùng cho | ứng dụng chạy thật | công cụ quản trị, script nội bộ |
Mặc định hãy tạo Sending Key. Nó bị giới hạn đúng một tên miền, nên khoá lộ ra ngoài thì thiệt hại cũng dừng ở tên miền đó. Account Key rộng hơn — cân nhắc kỹ trước khi đưa nó cho một ứng dụng đang chạy thật.
Sending Key gắn với tên miền đang chọn ở hộp tên miền trên thanh bên trái. Chọn nhầm thì khoá gắn nhầm tên miền, và không đổi lại được — phải xoá và tạo khoá khác. Kiểm lại hộp đó trước khi bấm tạo.
Tạo khoá
- Chọn đúng thẻ Sending Keys hoặc Account Keys
- Với Sending Key: chọn tên miền ở thanh bên trái
- Bấm Tạo khóa API mới
- Đặt Tên khóa API — tên này chỉ để bạn nhận ra sau này, ví dụ
Máy chủ đơn hàng - Bấm tạo
Đặt tên theo nơi dùng, không phải theo ngày tạo. Sáu tháng sau, khi cần thu hồi một khoá, thứ bạn biết là "máy chủ nào" chứ không phải "khoá tạo hôm nào".
Lưu mã khoá ngay
Mã khoá chỉ hiển thị đúng một lần
Sau khi tạo, hộp thoại hiện toàn bộ mã khoá kèm nút chép. Đóng hộp thoại là mất vĩnh viễn — hệ thống không lưu bản rõ và không hiển thị lại được, kể cả bộ phận hỗ trợ.
Chép và lưu trước khi đóng. Mất rồi thì cách duy nhất là xoá khoá đó và tạo khoá mới.
Bảng danh sách chỉ hiện phần đầu của mã ở cột Mã khóa (Preview) — đủ để đối chiếu khoá nào là khoá nào, không đủ để dùng.
Lưu vào biến môi trường của ứng dụng, không viết thẳng vào mã nguồn. Khoá nằm trong kho mã nguồn là khoá đã lộ, kể cả kho riêng tư.
Đừng đặt khoá ở phía trình duyệt
Khoá API cấp quyền gửi thư dưới danh nghĩa tài khoản của bạn. Bất kỳ ai đọc được nó đều gửi được thư mang tên miền của bạn.
Nghĩa là không đặt khoá trong JavaScript của trang web, ứng dụng di động, hay bất cứ thứ gì người dùng cuối tải về được. Lệnh gọi gửi thư phải xuất phát từ máy chủ của bạn.
Xem khoá đang dùng tới đâu
Bảng có hai cột giúp rà soát định kỳ:
| Cột | Dùng để |
|---|---|
| IP giới hạn | biết khoá có bị bó vào dải IP nào không |
| Lần dùng cuối | tìm khoá đã bỏ quên — trống hoặc rất cũ nghĩa là không ai dùng nữa |
Khoá không còn ai dùng thì xoá. Mỗi khoá còn sống là một đường vào còn mở.
Thu hồi một khoá
Bấm Xóa khóa API ở cuối dòng. Hộp thoại xác nhận in tên khoá — đọc lại trước khi xác nhận.
Việc xoá có hiệu lực ngay: ứng dụng đang dùng khoá đó mất quyền gửi lập tức, không có thời gian chuyển tiếp. Đổi khoá cho một hệ thống đang chạy thì làm theo thứ tự này:
- Tạo khoá mới
- Cập nhật cấu hình ứng dụng và triển khai
- Xem cột Lần dùng cuối của khoá cũ ngừng cập nhật
- Lúc đó mới xoá khoá cũ
Nghi khoá bị lộ thì làm ngược lại — xoá trước, chịu gián đoạn, rồi mới tạo khoá mới.
Kiểm tra kết quả
Khoá dùng được khi lệnh gọi gửi thư đầu tiên trả về mã chấp nhận. Xem Gửi thư đầu tiên qua Email API.
Bị từ chối xác thực nghĩa là khoá sai hoặc đã bị xoá. Bị từ chối quyền nghĩa là khoá đúng nhưng địa
chỉ from không thuộc tên miền mà Sending Key được gắn.
Cắm bản ghi cho tên miền gửi
Bước 2 của Email API. Thêm tên miền gửi rồi cắm các bản ghi ký thư và đường phản hồi, mà không đụng tới hộp thư đang dùng.
Nhận sự kiện thư qua webhook
Cấu hình endpoint để biết thư tới hay hỏng ngay trong mã nguồn, chọn đúng sự kiện cần nghe và xác minh chữ ký để không nhận nhầm dữ liệu giả.