API Reference

Tích hợp ZuckMails vào ứng dụng của bạn. Tạo email tạm, nhận OTP tự động qua REST API.

Base URL https://api.zuckmails.com
Note: https://zuckmails.com/api cũng hoạt động tương đương. Admin panel tại https://admin.zuckmails.com
Xác thực: Gửi token qua header Authorization: Bearer YOUR_TOKEN hoặc X-Api-Key: tm_xxx cho API key.
Plan: Free = 10 credits, email sống 10 phút | Pro = 100 credits, 15 phút | Enterprise = 9999 credits, 60 phút.
Authentication
POST /auth/register Đăng ký tài khoản mới Public

Body

ParameterTypeDescription
usernamestring3-30 ký tự (a-z, 0-9, _)
passwordstringTối thiểu 6 ký tự
emailstring optionalEmail liên hệ (phải đúng định dạng)

Response 201

{ "success": true, "data": { "id": 1, "username": "myuser", "role": "user", "credits": 10, "token": "eyJhbG..." } }
POST /auth/login Đăng nhập, nhận JWT token Public

Body

ParameterTypeDescription
usernamestringTên đăng nhập
passwordstringMật khẩu

Sử dụng Token

// Header (bắt buộc cho mọi request cần xác thực) Authorization: Bearer eyJhbGciOi... // Cookie (tự động set khi login qua web UI) Cookie: token=eyJhbGciOi...
GET /auth/me Thông tin tài khoản + token mới Auth

Response

{ "success": true, "data": { "id": 1, "username": "myuser", "credits": 9, "plan": "free", "plan_expires_at": null, "token": "eyJ...new_token" } }
POST /auth/change-password Đổi mật khẩu Auth

Body

ParameterTypeDescription
old_passwordstringMật khẩu hiện tại
new_passwordstringMật khẩu mới (tối thiểu 6 ký tự)
GET /auth/credits/history Lịch sử credits Auth

Query Parameters

ParameterTypeDescription
limitnumber optionalSố bản ghi (mặc định 50, tối đa 200)
Domains
GET /domains Danh sách domain khả dụng Public

Response

{ "success": true, "data": [ { "id": 1, "domain": "zuckmails.com", "created_at": "2026-03-01T00:00:00Z" } ] }
GET /domains/:domain/dns-guide Hướng dẫn cấu hình DNS Public

Trả về hướng dẫn cấu hình MX, SPF, DMARC cho domain của bạn.

Emails
POST /emails/generate Tạo email tạm thời (1 credit) Auth

Body

ParameterTypeDescription
domainstring optionalChọn domain, bỏ trống = ngẫu nhiên
usernamestring optionalCustom alias, 2-30 ký tự (chỉ Pro/Enterprise)

Response 201

{ "success": true, "data": { "address": "[email protected]", "domain": "zuckmails.com", "expires_at": "2026-03-20T10:10:00Z", "credits_remaining": 9 } }
POST /emails/rent Thuê email (API Key) API Key

Headers

X-Api-Key: tm_your_api_key

Body

ParameterTypeDescription
domainstring optionalChọn domain
usernamestring optional2-30 ký tự (a-z 0-9 . _ -)
expiry_hoursnumber optionalThời gian tồn tại (mặc định 24h)
GET /emails/my Danh sách email của tôi Auth

Query Parameters

ParameterTypeDescription
limitnumber optionalSố email tối đa (mặc định 50, tối đa 200)
GET /emails/:address/inbox Đọc hộp thư Auth

Query Parameters

ParameterTypeDescription
limitnumber optionalSố tin nhắn tối đa (mặc định 50, tối đa 200)

Response

{ "success": true, "data": { "address": "[email protected]", "message_count": 2, "messages": [{ "id": 101, "sender": "[email protected]", "subject": "Your code is 847293", "body_text": "Your verification code is 847293", "body_html": "<html>...</html>", "is_read": false, "received_at": "2026-03-20T10:02:00Z", "otp": { "otp_code": "847293", "provider": "Facebook" } }] } }
GET /emails/:address/latest Tin nhắn mới nhất Auth

Trả về tin nhắn mới nhất của email. Response giống 1 item trong inbox.

GET /emails/:address/messages/:msgId Xem tin nhắn cụ thể Auth

Trả về nội dung tin nhắn và tự động đánh dấu là đã đọc.

