Dokumentasi

Mailera API

Kelola kotak surat Microsoft (Outlook, Hotmail, Microsoft 365) secara menyeluruh melalui REST: tambahkan kotak surat, periksa status aktifnya, baca email, ambil kode OTP, kirim email, pindahkan email dari Email Sampah, dan terima webhook.

Pengantar

Semua endpoint berada di bawah satu URL dasar serta menerima dan mengembalikan JSON.

1Buat akun dan workspace Anda sendiri (gratis).
2Buka Pengaturan → API key, buat API key, lalu pilih izin aksesnya.
3Kirim API key melalui header X-API-Key pada setiap permintaan.

Respons berhasil memuat kolom data; respons error memuat kolom error dengan code dan message.

Buat workspace gratis

URL dasar

https://mailera.app/api/public/v1# 200{ "data": [ ... ], "next_cursor": "..." }# 4xx / 5xx{ "error": { "code": "not_found", "message": "..." } }

Autentikasi

Kirim API key Anda melalui header X-API-Key. API key diawali dengan mh_live_ dan hanya ditampilkan sekali saat dibuat; jika hilang, buat API key baru dan cabut yang lama.

Header Authorization dengan token Bearer yang berisi API key yang sama juga diterima.

API key dapat dibatasi ke daftar IP yang diizinkan; panggilan dari IP lain menerima 403.

cURL

curl https://mailera.app/api/public/v1/mailboxes \  -H "X-API-Key: mh_live_..."

Izin akses API key

Setiap API key memiliki satu atau beberapa izin akses. Memanggil endpoint tanpa izin akses yang sesuai akan mengembalikan 403 forbidden.

Izin akses	Mengizinkan
`read`	Baca kotak surat, email, kode OTP, dan lokasi email di Kotak Masuk/Email Sampah
`move`	Pindahkan email dari Email Sampah dan antar folder
`import`	Tambahkan kotak surat
`sync`	Minta sinkronisasi segera
`send`	Kirim, balas, dan teruskan email
`manage`	Jeda, lanjutkan, dan hapus kotak surat
`webhooks`	Kelola webhook

Error

Error selalu memuat code yang tetap dan message berbahasa Inggris. Tangani error berdasarkan code, bukan teks message.

HTTP	Kode	Arti
401	`unauthorized`	API key tidak ada, tidak valid, kedaluwarsa, atau dicabut
403	`forbidden`	API key tidak memiliki izin akses yang diperlukan atau IP tidak ada dalam daftar yang diizinkan
404	`not_found`	Kotak surat atau pesan tidak ada atau bukan milik workspace API key
409	`mailbox_unavailable`	Kotak surat perlu dihubungkan ulang, sedang dijeda, atau hanya menggunakan IMAP (belum didukung)
422	`validation_error`	Format data permintaan salah
429	`rate_limited`	Melebihi 300 permintaan per menit untuk API key ini — tunggu sesuai header Retry-After
503	`upstream_error`	Microsoft mengalami gangguan atau membatasi laju permintaan — coba lagi nanti
500	`internal_error`	Error sistem

Batas dan paginasi

Setiap API key mendapat 300 permintaan per menit. Jika terlampaui, respons 429 dikembalikan dengan header Retry-After.

Daftar mengembalikan next_cursor; kirim kembali nilainya sebagai parameter cursor untuk mendapatkan halaman berikutnya. Jika tidak ada lagi data, next_cursor bernilai null.

Parameter limit menentukan jumlah item per halaman.

cURL

curl "https://mailera.app/api/public/v1/mailboxes?limit=50&cursor=NEXT_CURSOR" \  -H "X-API-Key: mh_live_..."

Kotak surat

Tambahkan, periksa, sinkronkan, jeda, dan hapus kotak surat.

GET/mailboxes
Daftar kotak surat
Izin akses:
read
Kueri:
status, q, cursor, limit
POST/mailboxes/import
Impor kotak surat secara massal (email:password:refresh_token:client_id, atau dipisahkan dengan |)
Izin akses:
import
Isi permintaan:
lines, text, group_id, duplicate_mode
GET/mailboxes/import
Progres impor dan hasil per baris
Izin akses:
import
Kueri:
job_id
GET/mailboxes/{id}
Detail kotak surat dan jumlah pesan per folder
Izin akses:
read
PATCH/mailboxes/{id}
Jeda atau lanjutkan kotak surat
Izin akses:
manage
Isi permintaan:
action (wajib)
DELETE/mailboxes/{id}
Hapus kotak surat
Izin akses:
manage
GET/mailboxes/{id}/status
Periksa langsung dengan Microsoft apakah kotak surat masih berfungsi
Izin akses:
read
POST/mailboxes/{id}/sync
Sinkronkan sekarang
Izin akses:
sync
Isi permintaan:
wait

Impor kotak surat dan periksa progres

curl -X POST https://mailera.app/api/public/v1/mailboxes/import \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"lines":["user@hotmail.com:pass:M.C5_refresh...:9e5f94bc-..."]}'# → { "data": { "job_id": "..." } }curl "https://mailera.app/api/public/v1/mailboxes/import?job_id=JOB_ID" -H "X-API-Key: mh_live_xxx"

Pesan

Baca, cari, ambil kode OTP, dan kirim email.

GET/mailboxes/{id}/messages
Daftar pesan dalam folder
Izin akses:
read
Kueri:
folder, unread, cursor, limit
GET/mailboxes/{id}/messages/{msgId}
Ambil satu pesan beserta isinya
Izin akses:
read
GET/mailboxes/{id}/otp
Ambil kode OTP terbaru
Izin akses:
read
Kueri:
from, subject, since_minutes
POST/mailboxes/{id}/send
Kirim, balas, atau teruskan
Izin akses:
send
Isi permintaan:
to, cc, bcc, subject, html, text, importance, reply_to_message_id, mode, attachments
GET/messages/search
Cari email di semua kotak surat
Izin akses:
read
Kueri:
q, folder, limit

