REST API Reference

URL gốc

https://hn.manage.bizflycloud.vn/api/email-transactional/v1

Xác thực

Xác thực request bằng API key thông qua header X-API-KEY:

X-API-KEY: your_api_key_here

API key được tạo trong dashboard (với quyền full_access) hoặc thông qua endpoint Tạo API Key (có thể cấu hình quyền). Key đầy đủ chỉ hiển thị một lần khi tạo — hãy lưu trữ an toàn.

Các mức quyền

Each API key has a permission level that controls access:

Permission	Mô tả
`full_access`	Toàn bộ thao tác (tạo, gửi, xoá)
`sending_access`	Gửi email + thao tác đọc
`read_only`	Chỉ có quyền xem

Định dạng phản hồi

Tất cả phản hồi đều ở dạng JSON. Các phản hồi thành công trả về mã trạng thái 2xx.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00.000000Z"
}

Định dạng lỗi

{
  "detail": "Error description"
}

Mã trạng thái

Code	Mô tả
`200`	Thành công
`400`	Tham số request không hợp lệ
`401`	Thiếu hoặc API key không hợp lệ
`403`	Không đủ quyền
`404`	Không tìm thấy tài nguyên
`422`	Body request không hợp lệ
`500`	Lỗi server

Phân trang

List endpoints use page and per_page query parameters:

Parameter	Default	Max	Mô tả
`page`	1	—	Số trang (bắt đầu từ 1)
`per_page`	20	100	Số item mỗi trang

Content-Language

Thêm header Content-Language: vi để nhận thông báo lỗi bằng tiếng Việt, hoặc en (mặc định) cho tiếng Anh.

Emails

Gửi Email

Gửi email giao dịch tới một hoặc nhiều người nhận.

POST /emails

Quyền: sending_access or full_access

Request Body

Field	Type	Bắt buộc	Mô tả
`from`	string	Yes	Sender email. Format: `"Name <email@domain.com>"` or `"email@domain.com"`. Must be from a verified domain.
`to`	string[]	Yes	Recipient email addresses
`subject`	string	Yes	Email subject line
`html`	string	Yes*	HTML email content
`text`	string	Yes*	Plain text content
`cc`	string[]	No	CC recipients
`bcc`	string[]	No	BCC recipients
`reply_to`	string	No	Reply-to address
`attachments`	object[]	No	File attachments (see below)
`headers`	object	No	Custom email headers
`tags`	object[]	No	Analytics tags

*Ít nhất một trong hai loại html hoặc text là bắt buộc.

Ví dụ request

curl -X POST https://hn.manage.bizflycloud.vn/api/email-transactional/v1/emails \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Hello World",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
  }'

Phản hồi `200`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "status": "queued",
  "created_at": "2024-01-15T10:30:00.000000Z"
}

Danh sách email

Lấy danh sách email đã gửi với phân trang và bộ lọc.

GET /emails

Quyền: read_only, sending_access, or full_access

Query Parameters

Parameter	Type	Default	Mô tả
`page`	integer	1	Số trang
`per_page`	integer	20	Số item mỗi trang (max 100)
`status`	string	—	Lọc theo trạng thái. Comma-separated: `queued`, `sent`, `delivered`, `bounced`, `deferred`, `delayed`
`created_at_from`	string	—	Lower bound (ISO-8601 UTC, e.g. `2024-01-01T00:00:00Z`)
`created_at_to`	string	—	Upper bound (ISO-8601 UTC)

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/emails?page=1&per_page=10&status=delivered" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "from": "hello@yourdomain.com",
      "to": ["user@example.com"],
      "subject": "Hello World",
      "status": "Delivered",
      "created_at": "2024-01-15T10:30:00.000000"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 10,
  "stats": [
    { "label": "Delivered", "count": 35, "percentage": 83.3 },
    { "label": "Queued", "count": 5, "percentage": 11.9 },
    { "label": "Delayed", "count": 2, "percentage": 4.8 }
  ]
}

Lấy thông tin email

Lấy chi tiết email đã gửi theo message ID.

GET /emails/{message_id}

Quyền: read_only, sending_access, or full_access