DELETE /emails/:address Xóa email Auth

Xóa email và tất cả tin nhắn. Không hoàn lại credit.

OTP Extraction
GET /emails/:address/otp Trích xuất OTP Auth

Query Parameters

ParameterTypeDescription
providerstring optionalLọc theo nhà cung cấp

Supported Providers

facebook google instagram tiktok twitter telegram microsoft apple whatsapp discord linkedin snapchat

Response

{ "success": true, "data": { "otp_code": "847293", "provider": "Facebook", "message_id": 101, "sender": "[email protected]", "received_at": "2026-03-20T10:02:00Z" } }
GET /emails/:address/otp/wait Chờ OTP (long polling, max 120s) Auth

Query Parameters

ParameterTypeDescription
providerstring optionalLọc theo provider
timeoutnumber optionalThời gian chờ tối đa, giây (mặc định 60, max 120)
Server giữ kết nối mở, kiểm tra mỗi 2 giây. Trả về ngay khi tìm thấy OTP. Tối đa 3 kết nối đồng thời cho mỗi email.
Real-time (SSE)
GET /emails/:address/stream Nhận email thời gian thực Auth

Events

// Kết nối thành công data: {"type":"connected","address":"[email protected]"} // Email mới (bao gồm OTP nếu có) data: {"type":"new_message","message":{"id":101,"sender":"[email protected]","subject":"Your code","otp":{"otp_code":"847293","provider":"Facebook"}}}

JavaScript Example

const source = new EventSource( 'https://api.zuckmails.com/emails/[email protected]/stream' ); source.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === 'new_message') { console.log('Email mới từ:', data.message.sender); if (data.message.otp) { console.log('OTP:', data.message.otp.otp_code); } } };
API Keys
GET /keys/check Kiểm tra API key và credits API Key

Headers

X-Api-Key: tm_your_api_key

Response

{ "success": true, "data": { "user_name": "customer1", "credits": 95, "is_active": true } }
Webhooks
POST /webhooks Tạo webhook nhận thông báo email Pro+

Body

ParameterTypeDescription
urlstringURL callback (HTTPS/HTTP, không được là IP nội bộ)
eventsstring[] optionalMặc định: ["email.received"]

Webhook Payload

// Server gửi POST đến URL của bạn với header: // X-Hub-Signature-256: sha256=HMAC_SHA256(body, secret) // X-Event-Type: email.received { "event": "email.received", "data": { "address": "[email protected]", "sender": "[email protected]", "subject": "Your code is 847293", "otp": { "otp_code": "847293", "provider": "Facebook" } }, "timestamp": "2026-03-20T10:02:00Z" }
Luôn xác thực X-Hub-Signature-256 bằng HMAC-SHA256 với secret trước khi xử lý. Tối đa 5 webhooks mỗi tài khoản.
GET /webhooks Danh sách webhooks Auth

Trả về tất cả webhooks của bạn.

DELETE /webhooks/:id Xóa webhook Auth

Xóa webhook theo ID.

Plans
GET /plans Xem các gói dịch vụ Public

Response

{ "free": { "credits": 5, "expiry_minutes": 10, "custom_alias": false }, "pro": { "credits": 100, "expiry_minutes": 15, "custom_alias": true }, "enterprise": { "credits": 9999, "expiry_minutes": 60, "custom_alias": true } }
POST /plans/upgrade Yêu cầu nâng cấp plan Auth

Body

