WebHook

🇬🇧 English

Overview

BizMail automatically pushes real-time email delivery events to your webhook URL configured in the BizMail Portal.

When an email changes status (delivered, bounced, dropped), BizMail sends an HTTP POST request to your endpoint with a JSON payload describing the event.

Configuration

Configure your webhook URL and which events to receive in the BizMail Portal under your account settings. You can register separate webhook URLs per event type.

Events

Payload Structure

BizMail sends different payload shapes depending on the event type.

Event: delivered

Triggered when an email is successfully delivered.

{
  "event": "delivered",
  "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn",
  "recipient": "user@example.com",
  "time": 1713100000,
  "mxHostname": "mx.example.com",
  "response": "250 OK"
}

Event: bounced

Triggered when an email bounces. Includes a category field to distinguish hard and soft bounce.

{
  "event": "bounce",
  "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn",
  "to": "user@example.com",
  "time": 1713100000,
  "response": "550 5.1.1 The email account does not exist",
  "category": "hard_bounce",
  "user": "",
  "seq": "",
  "returnPath": ""
}

Category values:

Event: dropped

Triggered when an email is dropped (suppressed before sending).

{
  "action": "drop",
  "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn",
  "recipient": "user@example.com",
  "reason": "Suppressed address",
  "user": "",
  "seq": ""
}

Webhook Request Details

BizMail sends events as HTTP POST requests to your configured URL.

Headers:

Content-Type: application/json

Your endpoint must respond with HTTP 2xx to acknowledge receipt. If your endpoint does not respond or returns a non-2xx status, BizMail may retry the delivery.

Example Receiver (PHP)

$payload = file_get_contents('php://input');
$data = json_decode($payload, true);
switch ($data['event'] ?? $data['action'] ?? '') {
    case 'delivered':
        // handle delivered
        break;
    case 'bounce':
        $category = $data['category']; // hard_bounce or soft_bounce
        // handle bounce
        break;
    case 'drop':
        // handle dropped
        break;
}
http_response_code(200);

Example Receiver (Node.js / Express)

app.post('/webhook/bizmail', (req, res) => {
    const data = req.body;
    const event = data.event || data.action;
    switch (event) {
        case 'delivered':
            // handle delivered
            break;
        case 'bounce':
            const category = data.category; // hard_bounce or soft_bounce
            // handle bounce
            break;
        case 'drop':
            // handle dropped
            break;
    }
    res.sendStatus(200);
});

🇻🇳 Tiếng Việt

Tổng quan

BizMail tự động đẩy các sự kiện tracking email theo thời gian thực đến webhook URL được cấu hình trong BizMail Portal.

Khi email thay đổi trạng thái (delivered, bounced, dropped), BizMail gửi HTTP POST request đến endpoint của bạn kèm JSON payload mô tả sự kiện.

Cấu hình

Cấu hình webhook URL và các sự kiện cần nhận trong BizMail Portal tại phần cài đặt tài khoản. Bạn có thể đăng ký webhook URL riêng cho từng loại sự kiện.

Các sự kiện

Cấu trúc Payload

BizMail gửi payload có cấu trúc khác nhau tùy theo loại sự kiện.

Sự kiện: delivered

Kích hoạt khi email được gửi thành công.

{
  "event": "delivered",
  "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn",
  "recipient": "user@example.com",
  "time": 1713100000,
  "mxHostname": "mx.example.com",
  "response": "250 OK"
}

Sự kiện: bounced

Kích hoạt khi email bị bounce. Có trường category phân biệt hard/soft bounce.

{
  "event": "bounce",
  "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn",
  "to": "user@example.com",
  "time": 1713100000,
  "response": "550 5.1.1 The email account does not exist",
  "category": "hard_bounce",
  "user": "",
  "seq": "",
  "returnPath": ""
}

Giá trị category:

Sự kiện: dropped

Kích hoạt khi email bị hủy (bị chặn trước khi gửi).

{
  "action": "drop",
  "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn",
  "recipient": "user@example.com",
  "reason": "Suppressed address",
  "user": "",
  "seq": ""
}

Chi tiết Webhook Request

BizMail gửi sự kiện qua HTTP POST đến URL đã cấu hình.

Headers:

Content-Type: application/json

Endpoint của bạn phải trả về HTTP 2xx để xác nhận nhận được. Nếu không phản hồi hoặc trả về non-2xx, BizMail có thể thử gửi lại.

Ví dụ nhận webhook (PHP)

$payload = file_get_contents('php://input');
$data = json_decode($payload, true);
switch ($data['event'] ?? $data['action'] ?? '') {
    case 'delivered':
        // xử lý delivered
        break;
    case 'bounce':
        $category = $data['category']; // hard_bounce hoặc soft_bounce
        // xử lý bounce
        break;
    case 'drop':
        // xử lý dropped
        break;
}
http_response_code(200);

Ví dụ nhận webhook (Node.js / Express)

app.post('/webhook/bizmail', (req, res) => {
    const data = req.body;
    const event = data.event || data.action;
    switch (event) {
        case 'delivered':
            // xử lý delivered
            break;
        case 'bounce':
            const category = data.category; // hard_bounce hoặc soft_bounce
            // xử lý bounce
            break;
        case 'drop':
            // xử lý dropped
            break;
    }
    res.sendStatus(200);
});