API subscribe cho phép người dùng đăng ký email để nhận tin, ví dụ thông báo khi website có bài viết mới. API này phù hợp để gắn vào form “Đăng ký nhận tin” ở footer, popup, landing page hoặc trang blog.

Endpoint

POST /api/v1/ezycrm/subscribe
Content-Type: application/json
Request body:
{
  "email": "user@example.com"
}
Response thành công:
204 No Content
API không trả về body khi xử lý thành công.

Điều kiện sử dụng

Trước khi gọi API, quản trị viên cần bật cấu hình cho phép người dùng đăng ký nhận tin.
Nếu cấu hình này đang tắt, API sẽ từ chối request với lỗi 403 Forbidden.
Email gửi lên cũng phải hợp lệ:
  • Thiếu email: lỗi 400 Bad Request
  • Email sai định dạng: lỗi 400 Bad Request
Ví dụ lỗi validate: 
{
  "email": "invalid"
}
hoặc:
{
  "email": "required"
}

Nguyên lý hoạt động

Khi nhận request, hệ thống kiểm tra cấu hình đăng ký, validate email, sau đó thêm email vào nhóm người nhận tin. Nếu email chưa tồn tại trong hệ thống người dùng, hệ thống tạo một hồ sơ người dùng tối thiểu ở trạng thái lưu trữ, rồi gắn vai trò subscriber cho người dùng đó.
Nếu email đã tồn tại, hệ thống không tạo user mới mà chỉ đảm bảo user đó có vai trò subscriber. Vì vậy có thể gọi API nhiều lần với cùng một email mà không tạo trùng bản ghi đăng ký.
flowchart TD
    A[Người dùng nhập email] --> B[Gọi POST /api/v1/ezycrm/subscribe]
    B --> C{Cho phép đăng ký?}
    C -- Không --> D[Trả về 403 Forbidden]
    C -- Có --> E{Email hợp lệ?}
    E -- Không --> F[Trả về 400 Bad Request]
    E -- Có --> G{Email đã có user?}
    G -- Chưa --> H[Tạo user tối thiểu]
    G -- Rồi --> I[Dùng user hiện có]
    H --> J{Đã có vai trò subscriber?}
    I --> J
    J -- Chưa --> K[Gắn vai trò subscriber]
    J -- Rồi --> L[Bỏ qua]
    K --> M[Trả về 204 No Content]
    L --> M

Ví dụ gọi API

Dùng jQuery AJAX:
<form id="subscribeForm">
    <input type="email" id="subscribeEmail" placeholder="Email của bạn" required>
    <button type="submit">Đăng ký</button>
</form>

<script>
$('#subscribeForm').on('submit', function(e) {
    e.preventDefault();

    $.ajax({
        url: '/api/v1/ezycrm/subscribe',
        type: 'POST',
        contentType: 'application/json',
        data: JSON.stringify({
            email: $('#subscribeEmail').val()
        }),
        success: function() {
            alert('Bạn đã đăng ký nhận tin thành công.');
        },
        error: function(xhr) {
            if (xhr.status === 400) {
                alert('Email không hợp lệ.');
            } else if (xhr.status === 403) {
                alert('Chức năng đăng ký nhận tin hiện chưa được bật.');
            } else {
                alert('Không thể đăng ký nhận tin. Vui lòng thử lại sau.');
            }
        }
    });
});
</script>
Nếu form đang dùng hệ thống i18n hoặc component riêng của theme, chỉ cần giữ nguyên phần $.ajax(...); phần lấy email và hiển thị thông báo có thể thay bằng logic UI hiện tại.
Dùng fetch:
await fetch('/api/v1/ezycrm/subscribe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com'
  })
});
Dùng curl:
curl -X POST 'https://your-domain.com/api/v1/ezycrm/subscribe' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'

Luồng gửi thông báo sau khi đăng ký

API subscribe chỉ ghi nhận người dùng vào danh sách subscriber. Việc gửi email thông báo là một luồng riêng, chạy theo lịch cấu hình trong trang quản trị.
Ở mỗi lần chạy lịch, hệ thống kiểm tra:
  • cấu hình gửi mail cho subscriber có đang bật không,
  • từ lần chạy trước đến hiện tại có bài viết mới được publish không,
  • danh sách người dùng có vai trò subscriber.
Nếu có bài viết mới, hệ thống gửi email theo template thông báo bài viết mới đến từng subscriber có email hợp lệ. 
sequenceDiagram
    participant S as Bộ lập lịch
    participant C as Cấu hình
    participant P as Bài viết
    participant U as Subscriber
    participant M as Mail service

    S->>C: Kiểm tra có cho gửi mail không
    alt Không cho gửi
        C-->>S: Dừng
    else Cho gửi
        S->>P: Đếm bài viết mới từ lần chạy trước
        alt Không có bài mới
            P-->>S: Dừng
        else Có bài mới
            S->>U: Lấy danh sách subscriber
            U->>M: Gửi email thông báo
        end
    end

Lưu ý tích hợp

API này không tự gửi email xác nhận ngay sau khi đăng ký. Nó chỉ thêm email vào danh sách người nhận tin.
Nếu muốn hiển thị thông báo trên giao diện, chỉ cần coi HTTP 204 là đăng ký thành công, ví dụ: “Bạn đã đăng ký nhận tin thành công”.
Nên chống spam ở phía giao diện hoặc tầng gateway nếu form được public rộng rãi, ví dụ thêm captcha, rate limit theo IP hoặc kiểm soát tần suất gửi request.