Giới thiệu

GhostInbox REST API

API RESTful để tạo và quản lý hộp thư email tạm thời. Tất cả response trả về JSON. Các API yêu cầu xác thực bằng API key qua header X-Api-Key.

Cần xác thực
Header: X-Api-Key: tm_xxxx...
Real-time
WebSocket (Socket.io) cho email mới tức thì
SMTP Port 25
Gửi email đến server qua port 25
Cấu hình

Base URL

Base URL
https://hoanggiakiet.com/api
Response format
{
  "success": true,
  "data": { ... }
}
Lỗi

Xử lý lỗi

Khi có lỗi, API trả về success: false và trường error mô tả lỗi.

{
  "success": false,
  "error": "Mailbox not found"
}
HTTP Status Ý nghĩa
200 Thành công
401 Thiếu API key
403 API key không hợp lệ
404 Không tìm thấy mailbox/email
500 Lỗi server
POST /api/auth/register Đăng ký tài khoản

Tạo tài khoản người dùng mới trên hệ thống.

curl -X POST https://hoanggiakiet.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "user123", "password": "password123", "email": "user@example.com"}'
const res = await fetch('https://hoanggiakiet.com/api/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'user123',
    password: 'password123',
    email: 'user@example.com'
  })
});
const data = await res.json();
console.log(data);
POST /api/auth/login Đăng nhập tài khoản

Xác thực tài khoản và trả về thông tin đăng nhập kèm API key.

curl -X POST https://hoanggiakiet.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user123", "password": "password123"}'
const res = await fetch('https://hoanggiakiet.com/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'user123',
    password: 'password123'
  })
});
const data = await res.json();
console.log(data);
POST /api/login Đăng nhập API trực tiếp

Xác thực tài khoản trực tiếp qua API. Thích hợp cho các công cụ tích hợp tự động.

curl -X POST https://hoanggiakiet.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user123", "password": "password123"}'
const res = await fetch('https://hoanggiakiet.com/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'user123',
    password: 'password123'
  })
});
const data = await res.json();
console.log(data.token); // Đây chính là API Key (api_key) của bạn
GET /api/auth/me Lấy thông tin tài khoản

Lấy thông tin người dùng hiện tại gắn liền với API key. Có thể dùng các endpoint thay thế GET /api/me hoặc GET /api/user.

curl -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/auth/me
const res = await fetch('https://hoanggiakiet.com/api/auth/me', {
  headers: { 'X-Api-Key': apiKey }
});
const data = await res.json();
console.log(data.user);
POST /api/auth/change-password Đổi mật khẩu tài khoản

Thay đổi mật khẩu đăng nhập của tài khoản người dùng hiện tại.

curl -X POST https://hoanggiakiet.com/api/auth/change-password \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"oldPassword": "old_password_here", "newPassword": "new_password_here"}'
const res = await fetch('https://hoanggiakiet.com/api/auth/change-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey
  },
  body: JSON.stringify({
    oldPassword: 'old_password_here',
    newPassword: 'new_password_here'
  })
});
const data = await res.json();
console.log(data);
POST /api/auth/change-email Đổi email liên hệ

Cập nhật địa chỉ email liên hệ chính thức của người dùng.

curl -X POST https://hoanggiakiet.com/api/auth/change-email \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"newEmail": "new_email@example.com"}'
const res = await fetch('https://hoanggiakiet.com/api/auth/change-email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey
  },
  body: JSON.stringify({
    newEmail: 'new_email@example.com'
  })
});
const data = await res.json();
console.log(data);
POST /api/auth/regenerate-key Tạo lại API Key mới

Thu hồi API key cũ và cấp lại một API key mới cho tài khoản.

curl -X POST https://hoanggiakiet.com/api/auth/regenerate-key \
  -H "X-Api-Key: <your_api_key>"
const res = await fetch('https://hoanggiakiet.com/api/auth/regenerate-key', {
  method: 'POST',
  headers: { 'X-Api-Key': apiKey }
});
const data = await res.json();
console.log(data.api_key);
POST /api/mailbox Tạo hòm thư mới

