BizMail Delivery API — Overview

🇬🇧 English

Introduction

BizMail provides two methods to send transactional emails from your application:

REST API — Send emails via HTTP requests using JWT authentication
SMTP — Send emails via standard SMTP protocol using your BizMail Portal credentials

All credentials (username, password) are managed through the BizMail Portal.

REST API

Base URL: https://smtp-api.bizfly.vn

Authentication Flow

BizMail API uses JWT (JSON Web Token) for authentication.

JavaScript

Python

Java

cURL

Shell

1 1. Call POST /api/1.0/auth/token  →  get access_token (1 day) + refresh_token (90 days)
2 2. Attach access_token to every API request:
3        Authorization: Bearer <access_token>
4 3. When access_token expires → call POST /api/1.0/auth/refresh to get a new pair
5 4. When refresh_token expires → repeat step 1

Endpoints

Method	Endpoint	Auth	Description
POST	`/api/1.0/auth/token`	❌	Get access token & refresh token
POST	`/api/1.0/auth/refresh`	❌	Refresh access token using refresh token
POST	`/api/1.0/mail/store`	✅ Bearer JWT	Send a transactional email

1. Auth — Get Token

POST /api/1.0/auth/token

Obtain a JWT access token and refresh token using credentials from BizMail Portal.

Request Body (JSON):

Field	Type	Required	Description
username	string	✅	Username from BizMail Portal
password	string	✅	Password from BizMail Portal

Response:

JavaScript

Python

Java

cURL

Shell

1 {
2   "success": true,
3   "access_token": "<jwt_access_token>",
4   "refresh_token": "<jwt_refresh_token>",
5   "token_type": "Bearer",
6   "expires_in": 86400
7 }

2. Auth — Refresh Token

POST /api/1.0/auth/refresh

Get a new access token and refresh token using an existing refresh token.

Request Body (JSON):

Field	Type	Required	Description
refresh_token	string	✅	Refresh token from `/auth/token`

Response:

JavaScript

Python

Java

cURL

Shell

1 {
2   "success": true,
3   "access_token": "<new_jwt_access_token>",
4   "refresh_token": "<new_jwt_refresh_token>",
5   "token_type": "Bearer",
6   "expires_in": 86400
7 }

3. Send Mail

POST /api/1.0/mail/store

Send a transactional email with optional attachments.

Headers: Authorization: Bearer , Content-Type: multipart/form-data

Key Fields:

Field	Required	Description
from	✅	Sender email
from_name	✅	Sender display name
subject	✅	Email subject
to / to[]	✅	Recipient(s)
cc / cc[]	❌	CC recipient(s)
bcc / bcc[]	❌	BCC recipient(s)
text	✅ *	Plain text body
html	✅ *	HTML body
attachments[]	❌	File attachments (max 20MB total)

* At least one of text or html is required.

Response:

JavaScript

Python

Java

cURL

Shell

1 {
2   "code": 200,
3   "status": "Save mail success",
4   "message_id": "uuid@bizfly.vn"
5 }

4. Webhook — Mail Tracking

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

Trigger 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

Configure your webhook URL in the BizMail Portal under your account settings. See the Webhook Tracking document for full payload details.

Configure your webhook URL in the BizMail Portal under your account settings.

SMTP

For applications that support SMTP natively (e.g. Laravel Mail, PHPMailer, Nodemailer), you can send emails directly via BizMail’s SMTP server.

SMTP Configuration

Setting	Value
Host	`smtp-api.bizfly.vn`
Port (TLS)	`2525`
Port (SSL)	`2465`
Username	Your username from BizMail Portal
Password	Your password from BizMail Portal
Encryption	TLS (port 2525) / SSL (port 2465)

Example — Laravel (`.env`)

JavaScript

Python

Java

cURL

Shell

