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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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"
}

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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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://manage.bizflycloud.vn/email-transactional/api/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