Tạo một địa chỉ email tạm thời ngẫu nhiên hoặc tùy chọn theo prefix và tên miền. Có thể sử dụng endpoint thay thế POST /api/create-email.

Request Body (JSON, tùy chọn)
Tham số Kiểu Mặc định Mô tả
ttl number 3600 Thời gian sống (giây), tối thiểu 300, tối đa 600
prefix string (ngẫu nhiên) Prefix tùy chọn (3-30 ký tự, chỉ chứa chữ thường, số, dấu chấm, gạch ngang, gạch dưới)
domain string hoanggiakiet.com Tên miền để tạo hòm thư. Phải là tên miền mặc định hoặc tên miền do bạn sở hữu
Thử ngay 
curl -X POST https://hoanggiakiet.com/api/mailbox \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"ttl": 3600, "prefix": "mycustomprefix", "domain": "hoanggiakiet.com"}'
const res = await fetch('https://hoanggiakiet.com/api/mailbox', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey 
  },
  body: JSON.stringify({ 
    ttl: 3600,
    prefix: 'mycustomprefix',
    domain: 'hoanggiakiet.com'
  })
});
const { mailbox } = await res.json();
console.log(mailbox.address);
import requests
 
res = requests.post('https://hoanggiakiet.com/api/mailbox',
    headers={'X-Api-Key': api_key},
    json={
        'ttl': 3600,
        'prefix': 'mycustomprefix',
        'domain': 'hoanggiakiet.com'
    })
mailbox = res.json()['mailbox']
print(mailbox['address'])
GET /api/mailbox/:idOrAddress Lấy thông tin mailbox

Lấy thông tin của một mailbox theo ID hòm thư hoặc địa chỉ email.

Thử ngay
curl -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/mailbox/c7a8b9c0-1234-5678-90ab-cdef12345678
const idOrAddress = 'c7a8b9c0-1234-5678-90ab-cdef12345678';
const res = await fetch(`/api/mailbox/${encodeURIComponent(idOrAddress)}`, {
  headers: { 'X-Api-Key': apiKey }
});
const { mailbox } = await res.json();
import requests
from urllib.parse import quote
 
id_or_address = 'c7a8b9c0-1234-5678-90ab-cdef12345678'
res = requests.get(f'https://hoanggiakiet.com/api/mailbox/{quote(id_or_address)}',
    headers={'X-Api-Key': api_key})
print(res.json())
GET /api/emails Lấy tất cả mailbox của tài khoản

Lấy danh sách tất cả các hòm thư email tạm thời đang hoạt động mà tài khoản sở hữu.

Thử ngay
curl -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/emails
const res = await fetch('https://hoanggiakiet.com/api/emails', {
  headers: { 'X-Api-Key': apiKey }
});
const data = await res.json();
console.log(data.mailboxes);
POST /api/mailbox/:idOrAddress/extend Gia hạn thời gian sống mailbox

Gia hạn thời hạn hết hạn của một mailbox đang hoạt động.

Request Body (JSON, tùy chọn)
Tham số Kiểu Mặc định Mô tả
ttl number 3600 Thời gian gia hạn thêm (giây), tối thiểu 300, tối đa 600 
curl -X POST https://hoanggiakiet.com/api/mailbox/mymailbox@hoanggiakiet.com/extend \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"ttl": 3600}'
const res = await fetch('https://hoanggiakiet.com/api/mailbox/mymailbox@hoanggiakiet.com/extend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey
  },
  body: JSON.stringify({ ttl: 3600 })
});
const data = await res.json();
console.log(data.mailbox);
DELETE /api/mailbox/:idOrAddress Xóa mailbox

Xóa vĩnh viễn mailbox và tất cả email bên trong bằng ID hòm thư hoặc địa chỉ email.

Thử ngay
curl -X DELETE -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/mailbox/123456
const idOrAddress = '123456';
await fetch(`/api/mailbox/${encodeURIComponent(idOrAddress)}`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': apiKey }
});
import requests
from urllib.parse import quote
 
id_or_address = '123456'
requests.delete(f'https://hoanggiakiet.com/api/mailbox/{quote(id_or_address)}',
    headers={'X-Api-Key': api_key})
