Tài liệu API
Trình kết nối PHP gửi yêu cầu máy chủ tới máy chủ. Không đặt khóa trong JavaScript hoặc trình duyệt.
1. Cài đặt
- Tạo tên miền phụ mailguard.sygnexproduction.com, bật HTTPS và trỏ thư mục gốc web trực tiếp đến các tệp Guard.
- Nhập install_guard.sql vào cơ sở dữ liệu trung tâm đã có bảng utilisateurs.
- Cấu hình config/local.php và đặt mã cài đặt ngẫu nhiên dài ít nhất 40 ký tự.
- Mở /admin/setup.php để tạo quản trị viên đầu tiên, sau đó đăng nhập tại /admin/index.php.
- Tạo website trong bảng điều khiển, sao chép khóa API và bí mật chỉ một lần, rồi khai báo người nhận được phép.
- Cài trình kết nối PHP trên máy chủ của website nguồn. Không bao giờ gọi API từ JavaScript của trình duyệt.
2. Ví dụ PHP
Trình kết nối độc lập và dùng chức năng HTTPS gốc của PHP, không cần thư viện bên thứ ba. Kết quả trả về là JSON. Biểu mẫu phải gửi các trường từ máy chủ.
<?php
require_once __DIR__ . '/client-sdk/sygnex-guard-connector.php';
$guard = new SygnexGuardConnector(
'YOUR_API_KEY',
'YOUR_API_SECRET',
'https://mailguard.sygnexproduction.com/api/intercept.php',
'www.your-site.example'
);
$result = $guard->submit([
'nom_expediteur' => $_POST['nom'] ?? '',
'email_expediteur' => $_POST['email'] ?? '',
'email_destinataire' => 'contact@your-site.example',
'sujet' => $_POST['sujet'] ?? 'Website message',
'corps_message' => $_POST['message'] ?? '',
'langue' => 'fr',
'website' => $_POST['website'] ?? '', // honeypot: keep empty
]);
if (!$result['ok']) {
// Handle service or quota errors; never expose API secrets.
}Trường website phải được ẩn và để trống khi người thật điền biểu mẫu.
3. Các trường API chấp nhận
| Trường | Bắt buộc | Mô tả |
|---|---|---|
api_key | Có | Mã API được cấp cho website. |
api_secret | Có | Bí mật chỉ được truyền giữa các máy chủ qua HTTPS. |
site_domain | Có | Tên miền đã đăng ký trong bảng điều khiển. |
nom_expediteur | Có | Tên người gửi (tối đa 150 ký tự). |
email_expediteur | Có | Địa chỉ email trả lời hợp lệ. |
email_destinataire | Có | Phải khớp chính xác với địa chỉ được phép của website này. |
sujet | Có | Tối đa 255 ký tự. |
corps_message | Có | Nội dung tin nhắn (tối đa 60.000 byte). |
langue | Không | fr, en, de, it, zh hoặc vi. |
website | Không | Trường honeypot; phải để trống. |
pieces_jointes | Không | Mảng JSON gồm name, mime và content_base64; định dạng và dung lượng bị giới hạn. |
4. Các phản hồi thường gặp
200 sent— Người gửi đã được cho phép; tin nhắn đã chuyển đi.202 verification_required— Cần xác minh con người; email xác minh sẽ được gửi.202 received— Phản hồi trung tính có chủ ý đối với một số trường hợp chặn spam.401 unauthorized— Khóa API hoặc bí mật không đúng.403 recipient_not_allowed— Người nhận không được phép cho website này.429 rate_limited / monthly_quota_exceeded— Đã đạt giới hạn tốc độ hoặc hạn mức hàng tháng.503 service_unavailable— Cấu hình, cơ sở dữ liệu hoặc gửi email không khả dụng.
5. Các giới hạn vận hành quan trọng
Ứng dụng dùng hàm mail() gốc của PHP. Hàm trả về thành công không đảm bảo thư vào hộp thư chính. Hãy kiểm tra chính sách gửi thư của nhà cung cấp hosting và cấu hình SPF, DKIM, DMARC. Kiểm tra MX/SPF/DMARC chỉ mang tính tham khảo và không chứng minh danh tính tên miền bằng mật mã. Phép tính giúp giảm spam tự động nhưng không phải biện pháp bảo vệ tuyệt đối.
Tệp đính kèm được mã hóa base64 và phải tuân theo giới hạn trong config/local.php. Khai báo rõ người nhận được phép cho từng website; Guard từ chối người nhận chưa được khai báo.
6. Hạn mức và theo dõi sử dụng
Mức tham khảo ban đầu là 100 tin nhắn được bảo vệ mỗi tháng cho gói miễn phí và 1.000 cho Premium. Gói Doanh nghiệp có hạn mức tùy chỉnh do quản trị viên đặt thủ công. Quản trị viên có thể điều chỉnh hạn mức. Gói nội bộ bỏ qua trần thương mại về số tin nhắn nhưng vẫn chịu các biện pháp bảo vệ kỹ thuật và giới hạn tài nguyên hosting.
Guard theo dõi riêng số tin nhắn được bảo vệ và số email gửi đi được hàm mail() chấp nhận thực tế. Cảnh báo được thiết kế ở mức 70%, 90% và 100%. Khi đạt hạn mức tháng, các lần gửi mới của gói đó bị từ chối cho đến khi sang tháng mới hoặc hạn mức được thay đổi. Hãy xác nhận khả năng gửi thực tế với nhà cung cấp trước khi chào bán gói lưu lượng lớn.