← Back to HomeKembali ke Beranda

API Documentation

Complete guide to using Firentia Mail API for developers and bots.Panduan lengkap menggunakan API Firentia Mail untuk developer dan bot.

AuthenticationAutentikasi

All API v1 requests require an API Key via the apikey query parameter.

Semua request API v1 membutuhkan API Key melalui parameter query apikey.

How to get API Key: Login to admin panel or check /config endpoint. Cara mendapatkan API Key: Login ke panel admin atau cek endpoint /config. 
curl "https://firentia.store/api/v1/messages?address=test@firentia.store&apikey=YOUR_API_KEY"
GET /config

Get server configuration including API key, available domains, and MX host. No authentication required.Ambil konfigurasi server termasuk API key, domain tersedia, dan MX host. Tidak perlu autentikasi.

Response

{
  "domain": "firentia.store",
  "domains": ["firentia.store", "jayan.web.id", "ryuuut.my.id"],
  "apiKey": "your-api-key",
  "mxHost": "mail.firentia.store"
}
GET /api/domains

List all active (verified + shared) domains. No authentication required.Daftar semua domain aktif (terverifikasi + shared). Tidak perlu autentikasi.

Response

{
  "ok": true,
  "domains": ["firentia.store", "jayan.web.id", "ryuuut.my.id", "stacyer.biz.id", "toddis.web.id"]
}
POST /mailbox/generate

Generate a new email address on a specific domain. No authentication required.Buat alamat email baru di domain tertentu. Tidak perlu autentikasi.

Request Body

{
  "user": "myname",
  "domain": "firentia.store"
}

Response

{
  "ok": true,
  "email": "myname@firentia.store",
  "domain": "firentia.store"
}
GET /api/v1/messages

Get all messages for a specific address or domain. Requires API key.Ambil semua pesan untuk alamat atau domain tertentu. Membutuhkan API key.

Parameters

Example RequestContoh Request

curl "https://firentia.store/api/v1/messages?address=test@firentia.store&apikey=YOUR_API_KEY"

Response

[
  {
    "id": "a1b2c3d4-...",
    "address": "test@firentia.store",
    "domain": "firentia.store",
    "from_name": "Google",
    "from_addr": "noreply@google.com",
    "to_addr": "test@firentia.store",
    "subject": "Your verification code",
    "body_text": "Your code is 123456",
    "otp": "123456",
    "received_at": "2026-10-24T15:00:00.000Z",
    "is_read": 0
  }
]
GET /api/v1/messages/:id

Get a single message by ID (includes full HTML body). Requires API key.Ambil satu pesan berdasarkan ID (termasuk body HTML lengkap). Membutuhkan API key.

Parameters

Example RequestContoh Request

curl "https://firentia.store/api/v1/messages/a1b2c3d4-...?apikey=YOUR_API_KEY"

Response

{
  "id": "a1b2c3d4-...",
  "address": "test@firentia.store",
  "from_addr": "noreply@google.com",
  "subject": "Your verification code",
  "body_text": "Your code is 123456",
  "body_html": "<p>Your code is <b>123456</b></p>",
  "otp": "123456",
  "received_at": "2026-10-24T15:00:00.000Z",
  "is_read": 1
}
DELETE /api/v1/messages/:id

Delete a single message by ID. Requires API key.Hapus satu pesan berdasarkan ID. Membutuhkan API key.

Example RequestContoh Request

curl -X DELETE "https://firentia.store/api/v1/messages/a1b2c3d4-...?apikey=YOUR_API_KEY"

Response

{ "ok": true }
POST /api/v1/messages/delete-all

Delete all messages for a specific address or domain. Requires API key.Hapus semua pesan untuk alamat atau domain tertentu. Membutuhkan API key.

Request Body

{
  "address": "test@firentia.store",
  "apikey": "YOUR_API_KEY"
}

Response

{ "ok": true, "deleted": 5 }
GET /api/v1/domain/wait-otp

Long-poll for incoming OTP. Server blocks up to the specified timeout waiting for a message containing an OTP code.Long-poll untuk OTP masuk. Server menunggu hingga timeout yang ditentukan untuk pesan yang mengandung kode OTP.

Parameters

Example RequestContoh Request

curl "https://firentia.store/api/v1/domain/wait-otp?address=test@firentia.store&timeout=60&apikey=YOUR_API_KEY"

Success ResponseResponse Sukses

{
  "ok": true,
  "otp": "123456",
  "id": "a1b2c3d4-...",
  "address": "test@firentia.store",
  "subject": "Your verification code",
  "from": "noreply@google.com"
}

Timeout ResponseResponse Timeout

{ "ok": false, "error": "timeout", "waited_ms": 60000 }
POST /api/domains

Add and verify a custom domain. Set MX record to the server's MX host first.Tambah dan verifikasi domain custom. Atur MX record ke MX host server terlebih dahulu.

Request Body

{ "domain": "mydomain.com" }

Response

{
  "ok": true,
  "verified": true,
  "domain": "mydomain.com",
  "message": "Domain aktif! Email siap dipakai."
}
Note: If MX is not pointing to the server, verified will be false and the response includes the required mx_host. Catatan: Jika MX belum mengarah ke server, verified akan false dan response menyertakan mx_host yang dibutuhkan.

Python ExampleContoh Python

import requests

BASE = "https://firentia.store"
API_KEY = "YOUR_API_KEY"

# Generate email
res = requests.post(f"{BASE}/mailbox/generate", json={
    "user": "testuser",
    "domain": "firentia.store"
})
email = res.json()["email"]
print(f"Email: {email}")

# Check inbox
msgs = requests.get(
    f"{BASE}/api/v1/messages",
    params={"address": email, "apikey": API_KEY}
).json()

for m in msgs:
    print(f"From: {m['from_addr']}")
    print(f"Subject: {m['subject']}")
    if m.get("otp"):
        print(f"OTP: {m['otp']}")

JavaScript Example (Node.js)Contoh JavaScript (Node.js)

const BASE = "https://firentia.store";
const API_KEY = "YOUR_API_KEY";

// Generate email
const gen = await fetch(`${BASE}/mailbox/generate`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ user: "testuser", domain: "firentia.store" })
});
const { email } = await gen.json();
console.log("Email:", email);

// Check inbox
const msgs = await fetch(
  `${BASE}/api/v1/messages?address=${encodeURIComponent(email)}&apikey=${API_KEY}`
).then(r => r.json());

msgs.forEach(m => {
  console.log(`From: ${m.from_addr}`);
  console.log(`Subject: ${m.subject}`);
  if (m.otp) console.log(`OTP: ${m.otp}`);
});

Error CodesKode Error

CodeKode DescriptionDeskripsi
200SuccessBerhasil
401Invalid or missing API keyAPI key tidak valid atau tidak ada
404Resource not foundResource tidak ditemukan
500Server errorServer error