GET /api/mailbox/:idOrAddress/emails Lấy danh sách email hòm thư

Lấy danh sách tất cả email trong mailbox theo ID hoặc địa chỉ email, sắp xếp mới nhất lên trước.

Thử ngay
curl -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/mailbox/c7a8b9c0-1234-5678-90ab-cdef12345678/emails
const idOrAddress = 'c7a8b9c0-1234-5678-90ab-cdef12345678';
const res = await fetch(`/api/mailbox/${encodeURIComponent(idOrAddress)}/emails`, {
  headers: { 'X-Api-Key': apiKey }
});
const { emails } = await res.json();
emails.forEach(e => console.log(e.subject));
import requests
from urllib.parse import quote
 
id_or_address = 'c7a8b9c0-1234-5678-90ab-cdef12345678'
res = requests.get(f'https://hoanggiakiet.com/api/mailbox/{quote(id_or_address)}/emails',
    headers={'X-Api-Key': api_key})
for email in res.json()['emails']:
    print(email['subject'])
GET /api/messages Lấy tất cả email thuộc tài khoản

Lấy tất cả email của tài khoản. Có thể lọc theo mailbox thông qua query parameter. Các endpoint thay thế giống hệt: GET /api/email-messages hoặc GET /api/message-by-email (yêu cầu lọc).

Query Parameters (Tùy chọn / Bắt buộc tùy endpoint)
Tham số Kiểu Mặc định Mô tả
email hoặc address string - Địa chỉ hòm thư email cần lọc (ví dụ: mymailbox@hoanggiakiet.com). Lưu ý: Bắt buộc phải truyền đối với endpoint GET /api/message-by-email (nếu thiếu sẽ trả về lỗi 400 Bad Request: "Missing email query parameter"). Đối với GET /api/messages và GET /api/email-messages tham số này là tùy chọn.
Thử ngay
curl -H "X-Api-Key: <your_api_key>" "https://hoanggiakiet.com/api/messages?email=mymailbox@hoanggiakiet.com"
const res = await fetch('https://hoanggiakiet.com/api/messages', {
  headers: { 'X-Api-Key': apiKey }
});
const data = await res.json();
console.log(data.emails);
GET /api/email/:id Xem chi tiết email

Lấy toàn bộ nội dung email bao gồm HTML, text, và danh sách tệp đính kèm. Đánh dấu email là đã đọc.

Thử ngay
curl -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/email/123456789012
const id = '123456789012';
const res = await fetch(`/api/email/${id}`, {
  headers: { 'X-Api-Key': apiKey }
});
const { email, attachments } = await res.json();
console.log(email.subject, email.body_html);
import requests
 
id = '123456789012'
res = requests.get(f'https://hoanggiakiet.com/api/email/{id}',
    headers={'X-Api-Key': api_key})
data = res.json()
print(data['email']['subject'])
GET /api/read-message Đọc nội dung email (Query)

Lấy nội dung chi tiết của email và tệp đính kèm bằng cách truyền ID qua query parameter. Tự động đánh dấu email là đã đọc.

Query Parameters (Bắt buộc)
Tham số Kiểu Mặc định Mô tả
id string - ID của email cần đọc (ví dụ: 123456789012)
Thử ngay
curl -H "X-Api-Key: <your_api_key>" "https://hoanggiakiet.com/api/read-message?id=123456789012"
const id = '123456789012';
const res = await fetch(`https://hoanggiakiet.com/api/read-message?id=${id}`, {
  headers: { 'X-Api-Key': apiKey }
});
const data = await res.json();
console.log(data.email, data.attachments);
POST /api/email/:id/star Bật/tắt gắn sao email

Gắn sao (lưu trữ) hoặc bỏ gắn sao một email nhận được.

curl -X POST https://hoanggiakiet.com/api/email/123456789012/star \
  -H "X-Api-Key: <your_api_key>"
const res = await fetch('https://hoanggiakiet.com/api/email/123456789012/star', {
  method: 'POST',
  headers: { 'X-Api-Key': apiKey }
});
const data = await res.json();
console.log(data.email);
GET /api/emails/starred Lấy danh sách thư gắn sao

