MailGate API Reference

Dịch vụ gửi email giao dịch (mock) cho English app — biên nhận thanh toán, báo thất bại, chào mừng Premium. Đối tác thứ 2 bên cạnh PayGate.

Base URL: http://localhost:4343 · Đặc tả: openapi.yaml

Server giả phục vụ đào tạo. Dữ liệu trong RAM, mất khi restart.

Giới thiệu

REST API trả JSON. Tài nguyên: templates (mẫu email có sẵn) và messages (email đã gửi + trạng thái giao). Mọi request /v1/* cần khóa Bearer.

Xác thực

Header Authorization: Bearer mg_test_.... Lưu ý: khóa MailGate KHÁC khóa PayGate — mỗi đối tác 1 khóa riêng.

Header

Authorization: Bearer mg_test_demo_4343

Lỗi

HTTP	code	Ý nghĩa
400	`missing_field`	Thiếu to/template
400	`invalid_email`	Địa chỉ email sai định dạng
400	`template_not_found`	Template không tồn tại
401	`unauthorized`	Thiếu/sai khóa
429	`rate_limited`	Gửi quá nhiều

Gửi tới bounce@... để mô phỏng email bị trả về: message tạo thành công nhưng status: "bounced" + bounce_reason. Đây là case dạy "gửi OK ≠ giao thành công".

GET/v1/templates

Liệt kê template + biến bắt buộc. Template: receiptpayment_failedwelcome_premium

curl -s $BASE/v1/templates \
  -H "Authorization: Bearer mg_test_demo_4343"

POST/v1/messages

Gửi 1 email theo template với biến điền sẵn.

Tham số	Mô tả
`to` bắt buộc	Email người nhận
`template` bắt buộc	receipt \| payment_failed \| welcome_premium
`variables`	Biến điền vào template

Request

curl -s $BASE/v1/messages \
  -H "Authorization: Bearer mg_test_demo_4343" \
  -d '{"to":"hv@example.com","template":"receipt",
       "variables":{"customer_name":"A","amount":"99.000đ","charge_id":"ch_abc"}}'

Response 201

{ "id":"msg_...", "to":"hv@example.com",
  "template":"receipt", "status":"delivered" }

GET/v1/messages/{id}

Tra trạng thái giao email. Trạng thái: queueddeliveredbouncedfailed

curl -s $BASE/v1/messages/msg_abc \
  -H "Authorization: Bearer mg_test_demo_4343"

GET/v1/messages

Liệt kê email đã gửi (phân trang qua ?limit=).

curl -s $BASE/v1/messages?limit=5 \
  -H "Authorization: Bearer mg_test_demo_4343"

MailGate mock · tài liệu phục vụ Buổi 6 — Integrate.