ParameterTypeDescription
planstring"pro" hoặc "enterprise"
payment_methodstring optionalPhương thức thanh toán (momo, bank, crypto)
transaction_idstring optionalMã giao dịch
Admin sẽ xác nhận thanh toán và kích hoạt plan cho bạn.
Rate Limiting
Mỗi response trả về headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.
Khi vượt giới hạn, API trả về 429 Too Many Requests.
EndpointGiới hạn
POST /api/auth/login10 req/phút
POST /api/auth/register5 req/phút
/api/emails/*60 req/phút
/api/* (chung)120 req/phút
Code Examples
cURL Complete Flow Register → Generate → Wait OTP
# 1. Đăng ký tài khoản curl -s -X POST https://api.zuckmails.com/auth/register \ -H "Content-Type: application/json" \ -d '{"username":"myuser","password":"mypass123"}' # Lưu token từ response TOKEN="eyJ...your_token" # 2. Tạo email tạm thời curl -s -X POST https://api.zuckmails.com/emails/generate \ -H "Authorization: Bearer $TOKEN" # 3. Chờ OTP từ Facebook (tối đa 60 giây) curl -s "https://api.zuckmails.com/emails/[email protected]/otp/wait?provider=facebook&timeout=60" \ -H "Authorization: Bearer $TOKEN" # 4. Đọc hộp thư curl -s https://api.zuckmails.com/emails/[email protected]/inbox \ -H "Authorization: Bearer $TOKEN" # 5. Xóa email curl -s -X DELETE https://api.zuckmails.com/emails/[email protected] \ -H "Authorization: Bearer $TOKEN"
JS JavaScript / Node.js Fetch API + async/await
const API = 'https://api.zuckmails.com'; // Đăng nhập const login = await fetch(`${API}/auth/login`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'myuser', password: 'mypass123' }) }).then(r => r.json()); const headers = { 'Authorization': `Bearer ${login.data.token}` }; // Tạo email const email = await fetch(`${API}/emails/generate`, { method: 'POST', headers }).then(r => r.json()); console.log('Email:', email.data.address); // Chờ OTP (max 90 giây) const otp = await fetch( `${API}/emails/${encodeURIComponent(email.data.address)}/otp/wait?timeout=90`, { headers } ).then(r => r.json()); if (otp.data) { console.log('OTP:', otp.data.otp_code, 'from', otp.data.provider); }
PY Python requests library
import requests, urllib.parse API = "https://api.zuckmails.com" # Đăng nhập login = requests.post(f"{API}/auth/login", json={ "username": "myuser", "password": "mypass123" }).json() headers = {"Authorization": f"Bearer {login['data']['token']}"} # Tạo email email = requests.post(f"{API}/emails/generate", headers=headers).json() addr = email["data"]["address"] print(f"Email: {addr}") # Chờ OTP (max 90 giây) encoded = urllib.parse.quote(addr, safe="") otp = requests.get( f"{API}/emails/{encoded}/otp/wait", params={"timeout": 90}, headers=headers ).json() if otp["data"]: print(f"OTP: {otp['data']['otp_code']}")
C# C# / .NET HttpClient + System.Text.Json
using System.Net.Http; using System.Net.Http.Json; using System.Text.Json; var client = new HttpClient(); var api = "https://api.zuckmails.com"; // Login var loginRes = await client.PostAsJsonAsync( $"{api}/auth/login", new { username = "myuser", password = "mypass123" }); var loginData = await loginRes.Content.ReadFromJsonAsync<JsonElement>(); var token = loginData.GetProperty("data").GetProperty("token").GetString(); client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}"); // Generate email var genRes = await client.PostAsync($"{api}/emails/generate", null); var genData = await genRes.Content.ReadFromJsonAsync<JsonElement>(); var addr = genData.GetProperty("data").GetProperty("address").GetString(); // Wait for OTP var otpData = await client.GetFromJsonAsync<JsonElement>( $"{api}/emails/{addr}/otp/wait?timeout=60"); if (otpData.GetProperty("data").ValueKind != JsonValueKind.Null) Console.WriteLine($"OTP: {otpData.GetProperty("data").GetProperty("otp_code")}");
MetaMax Integration
MetaMax Custom Mail for MetaMax
Header Authorization: Bearer YOUR_TOKEN
Link Get Email https://api.zuckmails.com/emails/generate?email={Email}
Cắt Email "address":"([^"]+)
Cắt ID "address":"([^"]+)
Link Get Code https://api.zuckmails.com/emails/{Email}/otp/wait?timeout=60
Cắt Code "otp_code":"(.*?)"
List Domain zuckmails.com
Response mẫu:
Get Email: {"success":true,"data":{"address":"[email protected]","expires_at":"..."}}
Get Code: {"success":true,"data":{"otp_code":"847293","provider":"Facebook"}}
API Key Sử dụng API Key thay vì JWT Token Automation
Header X-Api-Key: tm_your_api_key
Link Get Email https://api.zuckmails.com/emails/rent?email={Email}
Cắt Email "address":"([^"]+)
Link Get Code https://api.zuckmails.com/emails/{Email}/otp/wait?timeout=60
Cắt Code "otp_code":"(.*?)"