Lấy danh sách tất cả các email đã gắn sao thuộc về tài khoản.

curl -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/emails/starred
const res = await fetch('https://hoanggiakiet.com/api/emails/starred', {
  headers: { 'X-Api-Key': apiKey }
});
const data = await res.json();
console.log(data.emails);
POST /api/email/send Gửi email nội bộ

Gửi một email đến hòm thư khác trong cùng hệ thống.

Request Body (JSON, bắt buộc)
Tham số Kiểu Mô tả
from string Địa chỉ người gửi (phải thuộc sở hữu của tài khoản)
to string Địa chỉ người nhận trong hệ thống
subject string Tiêu đề email
body_text string Nội dung văn bản thuần (tùy chọn)
body_html string Nội dung định dạng HTML (tùy chọn) 
curl -X POST https://hoanggiakiet.com/api/email/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"from": "sender@hoanggiakiet.com", "to": "recip@hoanggiakiet.com", "subject": "Test", "body_text": "Hi"}'
const res = await fetch('https://hoanggiakiet.com/api/email/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey
  },
  body: JSON.stringify({
    from: 'sender@hoanggiakiet.com',
    to: 'recip@hoanggiakiet.com',
    subject: 'Test',
    body_text: 'Hi'
  })
});
const data = await res.json();
console.log(data);
DELETE /api/email/:id Xóa email

Xóa một email theo ID.

Thử ngay
curl -X DELETE -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/email/123456789012
const id = '123456789012';
await fetch(`/api/email/${id}`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': apiKey }
});
import requests
 
id = '123456789012'
requests.delete(f'https://hoanggiakiet.com/api/email/{id}',
    headers={'X-Api-Key': api_key})
POST /api/delete-emails Xóa hàng loạt email hoặc hòm thư

Xóa đồng thời nhiều email hoặc mailbox chỉ với một request.

Request Body (JSON, tùy chọn)
Tham số Kiểu Mặc định Mô tả
email string - Xóa duy nhất mailbox này
emails array of string - Danh sách các địa chỉ mailbox muốn xóa
ids array of string - Danh sách các ID email muốn xóa
Thử ngay
curl -X POST https://hoanggiakiet.com/api/delete-emails \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"ids": ["123456789012", "987654321098"], "emails": ["trash@hoanggiakiet.com"]}'
const res = await fetch('https://hoanggiakiet.com/api/delete-emails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey
  },
  body: JSON.stringify({
    ids: ['123456789012', '987654321098'],
    emails: ['trash@hoanggiakiet.com']
  })
});
const data = await res.json();
console.log(data.message);
GET /api/auth/domains Danh sách tên miền

Lấy danh sách tất cả tên miền có sẵn cho tài khoản (bao gồm cả tên miền riêng). Có thể dùng các endpoint tương đương: GET /api/domains.

Thử ngay
curl -H "X-Api-Key: <your_api_key>" https://hoanggiakiet.com/api/auth/domains
const res = await fetch('https://hoanggiakiet.com/api/auth/domains', {
  headers: { 
    'X-Api-Key': apiKey 
  }
});
const data = await res.json();
console.log(data.domains);
POST /api/auth/add-domain Thêm tên miền riêng

Đăng ký thêm tên miền riêng vào hệ thống. Bản ghi MX phải được trỏ chính xác về server máy chủ thư trước khi thêm.

Request Body (JSON, bắt buộc)
Tham số Kiểu Mặc định Mô tả
domain string - Tên miền muốn thêm (ví dụ: mydomain.com)
Thử ngay
curl -X POST https://hoanggiakiet.com/api/auth/add-domain \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"domain": "mydomain.com"}'
const res = await fetch('https://hoanggiakiet.com/api/auth/add-domain', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey 
  },
  body: JSON.stringify({ domain: 'mydomain.com' })
});
const data = await res.json();
console.log(data.message);
POST /api/auth/remove-domain Xóa tên miền riêng

Xóa tên miền riêng khỏi tài khoản của bạn.

