// DOKUMENTASI API
MAILDROPY
API REFERENCE
REST API lengkap untuk mengintegrasikan layanan email sementara MAILDROPY ke dalam aplikasi Anda. Semua endpoint menggunakan prefix /wxapi dan mengembalikan data dalam format JSON.
// AUTENTIKASI
Autentikasi
Saat ini API tidak memerlukan autentikasi khusus. Semua endpoint bisa diakses langsung.
ℹ️
Catatan sesi: Beberapa endpoint (generate, set-email) menyimpan email aktif ke cookie sesi browser.
Jika Anda mengakses API dari luar browser (misalnya curl atau kode), gunakan header
Content-Type: application/json dan kirim body sebagai JSON.
// ERROR HANDLING
Error Handling
Semua error dikembalikan dalam format JSON dengan field error berisi pesan kesalahan.
| HTTP Code | Kondisi | Contoh Response |
|---|---|---|
| 200 | Request berhasil | { "success": true, ... } |
| 400 | Parameter tidak valid / kurang | { "error": "Missing params" } |
| 404 | Email / pesan tidak ditemukan | { "error": "Inbox not found" } |
// EMAIL
Generate Email
Buat alamat email sementara baru secara otomatis dengan nama acak yang unik.
POST
/wxapi/generate
Buat email acak baru
▾
Deskripsi
Menghasilkan alamat email sementara yang unik dengan format kata+kata+angka@domain.com. Email yang dihasilkan langsung aktif dan siap menerima pesan.
Request Body (opsional, JSON)
| Field | Tipe | Wajib | Default | Keterangan |
|---|---|---|---|---|
| domain | string | opsional | maildropy.com | Domain yang digunakan. Harus termasuk dalam daftar domain tersedia. |
Contoh Request
CURL
curl -X POST "https://maildropy.com/wxapi/generate" \
-H "Content-Type: application/json" \
-d '{"domain":"maildropy.com"}'
JAVASCRIPT (fetch)
const res = await fetch("/wxapi/generate", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ domain: "maildropy.com" })
});
const data = await res.json();
console.log(data.email); // "swiftwolf3821@maildropy.com"
Response
200 OK
{
"email": "swiftwolf3821@maildropy.com",
"domain": "maildropy.com",
"success": true
}
🧪 Coba Langsung
domain
POST
/wxapi/set-email
Set email kustom
▾
Deskripsi
Mengaktifkan alamat email tertentu yang dipilih sendiri. Inbox langsung dibuat jika belum ada.
Request Body (JSON)
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
| string | wajib | Alamat email lengkap, contoh: toko@domain.com |
Contoh Request
CURL
curl -X POST "https://maildropy.com/wxapi/set-email" \
-H "Content-Type: application/json" \
-d '{"email":"toko@maildropy.com"}'
Response
200 OK
{
"email": "toko@maildropy.com",
"success": true
}
🧪 Coba Langsung
email
// PESAN
Ambil Semua Pesan
Mengambil daftar semua pesan di inbox berdasarkan alamat email.
GET
/wxapi/messages/:email
Daftar semua pesan
▾
Path Parameter
| Parameter | Tipe | Wajib | Keterangan |
|---|---|---|---|
| string | wajib | Alamat email yang ingin dicek. Contoh: user@domain.com |
Contoh Request
CURL
curl "https://maildropy.com/wxapi/messages/nama@maildropy.com"
JAVASCRIPT
const email = "nama@maildropy.com";
const res = await fetch(`/wxapi/messages/${email}`);
const data = await res.json();
console.log(data.count); // jumlah pesan
console.log(data.messages); // array pesan
Response
{
"email": "nama@maildropy.com",
"exists": true,
"count": 3,
"unread": 1,
"messages": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"from": "pengirim@example.com",
"subject": "Verifikasi Akun Anda",
"date": "2025-01-15T10:30:00.000Z",
"receivedAt": "2025-01-15T10:30:05.000Z",
"read": false,
"preview": "Klik link berikut untuk verifikasi...",
"hasHtml": true,
"attachments": 0
}
]
}
{
"email": "nama@maildropy.com",
"exists": false,
"count": 0,
"unread": 0,
"messages": []
}
🧪 Coba Langsung
:email
GET
/wxapi/message/:email/:id
Isi pesan lengkap
▾
Deskripsi
Mengambil isi lengkap sebuah pesan termasuk HTML body, plain text, dan informasi lampiran. Memanggil endpoint ini otomatis menandai pesan sebagai dibaca.
Path Parameters
| Parameter | Tipe | Wajib | Keterangan |
|---|---|---|---|
| string | wajib | Alamat email pemilik inbox | |
| :id | string (UUID) | wajib | ID pesan dari hasil /wxapi/messages/:email |
Contoh Request
CURL
curl "https://maildropy.com/wxapi/message/nama@maildropy.com/550e8400-xxxx"
Response — 200 OK
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"from": "pengirim@example.com",
"to": "nama@maildropy.com",
"subject": "Verifikasi Akun Anda",
"text": "Klik link berikut untuk verifikasi...",
"html": "<div>Klik link berikut...</div>",
"date": "2025-01-15T10:30:00.000Z",
"receivedAt": "2025-01-15T10:30:05.000Z",
"read": true,
"attachments": []
}
DEL
/wxapi/message/:email/:id
Hapus satu pesan
▾
Contoh Request
CURL
curl -X DELETE "https://maildropy.com/wxapi/message/nama@maildropy.com/550e8400-xxxx"
Response — 200 OK
{ "success": true }
DEL
/wxapi/inbox/:email
Hapus seluruh inbox
▾
Deskripsi
Menghapus seluruh inbox beserta semua pesan di dalamnya. Operasi ini tidak bisa dibatalkan.
Contoh Request
CURL
curl -X DELETE "https://maildropy.com/wxapi/inbox/nama@maildropy.com"
Response — 200 OK
{ "success": true }
// DOMAIN
Daftar Domain
Mengambil semua domain yang tersedia untuk pembuatan email sementara.
GET
/wxapi/domains
Semua domain tersedia
▾
Deskripsi
Mengembalikan daftar domain bawaan, domain kustom yang sudah didaftarkan, dan satu domain acak untuk digunakan langsung.
Contoh Request
CURL
curl "https://maildropy.com/wxapi/domains"
Response — 200 OK
{
"domains": ["maildropy.com", "mail2.contoh.com"], // domain bawaan
"custom": ["tokosaya.com", "startup.id"], // domain kustom terdaftar
"random": "maildropy.com", // domain acak untuk dipakai
"total": 4
}
🧪 Coba Langsung
POST
/wxapi/domain/register
Daftarkan domain kustom
▾
Deskripsi
Mendaftarkan domain kustom Anda sebagai mailserver penerima. Setelah mendaftar, semua email ke *@domain-anda.com bisa diterima lewat sistem ini.
Request Body (JSON)
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
| domain | string | wajib | Nama domain yang ingin didaftarkan, contoh: tokosaya.com |
| string | wajib | Email pertama yang akan dibuat di domain ini, contoh: halo@tokosaya.com |
Contoh Request
CURL
curl -X POST "https://maildropy.com/wxapi/domain/register" \
-H "Content-Type: application/json" \
-d '{"domain":"tokosaya.com","email":"halo@tokosaya.com"}'
Response — 200 OK
{
"success": true,
"domain": "tokosaya.com",
"email": "halo@tokosaya.com"
}
GET
/wxapi/domain/:domain
Cek status domain
▾
Contoh Request
CURL
curl "https://maildropy.com/wxapi/domain/tokosaya.com"
Response — 200 OK
{
"domain": "tokosaya.com",
"registered": true,
"type": "custom" // "built-in" | "custom" | "unregistered"
}
// SERVER
Statistik Server
GET
/wxapi/stats
Info statistik server
▾
Response — 200 OK
{
"totalInboxes": 142,
"totalMessages": 893,
"customDomains": 7,
"builtInDomains": 2,
"uptime": 86400 // detik sejak server start
}
🧪 Coba Langsung
// REALTIME
Real-time via WebSocket
Selain REST API, MAILDROPY mendukung push notification real-time menggunakan Socket.IO.
JAVASCRIPT — Socket.IO Client
// Install: npm install socket.io-client
import { io } from "socket.io-client";
const socket = io("https://maildropy.com");
// Subscribe ke inbox
socket.emit("subscribe", "email@maildropy.com");
// Dengarkan pesan masuk baru
socket.on("new_message", (msg) => {
console.log("📬 Pesan baru!", msg);
// msg.id, msg.from, msg.subject, msg.date, msg.preview
});
socket.on("disconnect", () => {
console.log("Koneksi WebSocket terputus");
});
⚡
Event new_message hanya memberikan ringkasan pesan (id, from, subject, preview). Untuk isi lengkap, gunakan
GET /wxapi/message/:email/:id setelah menerima event.