Kết nối bất kỳ API email HTTP nào

Hướng dẫn thao tác

Dành cho:: Quản trị viên không gian làm việc, Người vận hành máy chủ
Cần quyền:: providers:managenhạy cảm
Trong ứng dụng:: Nhà cung cấp gửi thư, rồi Adapter

Khi nhà cung cấp gửi thư của bạn chưa được tích hợp sẵn trong ReputeCast nhưng có HTTP API để gửi thư và JSON webhook cho sự kiện, adapter HTTP chung là cách tích hợp API email tùy chỉnh mà bạn thiết lập trong một biểu mẫu, không cần viết code. Bạn ánh xạ yêu cầu gửi, vị trí mã thư trong phản hồi, và cách đọc cũng như xác thực webhook; ReputeCast lưu lại thành một adapter mà mọi không gian làm việc trên hệ thống đều kết nối được.

Loại	HTTP
Gửi marketing hàng loạt	Theo chính sách của bạn
Webhook sự kiện	Thêm thủ công tại nhà cung cấp của bạn; HMAC, Standard Webhooks, basic auth, khóa bí mật trong header hoặc không có
Thiết lập tên miền	DNS thủ công
Đồng bộ danh sách chặn gửi	Chỉ cục bộ
Kích thước lô	1
Ghi chú	Ánh xạ lệnh gửi và webhook của bất kỳ API email HTTP nào mà không cần viết mã, từ một biểu mẫu hoặc một manifest.

Trước khi bắt đầu

Chọn đúng loại adapter. Adapter HTTP chung gửi mỗi thư một yêu cầu và đọc webhook. Nếu nhà cung cấp của bạn cũng có SMTP endpoint, kết nối SMTP có thể đơn giản hơn; nếu bạn cần gửi theo lô, API tên miền hoặc đồng bộ danh sách chặn gửi, hãy viết một adapter cộng đồng. Adapter nhà cung cấp so sánh ba loại này.
Quản trị viên hệ thống. Adapter áp dụng cho mọi không gian làm việc trên hệ thống, nên chỉ quản trị viên hệ thống có providers:manage mới lưu được adapter. Những người khác chỉ xem được biểu mẫu ở chế độ chỉ đọc.
Từ tài liệu API của nhà cung cấp: endpoint gửi, cách xác thực (thường là API key trong một header), JSON body mà API yêu cầu, vị trí mã thư trong phản hồi, và cấu trúc của các sự kiện webhook.
Một địa chỉ HTTPS công khai cho webhook. ReputeCast không hỏi định kỳ được với một ánh xạ HTTP, nên địa chỉ phải truy cập được từ internet.

Ánh xạ và kết nối API

Mở Nhà cung cấp gửi thư, rồi Adapter và cuộn tới Adapter HTTP chung.
Điền ánh xạ:
- Endpoint gửi: phương thức và một URL https://, ví dụ POST https://api.example-esp.com/v1/messages (POST, PUT hoặc PATCH).
- Header của yêu cầu: mỗi dòng một header, dạng Name: value, ví dụ Authorization: Bearer {{ secrets.api_key }}. {{ secrets.api_key }} là khóa được nhập khi một không gian làm việc kết nối adapter.
- Mẫu nội dung yêu cầu: JSON body với các trường {{ }} như {{ sender }}, {{ recipient }}, {{ subject }}, {{ html }} và {{ headers_json }}. Giá trị được escape cho JSON. Hãy thêm {{ message_id }} nếu nhà cung cấp có thể gửi lại giá trị này trong webhook.
- Mã thư trong phản hồi: một JSONPath trỏ vào phản hồi, ví dụ $.data.id.
- Ánh xạ webhook: preset cho webhook có trường status, hoặc Ánh xạ JSONPath tùy chỉnh với đường dẫn của Loại sự kiện, Người nhận, Mã thư và, với webhook gửi theo lô, Các sự kiện trong một yêu cầu.
- Xác thực webhook: Chữ ký HMAC trong một header, Standard Webhooks (webhook-signature), Basic auth, Khóa bí mật trong một header, hoặc Không có: chỉ dùng URL webhook.
Chọn Thử với một thư mẫu. ReputeCast kết xuất yêu cầu mà nó sẽ gửi cho một thư mẫu, với các khóa bí mật hiển thị là ••••. Không có gì được gửi đi: bước này kiểm tra ánh xạ, không kiểm tra nhà cung cấp.
Chọn Lưu thành adapter, đặt Tên chẳng hạn như tên nhà cung cấp, rồi lưu. Adapter xuất hiện trong Thêm nhà cung cấp ở mọi không gian làm việc.
Trong không gian làm việc dùng để gửi, mở Nhà cung cấp gửi thư, chọn Thêm nhà cung cấp và tìm adapter của bạn trong Adapter cộng đồng. Chọn Kết nối, dán Khóa API và, nếu nhà cung cấp ký webhook bằng khóa bí mật riêng, dán Khóa bí mật ký webhook của họ trong phần thiết lập thêm. Ánh xạ tạo bằng biểu mẫu không có bước kiểm tra thông tin xác thực, nên khóa sai chỉ lộ ra khi gửi thư thử.
Trong 2. Webhook, ReputeCast kiểm tra URL công khai của chính nó. Chọn Sao chép URL và thêm URL đó làm webhook trong nhà cung cấp. Nếu bạn chưa nhập khóa bí mật ký riêng của nhà cung cấp, hãy chọn Tạo khóa bí mật, sao chép khóa (chỉ hiển thị một lần) và thiết lập nó trong nhà cung cấp theo cách xác thực webhook bạn đã chọn.
Hoàn tất bước Tiếp tục xác minh tên miền với các bản ghi DNS mà nhà cung cấp hướng dẫn; ReputeCast đề xuất DMARC nếu tên miền chưa có. Trong Gửi thử, gửi thư thử: đây là một thư thật đi qua ánh xạ của bạn, và dòng thời gian chờ tối đa 30 phút cho webhook đầu tiên của nhà cung cấp.