Request Body (JSON, bắt buộc)
Tham số Kiểu Mặc định Mô tả
domain string - Tên miền muốn xóa (ví dụ: mydomain.com)
Thử ngay
curl -X POST https://hoanggiakiet.com/api/auth/remove-domain \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your_api_key>" \
  -d '{"domain": "mydomain.com"}'
const res = await fetch('https://hoanggiakiet.com/api/auth/remove-domain', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey 
  },
  body: JSON.stringify({ domain: 'mydomain.com' })
});
const data = await res.json();
console.log(data.message);
Ví dụ

Luồng đầy đủ tự động

Mô phỏng toàn bộ vòng đời của hộp thư tạm thời: Tạo mailbox → Lấy thông tin chi tiết → Gửi email thử nội bộ → Lấy danh sách email → Xem nội dung email → Gắn sao email → Xóa email → Xóa mailbox. Nhấn chạy để thực hiện tự động.

1
Tạo mailbox mới
Chưa chạy
↓
2
Lấy chi tiết mailbox
Chưa chạy
↓
3
Gửi email nội bộ thử nghiệm
Chưa chạy
↓
4
Lấy danh sách thư nhận
Chưa chạy
↓
5
Đọc nội dung chi tiết thư
Chưa chạy
↓
6
Gắn sao (Star) thư
Chưa chạy
↓
7
Xóa thư vừa đọc
Chưa chạy
↓
8
Xóa mailbox hoàn tất
Chưa chạy
Ví dụ

JavaScript — Polling inbox

const apiKey = 'YOUR_API_KEY';

async function pollInbox(address, intervalMs = 5000) {
  const seen = new Set();

  setInterval(async () => {
    const res = await fetch(`/api/mailbox/${encodeURIComponent(address)}/emails`, {
      headers: { 'X-Api-Key': apiKey }
    });
    const { emails } = await res.json();

    for (const email of emails) {
      if (!seen.has(email.id)) {
        seen.add(email.id);
        console.log('New email:', email.subject);
        const detail = await fetch(`/api/email/${email.id}`, {
          headers: { 'X-Api-Key': apiKey }
        });
        const { email: full } = await detail.json();
        console.log(full.body_text);
      }
    }
  }, intervalMs);
}

const res = await fetch('/api/mailbox', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-Api-Key': apiKey
  },
  body: JSON.stringify({ ttl: 600 })
});
const data = await res.json();
const mailbox = data.mailbox;

console.log('Your email:', mailbox.address);
pollInbox(mailbox.address);
Ví dụ

Python — Tích hợp đơn giản

import requests
import time
from urllib.parse import quote

BASE = 'https://hoanggiakiet.com/api'
API_KEY = 'YOUR_API_KEY'
HEADERS = {'X-Api-Key': API_KEY}

def create_mailbox(ttl=600):
    res = requests.post(f'{BASE}/mailbox', headers=HEADERS, json={'ttl': ttl})
    return res.json()['mailbox']

def get_emails(address):
    res = requests.get(f'{BASE}/mailbox/{quote(address)}/emails', headers=HEADERS)
    return res.json().get('emails', [])

def read_email(email_id):
    res = requests.get(f'{BASE}/email/{email_id}', headers=HEADERS)
    return res.json()

mailbox = create_mailbox(ttl=600)
print(f"Email: {mailbox['address']}")
print(f"Expires: {mailbox['expires_at']}")

seen = set()
while True:
    emails = get_emails(mailbox['address'])
    for email in emails:
        if email['id'] not in seen:
            seen.add(email['id'])
            detail = read_email(email['id'])
            print(f"New: {detail['email']['subject']}")
    time.sleep(5)
Ví dụ

cURL — Workflow nhanh

API_KEY="YOUR_API_KEY"

curl -s -X POST https://hoanggiakiet.com/api/mailbox \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{"ttl":600}'

EMAIL_ID="d7637f91-e683-4feb-b2b6-e550b061c1c7"
curl -s -H "X-Api-Key: $API_KEY" "https://hoanggiakiet.com/api/email/$EMAIL_ID"

curl -X DELETE "https://hoanggiakiet.com/api/email/$EMAIL_ID"

curl -X DELETE "https://hoanggiakiet.com/api/mailbox/$ADDRESS"