Path Parameters

Parameter	Type	Mô tả
`message_id`	string	The message ID returned from send

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/emails/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "subject": "Hello World",
  "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  "status": "Delivered",
  "created_at": "2024-01-15T10:30:00.000000",
  "delivered_at": "2024-01-15T10:30:05.000000"
}

Domains

Danh sách domain

Lấy danh sách tất cả domain của tài khoản.

GET /domains

Quyền: read_only, sending_access, or full_access

Query Parameters

Parameter	Type	Default	Mô tả
`page`	integer	1	Số trang
`per_page`	integer	20	Số item mỗi trang (max 100)
`search`	string	—	Search by domain name

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/domains?page=1&per_page=10" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "data": [
    {
      "id": "dom_123",
      "domain": "yourdomain.com",
      "status": "verified",
      "created_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "total": 3,
  "total_verified": 2,
  "page": 1,
  "per_page": 10
}

Tạo domain

Thêm domain gửi email mới. Trả về DNS records cần cấu hình để xác minh.

POST /domains

Quyền: full_access

Request Body

Field	Type	Bắt buộc	Mô tả
`domain`	string	Yes	Domain name (e.g., `yourdomain.com`)

Ví dụ request

curl -X POST https://hn.manage.bizflycloud.vn/api/email-transactional/v1/domains \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "yourdomain.com" }'

Phản hồi `200`

{
  "id": "dom_123",
  "domain": "yourdomain.com",
  "status": "pending",
  "dns_records": [
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:_spf.bizflycloud.vn ~all",
      "purpose": "spf"
    },
    {
      "type": "MX",
      "name": "@",
      "value": "capmx-re30.bizflycloud.vn",
      "priority": 5,
      "purpose": "mx"
    },
    {
      "type": "MX",
      "name": "@",
      "value": "capmx-re40.bizflycloud.vn",
      "priority": 5,
      "purpose": "mx"
    },
    {
      "type": "MX",
      "name": "@",
      "value": "capmx-re20.bizflycloud.vn",
      "priority": 15,
      "purpose": "mx"
    },
    {
      "type": "TXT",
      "name": "dkim._domainkey",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh...",
      "purpose": "dkim"
    }
  ],
  "created_at": "2024-01-15T10:30:00.000000Z"
}

Lấy thông tin domain

Lấy chi tiết và trạng thái xác minh DNS theo thời gian thực của domain.

GET /domains/{domain_id}

Quyền: read_only, sending_access, or full_access

Path Parameters

Parameter	Type	Mô tả
`domain_id`	string	Domain ID (format: `dom_123`)

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/domains/dom_123" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "id": "dom_123",
  "domain": "yourdomain.com",
  "status": "verified",
  "dns_records": [
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:_spf.bizflycloud.vn ~all",
      "purpose": "spf",
      "verified": true
    },
    {
      "type": "MX",
      "name": "@",
      "value": "capmx-re30.bizflycloud.vn",
      "priority": 5,
      "purpose": "mx",
      "verified": true
    },
    {
      "type": "TXT",
      "name": "dkim._domainkey",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh...",
      "purpose": "dkim",
      "verified": true
    }
  ],
  "verified_at": "2024-01-15T12:00:00.000000Z"
}

Xác minh domain

Xác minh DNS records cho domain. Nếu tất cả bản ghi (SPF, MX, DKIM) hợp lệ, domain sẽ được đánh dấu đã xác minh.

POST /domains/{domain_id}/verify

Quyền: full_access

Path Parameters

Parameter	Type	Mô tả
`domain_id`	string	Domain ID (format: `dom_123`)

Ví dụ request

curl -X POST "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/domains/dom_123/verify" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "id": "dom_123",
  "domain": "yourdomain.com",
  "status": "verified",
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 ...", "purpose": "spf", "verified": true },
    { "type": "MX", "name": "@", "value": "capmx-re30.bizflycloud.vn", "priority": 5, "purpose": "mx", "verified": true },
    { "type": "TXT", "name": "dkim._domainkey", "value": "v=DKIM1; ...", "purpose": "dkim", "verified": true }
  ],
  "verified_at": "2024-01-15T12:00:00.000000Z"
}