1 MAIL_MAILER=smtp
2 MAIL_HOST=smtp-api.bizfly.vn
3 MAIL_PORT=2525
4 MAIL_USERNAME=your_username
5 MAIL_PASSWORD=your_password
6 MAIL_ENCRYPTION=tls
7 MAIL_FROM_ADDRESS=info@yourdomain.com
8 MAIL_FROM_NAME="Your Company"

Example — PHPMailer

JavaScript

Python

Java

cURL

Shell

1 $mail = new PHPMailer(true);
2 $mail->isSMTP();
3 $mail->Host       = 'smtp-api.bizfly.vn';
4 $mail->SMTPAuth   = true;
5 $mail->Username   = 'your_username';
6 $mail->Password   = 'your_password';
7 $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
8 $mail->Port       = 2525;

Example — Nodemailer

JavaScript

Python

Java

cURL

Shell

1 const transporter = nodemailer.createTransport({
2   host: 'smtp-api.bizfly.vn',
3   port: 2525,
4   secure: false,
5   auth: {
6     user: 'your_username',
7     pass: 'your_password',
8   },
9 });

🇻🇳 Tiếng Việt

Giới thiệu

BizMail cung cấp hai phương thức gửi email giao dịch từ ứng dụng của bạn:

REST API — Gửi email qua HTTP request sử dụng xác thực JWT
SMTP — Gửi email qua giao thức SMTP chuẩn sử dụng thông tin đăng nhập từ BizMail Portal

Tất cả thông tin đăng nhập (username, password) được quản lý qua BizMail Portal.

REST API

Base URL: https://smtp-api.bizfly.vn

Luồng xác thực

BizMail API sử dụng JWT (JSON Web Token) để xác thực.

JavaScript

Python

Java

cURL

Shell

1 1. Gọi POST /api/1.0/auth/token  →  nhận access_token (1 ngày) + refresh_token (90 ngày)
2 2. Gắn access_token vào mọi API request:
3        Authorization: Bearer <access_token>
4 3. Khi access_token hết hạn → gọi POST /api/1.0/auth/refresh để lấy cặp token mới
5 4. Khi refresh_token hết hạn → lặp lại bước 1

Danh sách Endpoint

Method	Endpoint	Auth	Mô tả
POST	`/api/1.0/auth/token`	❌	Lấy access token & refresh token
POST	`/api/1.0/auth/refresh`	❌	Làm mới access token bằng refresh token
POST	`/api/1.0/mail/store`	✅ Bearer JWT	Gửi email giao dịch

1. Auth — Lấy Token

POST /api/1.0/auth/token

Lấy JWT access token và refresh token từ thông tin đăng nhập trên BizMail Portal.

Request Body (JSON):

Tham số	Kiểu	Bắt buộc	Mô tả
username	string	✅	Username từ BizMail Portal
password	string	✅	Password từ BizMail Portal

Response:

JavaScript

Python

Java

cURL

Shell

1 {
2   "success": true,
3   "access_token": "<jwt_access_token>",
4   "refresh_token": "<jwt_refresh_token>",
5   "token_type": "Bearer",
6   "expires_in": 86400
7 }

2. Auth — Refresh Token

POST /api/1.0/auth/refresh

Lấy access token và refresh token mới từ refresh token hiện có.

Request Body (JSON):

Tham số	Kiểu	Bắt buộc	Mô tả
refresh_token	string	✅	Refresh token nhận từ `/auth/token`

Response:

JavaScript

Python

Java

cURL

Shell

1 {
2   "success": true,
3   "access_token": "<new_jwt_access_token>",
4   "refresh_token": "<new_jwt_refresh_token>",
5   "token_type": "Bearer",
6   "expires_in": 86400
7 }

3. Gửi Mail

POST /api/1.0/mail/store

Gửi email giao dịch, hỗ trợ file đính kèm.

Headers: Authorization: Bearer , Content-Type: multipart/form-data

Các tham số chính:

