เอกสาร

Mailera API

จัดการกล่องจดหมาย Microsoft (Outlook, Hotmail, Microsoft 365) แบบครบวงจรผ่าน REST: เพิ่มกล่องจดหมาย ตรวจสอบว่ายังใช้งานได้ อ่านอีเมล ดึงรหัส OTP ส่งอีเมล ย้ายอีเมลออกจากอีเมลขยะ และรับ webhook

บทนำ

ทุกเอนด์พอยต์อยู่ภายใต้ URL หลักเดียวกัน และรับส่งข้อมูลเป็น JSON

1สร้างบัญชีและเวิร์กสเปซของคุณเอง (ฟรี)
2เปิดการตั้งค่า → API key สร้างคีย์และเลือกขอบเขตสิทธิ์
3ส่งคีย์ในส่วนหัว X-API-Key ของทุกคำขอ

การตอบกลับที่สำเร็จจะมีฟิลด์ data ส่วนข้อผิดพลาดจะมีฟิลด์ error ซึ่งประกอบด้วย code และ message

สร้างเวิร์กสเปซฟรี

URL หลัก

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

การยืนยันตัวตน

ส่ง API key ในส่วนหัว X-API-Key คีย์ขึ้นต้นด้วย mh_live_ และจะแสดงเพียงครั้งเดียวเมื่อสร้าง หากทำหาย ให้สร้างคีย์ใหม่และเพิกถอนคีย์เดิม

สามารถใช้ส่วนหัว Authorization ที่มี Bearer token ซึ่งใช้คีย์เดียวกันได้เช่นกัน

สามารถจำกัดคีย์ให้ใช้ได้เฉพาะ IP ในรายการที่อนุญาต คำขอจาก IP อื่นจะได้รับ 403

cURL

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

ขอบเขตสิทธิ์ของคีย์

แต่ละคีย์มีขอบเขตสิทธิ์อย่างน้อยหนึ่งรายการ การเรียกเอนด์พอยต์ที่คีย์ไม่มีสิทธิ์จะได้รับ 403 forbidden

ขอบเขตสิทธิ์	อนุญาตให้
`read`	อ่านกล่องจดหมาย อีเมล รหัส OTP และตำแหน่งอีเมลในกล่องจดหมายเข้า/อีเมลขยะ
`move`	ย้ายอีเมลออกจากอีเมลขยะและย้ายระหว่างโฟลเดอร์
`import`	เพิ่มกล่องจดหมาย
`sync`	ขอซิงค์ทันที
`send`	ส่ง ตอบกลับ และส่งต่ออีเมล
`manage`	พักใช้งาน เปิดใช้งานต่อ และลบกล่องจดหมาย
`webhooks`	จัดการ webhook

ข้อผิดพลาด

ข้อผิดพลาดจะมี code ที่คงที่และ message เป็นภาษาอังกฤษเสมอ ให้จัดการข้อผิดพลาดตาม code ไม่ใช่ข้อความใน message

HTTP	รหัส	ความหมาย
401	`unauthorized`	ไม่มี API key หรือคีย์ไม่ถูกต้อง หมดอายุ หรือถูกเพิกถอน
403	`forbidden`	คีย์ไม่มีขอบเขตสิทธิ์ที่จำเป็น หรือ IP ไม่อยู่ในรายการที่อนุญาตของคีย์
404	`not_found`	ไม่พบกล่องจดหมายหรืออีเมล หรือไม่ได้อยู่ในเวิร์กสเปซของคีย์
409	`mailbox_unavailable`	กล่องจดหมายต้องเชื่อมต่อใหม่ ถูกพักใช้งาน หรือใช้ IMAP เท่านั้น (ยังไม่รองรับ)
422	`validation_error`	ข้อมูลคำขอมีรูปแบบไม่ถูกต้อง
429	`rate_limited`	คำขอของคีย์นี้เกิน 300 ครั้งต่อนาที — รอตามเวลาที่ระบุในส่วนหัว Retry-After
503	`upstream_error`	Microsoft มีข้อผิดพลาดหรือจำกัดอัตราการเรียก — ลองอีกครั้งภายหลัง
500	`internal_error`	ข้อผิดพลาดของระบบ

ขีดจำกัดและการแบ่งหน้า

แต่ละคีย์ส่งคำขอได้ 300 ครั้งต่อนาที หากเกินขีดจำกัดจะได้รับ 429 พร้อมส่วนหัว Retry-After

รายการจะส่งค่า next_cursor กลับมา ให้ส่งค่านี้ผ่านพารามิเตอร์ cursor เพื่อดึงหน้าถัดไป เมื่อไม่มีข้อมูลเหลือ next_cursor จะเป็น null

พารามิเตอร์ limit กำหนดจำนวนรายการต่อหน้า

cURL

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

กล่องจดหมาย

เพิ่ม ตรวจสอบ ซิงค์ พักใช้งาน และลบกล่องจดหมาย

GET/mailboxes
แสดงรายการกล่องจดหมาย
ขอบเขตสิทธิ์:
read
พารามิเตอร์ Query:
status, q, cursor, limit
POST/mailboxes/import
นำเข้ากล่องจดหมายจำนวนมาก (email:password:refresh_token:client_id หรือคั่นด้วย |)
ขอบเขตสิทธิ์:
import
เนื้อหาคำขอ:
lines, text, group_id, duplicate_mode
GET/mailboxes/import
ความคืบหน้าการนำเข้าและผลลัพธ์แต่ละบรรทัด
ขอบเขตสิทธิ์:
import
พารามิเตอร์ Query:
job_id
GET/mailboxes/{id}
รายละเอียดกล่องจดหมายและจำนวนอีเมลในแต่ละโฟลเดอร์
ขอบเขตสิทธิ์:
read
PATCH/mailboxes/{id}
พักใช้งานหรือเปิดใช้งานกล่องจดหมายต่อ
ขอบเขตสิทธิ์:
manage
เนื้อหาคำขอ:
action (จำเป็น)
DELETE/mailboxes/{id}
ลบกล่องจดหมาย
ขอบเขตสิทธิ์:
manage
GET/mailboxes/{id}/status
ตรวจสอบกับ Microsoft โดยตรงว่ากล่องจดหมายยังใช้งานได้หรือไม่
ขอบเขตสิทธิ์:
read
POST/mailboxes/{id}/sync
ซิงค์ทันที
ขอบเขตสิทธิ์:
sync
เนื้อหาคำขอ:
wait

