NEXORELAY — DEVELOPER PLATFORM

Tài liệu API

Một API · giao dịch + marketing · kết nối trong 60 giây

Xác thực

Mọi request đều kèm header Authorization. Tạo key trong console — bản rõ chỉ hiện một lần.

curl https://api.nexorelay.com/v1/emails \ -H "Authorization: Bearer nxr_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ ... }'

Lấy API key trong console →

Gửi email

POST /v1/emails — tên miền gửi và tham số được kiểm tra đồng bộ; vào hàng đợi trả 202 kèm email id, trạng thái sau đó quay về qua event và webhook.

POST https://api.nexorelay.com/v1/emails { "from": "Acme <[email protected]>", "to": ["[email protected]"], "subject": "Hello", "html": "<strong>Hi</strong>", "tags": { "order_id": "123" } }

Phản hồi 202

{ "id": "email_abc123" }

Gửi bằng mẫu

Truyền template_id và variables (loại trừ với subject/html/text). Biến dùng cú pháp Handlebars.

{ "from": "Acme <[email protected]>", "to": ["[email protected]"], "template_id": "tpl_123", "variables": { "name": "Tom" } }

Gửi hàng loạt

POST /v1/emails/batch — tối đa 100 email/lần, mỗi email nội dung riêng.

POST https://api.nexorelay.com/v1/emails/batch { "emails": [ { "from": "...", "to": ["..."], "subject": "..." } ] } → 202 { "ids": ["email_1", "email_2", ...] }

Tra cứu email

GET https://api.nexorelay.com/v1/emails/email_abc123 → 200 { "id": "email_abc123", "status": "DELIVERED", ... }

Sự kiện Webhook

Đăng ký endpoint trong console — sự kiện đến với chữ ký HMAC: email.sent / delivered / bounced / complained / opened / clicked.

POST https://api.acme.com/hooks/nexorelay X-Nexorelay-Signature: sha256=... { "type": "email.delivered", "data": { "id": "email_abc123" } }

Định dạng lỗi

Một phong bì lỗi thống nhất — type là phân loại, code là nguyên nhân đọc được bằng máy.

{ "error": { "type": "invalid_request_error", "code": "domain_not_verified", "message": "The sending domain \"mail.example.com\" is not verified." } }

type	HTTP
invalid_request_error	400 / 404 / 409 / 422
authentication_error	401
permission_error	403
rate_limit_error	429
api_error	500
service_unavailable_error	503

Idempotency & giới hạn

Gửi header Idempotency-Key — cùng key+body trong 24h trả phản hồi đầu tiên, khác body trả 409. Mặc định 10 req/s mỗi key.

Idempotency-Key: order-8742