Kirim email

curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/send \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"to":["customer@example.com"],"subject":"Hello","text":"Message body"}'

Email Sampah

Periksa lokasi email di Kotak Masuk/Email Sampah dan pindahkan email dari Email Sampah.

POST/mailboxes/{id}/messages/{msgId}/move
Pindahkan pesan (misalnya dari Email Sampah ke Kotak Masuk)
Izin akses:
move
Isi permintaan:
destination (wajib)
POST/mailboxes/{id}/unspam
Pindahkan semua email, atau email dari satu pengirim, dari Email Sampah
Izin akses:
move
Isi permintaan:
filter
GET/mailboxes/{id}/placement
Apakah email masuk ke Kotak Masuk atau Email Sampah
Izin akses:
read
Kueri:
from, subject, since_minutes

Kotak Masuk atau Email Sampah? Lalu pindahkan dari Email Sampah

curl "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/placement?from=me@example.com" -H "X-API-Key: mh_live_xxx"curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/unspam -H "X-API-Key: mh_live_xxx" \  -H "content-type: application/json" -d '{"filter":{"type":"sender","value":"me@example.com"}}'

Webhook

Daftarkan URL untuk menerima peristiwa.

Untuk setiap peristiwa, Mailera mengirim POST JSON ke URL Anda. Jika endpoint mengembalikan error atau tidak merespons, Mailera mencoba lagi dengan jeda yang makin lama.

Peristiwa	Kapan
`message.received`	Email baru tiba di Kotak Masuk
`message.junk`	Email baru masuk ke Email Sampah
`mailbox.disconnected`	Koneksi kotak surat terputus (token dicabut, kata sandi diubah…)

Untuk memverifikasi, hitung HMAC-SHA256 dari gabungan timestamp, titik, dan body menggunakan kunci rahasia webhook, lalu bandingkan dengan header tanda tangan.

Header yang dikirim: X-MailHub-Event X-MailHub-Delivery X-MailHub-Timestamp X-MailHub-Signature

GET/webhooks
Daftar webhook
Izin akses:
webhooks
POST/webhooks
Buat webhook (kunci rahasia penandatanganan hanya dikembalikan sekali)
Izin akses:
webhooks
Isi permintaan:
url (wajib), events, group_id
PATCH/webhooks/{id}
Aktifkan/nonaktifkan webhook atau ubah peristiwa atau URL-nya
Izin akses:
webhooks
DELETE/webhooks/{id}
Hapus webhook
Izin akses:
webhooks

Verifikasi tanda tangan webhook (Node.js)

import crypto from "node:crypto";// X-MailHub-Signature: sha256=<hex>   X-MailHub-Timestamp: <unix seconds>const expected = "sha256=" + crypto.createHmac("sha256", SECRET)  .update(timestamp + "." + rawBody).digest("hex");const ok = expected.length === signature.length &&  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

Contoh

Ganti MAILBOX_ID dan API key dengan nilai milik Anda.

Impor kotak surat dan periksa progres

curl -X POST https://mailera.app/api/public/v1/mailboxes/import \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"lines":["user@hotmail.com:pass:M.C5_refresh...:9e5f94bc-..."]}'# → { "data": { "job_id": "..." } }curl "https://mailera.app/api/public/v1/mailboxes/import?job_id=JOB_ID" -H "X-API-Key: mh_live_xxx"

Periksa apakah kotak surat masih aktif

curl https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/status -H "X-API-Key: mh_live_xxx"

Ambil kode OTP terbaru (15 menit terakhir)

curl "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/otp?from=noreply@service.com&since_minutes=15" \  -H "X-API-Key: mh_live_xxx"# → { "data": { "code": "482913", "folder": "inbox", ... } }  or  { "data": { "code": null } }

Kirim email

curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/send \  -H "X-API-Key: mh_live_xxx" -H "content-type: application/json" \  -d '{"to":["customer@example.com"],"subject":"Hello","text":"Message body"}'

Kotak Masuk atau Email Sampah? Lalu pindahkan dari Email Sampah

curl "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/placement?from=me@example.com" -H "X-API-Key: mh_live_xxx"curl -X POST https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/unspam -H "X-API-Key: mh_live_xxx" \  -H "content-type: application/json" -d '{"filter":{"type":"sender","value":"me@example.com"}}'

JavaScript (sisi server)

const res = await fetch("https://mailera.app/api/public/v1/mailboxes?limit=50", {  headers: { "X-API-Key": process.env.MAILERA_API_KEY },});const { data, next_cursor } = await res.json();

Python

import os, requestsr = requests.get(    "https://mailera.app/api/public/v1/mailboxes/MAILBOX_ID/messages",    params={"folder": "inbox", "limit": 20},    headers={"X-API-Key": os.environ["MAILERA_API_KEY"]},)print(r.json()["data"])

Verifikasi tanda tangan webhook (Node.js)

import crypto from "node:crypto";// X-MailHub-Signature: sha256=<hex>   X-MailHub-Timestamp: <unix seconds>const expected = "sha256=" + crypto.createHmac("sha256", SECRET)  .update(timestamp + "." + rawBody).digest("hex");const ok = expected.length === signature.length &&  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

OpenAPI 3.1 — openapi.json Panduan untuk agen AI — llms.txt