> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bizmail-delivery.bizfly.vn/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bizmail-delivery.bizfly.vn/_mcp/server. # WebHook POST https:// Content-Type: multipart/form-data # BizMail API 1.0 — Webhook Tracking --- ## 🇬🇧 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 | Event | Description | |-------|-------------| | `delivered` | Email was successfully delivered to the recipient's inbox | | `bounced` | Email bounced — can be hard bounce (invalid address) or soft bounce (temporary server rejection) | | `dropped` | Email was dropped by the server | --- ### Payload Structure BizMail sends different payload shapes depending on the event type. --- #### Event: `delivered` Triggered when an email is successfully delivered. ```json { "event": "delivered", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "time": 1713100000, "mxHostname": "mx.example.com", "response": "250 OK" } ``` | Field | Type | Description | |-------|------|-------------| | event | string | Always `delivered` | | id | string | `message_id` of the original email | | recipient | string | Recipient email address | | time | integer | Delivery timestamp (Unix ms) | | mxHostname | string | MX server that accepted the email | | response | string | SMTP response from the receiving server | --- #### Event: `bounced` Triggered when an email bounces. Includes a `category` field to distinguish hard and soft bounce. ```json { "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": "" } ``` | Field | Type | Description | |-------|------|-------------| | event | string | Always `bounce` | | id | string | `message_id` of the original email | | to | string | Recipient email address | | time | integer | Event timestamp (Unix ms) | | response | string | SMTP error response | | category | string | `hard_bounce` (permanent, e.g. invalid address) or `soft_bounce` (temporary, e.g. mailbox full) | | user | string | Reserved | | seq | string | Reserved | | returnPath | string | Return path header | **Category values:** | Value | Trigger condition | Description | |-------|-------------------|-------------| | `hard_bounce` | `REJECTED` | Permanent failure — invalid address or domain | | `soft_bounce` | `DEFERRED` | Temporary failure — server busy or mailbox full | --- #### Event: `dropped` Triggered when an email is dropped (suppressed before sending). ```json { "action": "drop", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "reason": "Suppressed address", "user": "", "seq": "" } ``` | Field | Type | Description | |-------|------|-------------| | action | string | Always `drop` | | id | string | `message_id` of the original email | | recipient | string | Recipient email address | | reason | string | Reason the email was dropped | | user | string | Reserved | | seq | string | Reserved | --- ### 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) ```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) ```js 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 | Sự kiện | Mô tả | |---------|-------| | `delivered` | Email đã được gửi thành công vào hộp thư của người nhận | | `bounced` | Email bị bounce — có thể là hard bounce (địa chỉ không tồn tại) hoặc soft bounce (server từ chối tạm thời) | | `dropped` | Email bị hủy trước khi gửi | --- ### 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. ```json { "event": "delivered", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "time": 1713100000, "mxHostname": "mx.example.com", "response": "250 OK" } ``` | Trường | Kiểu | Mô tả | |--------|------|-------| | event | string | Luôn là `delivered` | | id | string | `message_id` của email gốc | | recipient | string | Địa chỉ email người nhận | | time | integer | Timestamp gửi thành công (Unix ms) | | mxHostname | string | MX server đã nhận email | | response | string | Phản hồi SMTP từ server nhận | --- #### Sự kiện: `bounced` Kích hoạt khi email bị bounce. Có trường `category` phân biệt hard/soft bounce. ```json { "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": "" } ``` | Trường | Kiểu | Mô tả | |--------|------|-------| | event | string | Luôn là `bounce` | | id | string | `message_id` của email gốc | | to | string | Địa chỉ email người nhận | | time | integer | Timestamp sự kiện (Unix ms) | | response | string | Thông báo lỗi SMTP | | category | string | `hard_bounce` (lỗi vĩnh viễn) hoặc `soft_bounce` (lỗi tạm thời) | | user | string | Dự phòng | | seq | string | Dự phòng | | returnPath | string | Header return path | **Giá trị category:** | Giá trị | Điều kiện | Mô tả | |---------|-----------|-------| | `hard_bounce` | `REJECTED` | Lỗi vĩnh viễn — địa chỉ hoặc domain không tồn tại | | `soft_bounce` | `DEFERRED` | Lỗi tạm thời — server bận hoặc hộp thư đầy | --- #### Sự kiện: `dropped` Kích hoạt khi email bị hủy (bị chặn trước khi gửi). ```json { "action": "drop", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "reason": "Suppressed address", "user": "", "seq": "" } ``` | Trường | Kiểu | Mô tả | |--------|------|-------| | action | string | Luôn là `drop` | | id | string | `message_id` của email gốc | | recipient | string | Địa chỉ email người nhận | | reason | string | Lý do email bị hủy | | user | string | Dự phòng | | seq | string | Dự phòng | --- ### 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) ```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) ```js 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); }); ``` Reference: https://docs.bizmail-delivery.bizfly.vn/biz-mail-delivery/mail/web-hook ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: collection version: 1.0.0 paths: /: post: operationId: web-hook summary: WebHook description: > # BizMail API 1.0 — Webhook Tracking --- ## 🇬🇧 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 | Event | Description | |-------|-------------| | `delivered` | Email was successfully delivered to the recipient's inbox | | `bounced` | Email bounced — can be hard bounce (invalid address) or soft bounce (temporary server rejection) | | `dropped` | Email was dropped by the server | --- ### Payload Structure BizMail sends different payload shapes depending on the event type. --- #### Event: `delivered` Triggered when an email is successfully delivered. ```json { "event": "delivered", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "time": 1713100000, "mxHostname": "mx.example.com", "response": "250 OK" } ``` | Field | Type | Description | |-------|------|-------------| | event | string | Always `delivered` | | id | string | `message_id` of the original email | | recipient | string | Recipient email address | | time | integer | Delivery timestamp (Unix ms) | | mxHostname | string | MX server that accepted the email | | response | string | SMTP response from the receiving server | --- #### Event: `bounced` Triggered when an email bounces. Includes a `category` field to distinguish hard and soft bounce. ```json { "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": "" } ``` | Field | Type | Description | |-------|------|-------------| | event | string | Always `bounce` | | id | string | `message_id` of the original email | | to | string | Recipient email address | | time | integer | Event timestamp (Unix ms) | | response | string | SMTP error response | | category | string | `hard_bounce` (permanent, e.g. invalid address) or `soft_bounce` (temporary, e.g. mailbox full) | | user | string | Reserved | | seq | string | Reserved | | returnPath | string | Return path header | **Category values:** | Value | Trigger condition | Description | |-------|-------------------|-------------| | `hard_bounce` | `REJECTED` | Permanent failure — invalid address or domain | | `soft_bounce` | `DEFERRED` | Temporary failure — server busy or mailbox full | --- #### Event: `dropped` Triggered when an email is dropped (suppressed before sending). ```json { "action": "drop", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "reason": "Suppressed address", "user": "", "seq": "" } ``` | Field | Type | Description | |-------|------|-------------| | action | string | Always `drop` | | id | string | `message_id` of the original email | | recipient | string | Recipient email address | | reason | string | Reason the email was dropped | | user | string | Reserved | | seq | string | Reserved | --- ### 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) ```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) ```js 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 | Sự kiện | Mô tả | |---------|-------| | `delivered` | Email đã được gửi thành công vào hộp thư của người nhận | | `bounced` | Email bị bounce — có thể là hard bounce (địa chỉ không tồn tại) hoặc soft bounce (server từ chối tạm thời) | | `dropped` | Email bị hủy trước khi gửi | --- ### 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. ```json { "event": "delivered", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "time": 1713100000, "mxHostname": "mx.example.com", "response": "250 OK" } ``` | Trường | Kiểu | Mô tả | |--------|------|-------| | event | string | Luôn là `delivered` | | id | string | `message_id` của email gốc | | recipient | string | Địa chỉ email người nhận | | time | integer | Timestamp gửi thành công (Unix ms) | | mxHostname | string | MX server đã nhận email | | response | string | Phản hồi SMTP từ server nhận | --- #### Sự kiện: `bounced` Kích hoạt khi email bị bounce. Có trường `category` phân biệt hard/soft bounce. ```json { "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": "" } ``` | Trường | Kiểu | Mô tả | |--------|------|-------| | event | string | Luôn là `bounce` | | id | string | `message_id` của email gốc | | to | string | Địa chỉ email người nhận | | time | integer | Timestamp sự kiện (Unix ms) | | response | string | Thông báo lỗi SMTP | | category | string | `hard_bounce` (lỗi vĩnh viễn) hoặc `soft_bounce` (lỗi tạm thời) | | user | string | Dự phòng | | seq | string | Dự phòng | | returnPath | string | Header return path | **Giá trị category:** | Giá trị | Điều kiện | Mô tả | |---------|-----------|-------| | `hard_bounce` | `REJECTED` | Lỗi vĩnh viễn — địa chỉ hoặc domain không tồn tại | | `soft_bounce` | `DEFERRED` | Lỗi tạm thời — server bận hoặc hộp thư đầy | --- #### Sự kiện: `dropped` Kích hoạt khi email bị hủy (bị chặn trước khi gửi). ```json { "action": "drop", "id": "550e8400-e29b-41d4-a716-446655440000@bizfly.vn", "recipient": "user@example.com", "reason": "Suppressed address", "user": "", "seq": "" } ``` | Trường | Kiểu | Mô tả | |--------|------|-------| | action | string | Luôn là `drop` | | id | string | `message_id` của email gốc | | recipient | string | Địa chỉ email người nhận | | reason | string | Lý do email bị hủy | | user | string | Dự phòng | | seq | string | Dự phòng | --- ### 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) ```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) ```js 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); }); ``` tags: - subpackage_mail responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Mail_WebHook_Response_200' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/PostRequestBadRequestError' requestBody: content: multipart/form-data: schema: type: object properties: {} servers: - url: https:/ description: https://{uri} components: schemas: Mail_WebHook_Response_200: type: object properties: code: type: integer status: type: string message_id: type: string format: email required: - code - status - message_id title: Mail_WebHook_Response_200 PostResponsesContentApplicationJsonSchemaErrorsItems: type: object properties: msg: type: string param: type: string location: type: string required: - msg - param - location title: PostResponsesContentApplicationJsonSchemaErrorsItems PostRequestBadRequestError: type: object properties: errors: type: array items: $ref: >- #/components/schemas/PostResponsesContentApplicationJsonSchemaErrorsItems required: - errors title: PostRequestBadRequestError ``` ## Examples **Request** ```json {} ``` **Response** ```json { "code": 200, "status": "Save mail success", "message_id": "bfe53336-5758-4e02-b44e-85e0d6df7ad0@bizfly.vn" } ``` **SDK Code** ```python Mail_WebHook_example import requests url = "https://https/" payload = "-----011000010111000001101001--\r\n" headers = {"Content-Type": "multipart/form-data; boundary=---011000010111000001101001"} response = requests.post(url, data=payload, headers=headers) print(response.json()) ``` ```javascript Mail_WebHook_example const url = 'https://https/'; const form = new FormData(); const options = {method: 'POST'}; options.body = form; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Mail_WebHook_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://https/" payload := strings.NewReader("-----011000010111000001101001--\r\n") req, _ := http.NewRequest("POST", url, payload) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Mail_WebHook_example require 'uri' require 'net/http' url = URI("https://https/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request.body = "-----011000010111000001101001--\r\n" response = http.request(request) puts response.read_body ``` ```java Mail_WebHook_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://https/") .body("-----011000010111000001101001--\r\n") .asString(); ``` ```php Mail_WebHook_example request('POST', 'https://https/', [ 'headers' => [ 'Content-Type' => 'multipart/form-data; boundary=---011000010111000001101001', ], ]); echo $response->getBody(); ``` ```csharp Mail_WebHook_example using RestSharp; var client = new RestClient("https://https/"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "multipart/form-data; boundary=---011000010111000001101001"); request.AddParameter("undefined", "-----011000010111000001101001--\r\n", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Mail_WebHook_example import Foundation let parameters = [] let boundary = "---011000010111000001101001" var body = "" var error: NSError? = nil for param in parameters { let paramName = param["name"]! body += "--\(boundary)\r\n" body += "Content-Disposition:form-data; name=\"\(paramName)\"" if let filename = param["fileName"] { let contentType = param["content-type"]! let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8) if (error != nil) { print(error as Any) } body += "; filename=\"\(filename)\"\r\n" body += "Content-Type: \(contentType)\r\n\r\n" body += fileContent } else if let paramValue = param["value"] { body += "\r\n\r\n\(paramValue)" } } let request = NSMutableURLRequest(url: NSURL(string: "https://https/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```