If verification fails, status is "pending" and verified is false on failing records.

Lấy thông tin domain Quota

Lấy quota gửi email và mức sử dụng của domain.

GET /domains/{domain_id}/quota

Quyền: read_only, sending_access, or full_access

Path Parameters

Parameter	Type	Mô tả
`domain_id`	string	Domain ID (format: `dom_123`)

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/domains/dom_123/quota" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "domain": "yourdomain.com",
  "daily_limit": 20000,
  "daily_used": 1523,
  "daily_remaining": 18477,
  "hourly_limit": 833,
  "hourly_used": 45,
  "hourly_remaining": 788,
  "monthly_limit": 600000,
  "monthly_used": 32150,
  "monthly_remaining": 567850,
  "pack_code": "ET20",
  "pack_name": "ET20 - Goi khoi dau hoan hao"
}

Xoá domain

Xoá vĩnh viễn domain và toàn bộ bản ghi liên quan (DKIM, sender, tracking settings).

DELETE /domains/{domain_id}

Quyền: full_access

Path Parameters

Parameter	Type	Mô tả
`domain_id`	string	Domain ID (format: `dom_123`)

Ví dụ request

curl -X DELETE "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/domains/dom_123" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "id": "dom_123",
  "deleted": true
}

Senders

Tạo sender

Tạo sender để gửi email. Bắt buộc phải tạo sender trước khi gửi email từ domain.

POST /senders

Quyền: full_access

Điều kiện tiên quyết:

Tên miền phải tồn tại và được xác minh thông qua Xác minh domain

Request Body

Field	Type	Bắt buộc	Mô tả
`account`	string	Yes	Địa chỉ email người gửi (ví dụ: `noreply@yourdomain.com`)
`domain`	string	Yes	Tên miền (ví dụ: `yourdomain.com`). Phải trùng khớp với tên miền của tài khoản.
`password`	string	Yes	Mật khẩu SMTP (tối thiểu 8 ký tự)

Ví dụ request

curl -X POST https://hn.manage.bizflycloud.vn/api/email-transactional/v1/senders \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "noreply@yourdomain.com",
    "domain": "yourdomain.com",
    "password": "YourSecurePassword123"
  }'

Phản hồi `200`

{
  "id": "42",
  "account": "noreply@yourdomain.com",
  "domain": "yourdomain.com",
  "active": true,
  "daily_limit": 500,
  "hourly_limit": 50,
  "created_at": "2024-01-15T10:30:00.000000Z"
}

Đổi mật khẩu sender

Đổi mật khẩu SMTP của sender. Cập nhật cả mật khẩu đăng nhập trực tiếp lẫn thông tin xác thực nội bộ dùng cho luồng gửi qua API.

PATCH /v1/senders/{account}/password Quyền: full_access

Điều kiện tiên quyết:

Sender phải đã được tạo thông qua Tạo sender

Path Parameter:

Field	Type	Mô tả
account	string	Địa chỉ email của sender (ví dụ: noreply@yourdomain.com )

Request Body:

Field	Type	Bắt buộc	Mô tả
password	string	Yes Mật khẩu SMTP mới (tối thiểu 8 ký tự)

Ví dụ request:

curl -X PATCH https://hn.manage.bizflycloud.vn/api/email-transactional/v1/senders/noreply@yourdomain.com/password \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "NewSecurePassword123"
  }'
Phản hồi 200:
{
  "message": "Password updated successfully"
}

Errors:

Status	Condition
403	Domain không thuộc về user hiện tại
404	Sender không tồn tại (smtp_credentials_not_found)
422	password dưới 8 ký tự

API Keys

Tạo API Key

Tạo API key mới. Key đầy đủ chỉ trả về một lần duy nhất — hãy lưu trữ an toàn.

POST /api-keys

Quyền: full_access

Request Body

Field	Type	Bắt buộc	Mô tả
`name`	string	Yes	Tên mô tả cho khóa API
`permission`	string	No	Mức độ quyền hạn: `full_access` (mặc định), `sending_access`, `read_only`
`expires_in_days`	integer	No	Hạn sử dụng (ngày): 7, 30, 60, 90, 180, 365. Bỏ qua nếu không có hạn sử dụng.