นำเข้ากล่องจดหมายและตรวจสอบความคืบหน้า

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"

อีเมล

อ่าน ค้นหา ดึงรหัส OTP และส่งอีเมล

GET/mailboxes/{id}/messages
แสดงรายการอีเมลในโฟลเดอร์
ขอบเขตสิทธิ์:
read
พารามิเตอร์ Query:
folder, unread, cursor, limit
GET/mailboxes/{id}/messages/{msgId}
ดึงอีเมลหนึ่งฉบับพร้อมเนื้อหา
ขอบเขตสิทธิ์:
read
GET/mailboxes/{id}/otp
ดึงรหัส OTP ล่าสุด
ขอบเขตสิทธิ์:
read
พารามิเตอร์ Query:
from, subject, since_minutes
POST/mailboxes/{id}/send
ส่ง ตอบกลับ หรือส่งต่อ
ขอบเขตสิทธิ์:
send
เนื้อหาคำขอ:
to, cc, bcc, subject, html, text, importance, reply_to_message_id, mode, attachments
GET/messages/search
ค้นหาอีเมลในกล่องจดหมายทั้งหมด
ขอบเขตสิทธิ์:
read
พารามิเตอร์ Query:
q, folder, limit

ส่งอีเมล

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"}'

อีเมลขยะ

ตรวจสอบตำแหน่งอีเมลในกล่องจดหมายเข้า/อีเมลขยะ และย้ายอีเมลออกจากอีเมลขยะ

POST/mailboxes/{id}/messages/{msgId}/move
ย้ายอีเมล (เช่น จากอีเมลขยะไปยังกล่องจดหมายเข้า)
ขอบเขตสิทธิ์:
move
เนื้อหาคำขอ:
destination (จำเป็น)
POST/mailboxes/{id}/unspam
ย้ายอีเมลทั้งหมดหรือเฉพาะของผู้ส่งรายหนึ่งออกจากอีเมลขยะ
ขอบเขตสิทธิ์:
move
เนื้อหาคำขอ:
filter
GET/mailboxes/{id}/placement
ตรวจสอบว่าอีเมลเข้ากล่องจดหมายเข้าหรืออีเมลขยะ
ขอบเขตสิทธิ์:
read
พารามิเตอร์ Query:
from, subject, since_minutes

กล่องจดหมายเข้าหรืออีเมลขยะ? แล้วย้ายออกจากอีเมลขยะ

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

ลงทะเบียน URL สำหรับรับเหตุการณ์

ทุกครั้งที่เกิดเหตุการณ์ Mailera จะส่งคำขอ POST แบบ JSON ไปยัง URL ของคุณ หากเอนด์พอยต์ส่งข้อผิดพลาดกลับมาหรือไม่ตอบสนอง Mailera จะลองส่งใหม่โดยเพิ่มระยะเวลารอขึ้นเรื่อย ๆ

เหตุการณ์	เมื่อ
`message.received`	มีอีเมลใหม่ในกล่องจดหมายเข้า
`message.junk`	มีอีเมลใหม่ในอีเมลขยะ
`mailbox.disconnected`	กล่องจดหมายขาดการเชื่อมต่อ (token ถูกเพิกถอน เปลี่ยนรหัสผ่าน…)

ในการตรวจสอบ ให้คำนวณ HMAC-SHA256 ของ timestamp ตามด้วยจุดและ body โดยใช้คีย์ลับของ webhook แล้วเปรียบเทียบกับส่วนหัวลายเซ็น

ส่วนหัวที่ส่ง: X-MailHub-Event X-MailHub-Delivery X-MailHub-Timestamp X-MailHub-Signature

GET/webhooks
แสดงรายการ webhook
ขอบเขตสิทธิ์:
webhooks
POST/webhooks
สร้าง webhook (คีย์ลับสำหรับลงลายเซ็นจะส่งกลับเพียงครั้งเดียว)
ขอบเขตสิทธิ์:
webhooks
เนื้อหาคำขอ:
url (จำเป็น), events, group_id
PATCH/webhooks/{id}
เปิด/ปิด webhook หรือเปลี่ยนเหตุการณ์หรือ URL
ขอบเขตสิทธิ์:
webhooks
DELETE/webhooks/{id}
ลบ webhook
ขอบเขตสิทธิ์:
webhooks

ตรวจสอบลายเซ็น 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));

ตัวอย่าง

แทนที่ MAILBOX_ID และคีย์ด้วยค่าของคุณเอง

นำเข้ากล่องจดหมายและตรวจสอบความคืบหน้า

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"

ตรวจสอบว่ากล่องจดหมายยังใช้งานได้

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

ดึงรหัส OTP ล่าสุด (ในช่วง 15 นาทีที่ผ่านมา)

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 } }

ส่งอีเมล

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"}'

กล่องจดหมายเข้าหรืออีเมลขยะ? แล้วย้ายออกจากอีเมลขยะ

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 (ฝั่งเซิร์ฟเวอร์)

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"])

ตรวจสอบลายเซ็น 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 คู่มือสำหรับเอเจนต์ AI — llms.txt