Tham số	Bắt buộc	Mô tả
from	✅	Email người gửi
from_name	✅	Tên hiển thị người gửi
subject	✅	Tiêu đề email
to / to[]	✅	Email người nhận (1 hoặc nhiều)
cc / cc[]	❌	Email CC (1 hoặc nhiều)
bcc / bcc[]	❌	Email BCC (1 hoặc nhiều)
text	✅ *	Nội dung text thuần
html	✅ *	Nội dung HTML
attachments[]	❌	File đính kèm (tổng tối đa 20MB)

* Phải có ít nhất một trong text hoặc html.

Response:

JavaScript

Python

Java

cURL

Shell

1 {
2   "code": 200,
3   "status": "Save mail success",
4   "message_id": "uuid@bizfly.vn"
5 }

4. Webhook — Tracking Mail

BizMail gửi các sự kiện tracking theo thời gian thực đến webhook URL được cấu hình trong BizMail Portal.

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 hình webhook URL trong BizMail Portal tại phần cài đặt tài khoản. Xem chi tiết payload tại tài liệu Webhook Tracking.

SMTP

Dành cho các ứng dụng hỗ trợ SMTP gốc (Laravel Mail, PHPMailer, Nodemailer…), bạn có thể gửi email trực tiếp qua SMTP server của BizMail.

Thông tin cấu hình SMTP

Thông số	Giá trị
Host	`smtp-api.bizfly.vn`
Port (TLS)	`2525`
Port (SSL)	`2465`
Username	Username từ BizMail Portal
Password	Password từ BizMail Portal
Mã hoá	TLS (port 2525) / SSL (port 2465)

Ví dụ — Laravel (`.env`)

JavaScript

Python

Java

cURL

Shell

1 MAIL_MAILER=smtp
2 MAIL_HOST=smtp-api.bizfly.vn
3 MAIL_PORT=2525
4 MAIL_USERNAME=your_username
5 MAIL_PASSWORD=your_password
6 MAIL_ENCRYPTION=tls
7 MAIL_FROM_ADDRESS=info@yourdomain.com
8 MAIL_FROM_NAME="Tên công ty"

Ví dụ — PHPMailer

JavaScript

Python

Java

cURL

Shell

1 $mail = new PHPMailer(true);
2 $mail->isSMTP();
3 $mail->Host       = 'smtp-api.bizfly.vn';
4 $mail->SMTPAuth   = true;
5 $mail->Username   = 'your_username';
6 $mail->Password   = 'your_password';
7 $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
8 $mail->Port       = 2525;

Ví dụ — Nodemailer

JavaScript

Python

Java

cURL

Shell

1 const transporter = nodemailer.createTransport({
2   host: 'smtp-api.bizfly.vn',
3   port: 2525,
4   secure: false,
5   auth: {
6     user: 'your_username',
7     pass: 'your_password',
8   },
9 });

BizMail Delivery API — Overview

🇬🇧 English

Introduction

REST API

Authentication Flow

JavaScript

Python

Java

cURL

Shell

Endpoints

1. Auth — Get Token

JavaScript

Python

Java

cURL

Shell

2. Auth — Refresh Token

JavaScript

Python

Java

cURL

Shell

3. Send Mail

JavaScript

Python

Java

cURL

Shell

4. Webhook — Mail Tracking

SMTP

SMTP Configuration

Example — Laravel (.env)

JavaScript

Python

Java

cURL

Shell

Example — PHPMailer

JavaScript

Python

Java

cURL

Shell

Example — Nodemailer

JavaScript

Python

Java

cURL

Shell

🇻🇳 Tiếng Việt

Giới thiệu

REST API

Luồng xác thực

JavaScript

Python

Java

cURL

Shell

Danh sách Endpoint

1. Auth — Lấy Token

JavaScript

Python

Java

cURL

Shell

2. Auth — Refresh Token

JavaScript

Python

Java

cURL

Shell

3. Gửi Mail

JavaScript

Python

Java

cURL

Shell

4. Webhook — Tracking Mail

SMTP

Example — Laravel (`.env`)

Ví dụ — Laravel (`.env`)