Kiểm tra kết quả

Dòng thời gian của thư thử hiển thị sự kiện gửi thành công từ nhà cung cấp.
Thẻ adapter của bạn trên Nhà cung cấp gửi thư, rồi Nhà cung cấp hiển thị Ổn định, và sự kiện đổ về trong Nhà cung cấp gửi thư, rồi Sự kiện và đồng bộ.

ReputeCast gửi mỗi thư một yêu cầu, tối đa 20 yêu cầu mỗi giây. Phản hồi 401 hoặc 403 từ nhà cung cấp đánh dấu nhà cung cấp gián đoạn do thông tin xác thực bị lỗi, 429 làm chậm tốc độ gửi, còn 408 hoặc 5xx được tính vào sự cố gián đoạn. Ánh xạ không hỗ trợ bản sao và tệp đính kèm. ReputeCast không đọc được điều khoản của nhà cung cấp, nên hãy kiểm tra chính sách sử dụng được chấp nhận (acceptable-use policy) của họ trước khi định tuyến thư Gửi hàng loạt tới đó.

Khắc phục sự cố

“Hãy nhập một URL https://, ví dụ POST https://api.example-esp.com/v1/messages.” Biểu mẫu cần phương thức và một địa chỉ https://. Địa chỉ http:// chỉ dùng được trong manifest, cho máy chủ thử nghiệm trên loopback.
“Mẫu nội dung không phải JSON hợp lệ sau khi điền các trường {{ }}.” Hãy kiểm tra dấu phẩy và dấu ngoặc kép. Bên trong một chuỗi JSON, trường được escape tại chỗ ("subject": "{{ subject }}"); bên ngoài chuỗi, trường được mã hóa JSON, nên "headers": {{ headers_json }} trở thành một object.
“… đã được đăng ký với khóa …”. Một adapter khác đã dùng tên đó. Hãy chọn tên khác.
Thư thử thất bại với “… không nhận thư thử”. Câu trả lời của nhà cung cấp nằm sau thông báo: thường là khóa sai, thiếu header hoặc một trường trong body bị API từ chối. Hãy so sánh yêu cầu từ Thử với một thư mẫu với tài liệu của nhà cung cấp.
Webhook nhận 401. Yêu cầu của nhà cung cấp không khớp với cách xác thực webhook bạn đã chọn, hoặc nhà cung cấp vẫn dùng khóa bí mật cũ. Sau khi dùng Xoay vòng khóa bí mật trong Cài đặt, rồi Nhà cung cấp, hãy dán khóa bí mật mới vào nhà cung cấp, vì ReputeCast không cập nhật được ở phía đó.
Bạn đã ngắt kết nối adapter. ReputeCast không thay đổi gì ở phía nhà cung cấp. Hãy xóa webhook trỏ tới ReputeCast ở đó.