Ví dụ request

curl -X POST https://hn.manage.bizflycloud.vn/api/email-transactional/v1/api-keys \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "permission": "sending_access",
    "expires_in_days": 365
  }'

Phản hồi `200`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Server",
  "key": "etrans_abc123xyz...",
  "permission": "sending_access",
  "expires_at": "2025-01-15T10:30:00.000000Z",
  "created_at": "2024-01-15T10:30:00.000000Z"
}

Danh sách API Key

List all active API keys. For security, the full key value is never shown after creation.

GET /api-keys

Quyền: read_only, sending_access, or full_access

Query Parameters

Parameter	Type	Default	Mô tả
`page`	integer	1	Số trang
`per_page`	integer	20	Số item mỗi trang (max 100)

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/api-keys?page=1&per_page=10" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production Server",
      "key": "etrans_...xyz",
      "permission": "sending_access",
      "expires_at": "2025-01-15T10:30:00.000000Z",
      "is_expired": false,
      "created_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 10
}

Lấy thông tin API Key

Get details of a specific API key.

GET /api-keys/{key_id}

Quyền: read_only, sending_access, or full_access

Path Parameters

Parameter	Type	Mô tả
`key_id`	string	API key ID

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/api-keys/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Server",
  "permission": "sending_access",
  "expires_at": "2025-01-15T10:30:00.000000Z",
  "is_expired": false,
  "active": true,
  "created_at": "2024-01-15T10:30:00.000000Z",
  "updated_at": "2024-01-15T10:30:00.000000Z"
}

Xoá API Key

Revoke an API key. This is permanent — applications using this key will stop authenticating immediately.

DELETE /api-keys/{key_id}

Quyền: full_access

Path Parameters

Parameter	Type	Mô tả
`key_id`	string	ID khóa API cần thu hồi

Ví dụ request

curl -X DELETE "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/api-keys/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "deleted": true
}

Logs

Danh sách log transaction

Lấy log gửi email cho tất cả domain thuộc người dùng đã xác thực.

GET /logs

Quyền: read_only, sending_access, or full_access

Query Parameters

Parameter	Type	Default	Mô tả
`page`	integer	1	Số trang
`per_page`	integer	20	Số item mỗi trang (max 100)
`log_after`	string	—	Lọc nhật ký sau mốc thời gian này (ISO-8601 UTC)
`log_before`	string	—	Lọc nhật ký trước mốc thời gian này (ISO-8601 UTC)
`action`	string	—	Lọc theo hành động: `delivered`, `deferred`, `rejected`, `bounced`, `sender`, `queue`
`sender`	string	—	Lọc theo email người gửi
`recipient`	string	—	Lọc theo địa chỉ email người nhận
`message_id`	string	—	Lọc theo ID tin nhắn
`source`	string	—	Lọc theo nguồn: `api`, `smtp` (phân cách bằng dấu phẩy)
`sorts`	string	`-timestamp`	Sắp xếp theo trường có tiền tố chỉ hướng (`-` để sắp xếp giảm dần)

Ví dụ request

curl -X GET "https://hn.manage.bizflycloud.vn/api/email-transactional/v1/logs?page=1&per_page=10&action=delivered&source=api" \
  -H "X-API-KEY: your_api_key"

Phản hồi `200`

{
  "logs": [
    {
      "message_id": "550e8400-e29b-41d4-a716-446655440000",
      "action": "Delivered",
      "sender": "hello@yourdomain.com",
      "recipient": "user@example.com",
      "timestamp": "2024-01-15T10:30:05.000Z",
      "source": "API"
    }
  ],
  "total": 156,
  "page": 1,
  "per_page": 10,
  "stats": [
    { "label": "Delivered", "count": 120, "percentage": 76.9 },
    { "label": "Delayed", "count": 25, "percentage": 16.0 },
    { "label": "Bounced", "count": 11, "percentage": 7.1 }
  ]
}

Email Transaction Account