Mailera API

Giới thiệu

Mọi endpoint nằm dưới một địa chỉ gốc, nhận và trả về JSON.

1. 1Tạo tài khoản và workspace riêng (miễn phí).
2. 2Vào Cài đặt → API key, tạo key và chọn quyền.
3. 3Gửi key qua header X-API-Key trong mọi lượt gọi.

Thành công trả về trường data; lỗi trả về trường error gồm code và message.

Xác thực

Gửi API key trong header X-API-Key. Key bắt đầu bằng mh_live_ và chỉ hiện một lần khi tạo; nếu làm mất, hãy tạo key mới và thu hồi key cũ.

Header Authorization dạng Bearer với cùng key cũng được chấp nhận.

Key có thể giới hạn theo danh sách IP; gọi từ IP khác sẽ nhận lỗi 403.

Giới hạn và phân trang

Mỗi key được 300 lượt mỗi phút. Vượt giới hạn trả về 429 kèm header Retry-After.

Danh sách trả về next_cursor; gửi lại giá trị đó qua tham số cursor để lấy trang tiếp theo. Khi hết dữ liệu, next_cursor là null.

Tham số limit đặt số dòng mỗi trang.

Hộp thư

Thêm, kiểm tra, đồng bộ, tạm dừng và xoá hộp thư.

• GET/mailboxes

  Danh sách hộp thư

  Quyền:

  read

  Query:

  status, q, cursor, limit

• POST/mailboxes/import

  Nhập hộp thư hàng loạt (email:password:refresh_token:client_id, hoặc dấu |)

  Quyền:

  import

  Body:

  lines, text, group_id, duplicate_mode

• GET/mailboxes/import

  Tiến độ lần nhập và kết quả từng dòng

  Quyền:

  import

  Query:

  job_id

• GET/mailboxes/{id}

  Chi tiết hộp thư và bộ đếm thư mục

  Quyền:

  read

• PATCH/mailboxes/{id}

  Tạm dừng hoặc bật lại hộp thư

  Quyền:

  manage

  Body:

  action (bắt buộc)

• DELETE/mailboxes/{id}

  Xoá hộp thư

  Quyền:

  manage

• GET/mailboxes/{id}/status

  Kiểm tra trực tiếp với Microsoft xem hộp thư còn hoạt động

  Quyền:

  read

• POST/mailboxes/{id}/sync

  Đồng bộ ngay

  Quyền:

  sync

  Body:

  wait

Thư

Đọc, tìm kiếm, lấy OTP và gửi thư.

• GET/mailboxes/{id}/messages

  Danh sách thư theo thư mục

  Quyền:

  read

  Query:

  folder, unread, cursor, limit

• GET/mailboxes/{id}/messages/{msgId}

  Nội dung một thư

  Quyền:

  read

• GET/mailboxes/{id}/otp

  Lấy mã OTP mới nhất

  Quyền:

  read

  Query:

  from, subject, since_minutes

• POST/mailboxes/{id}/send

  Gửi, trả lời hoặc chuyển tiếp thư

  Quyền:

  send

  Body:

  to, cc, bcc, subject, html, text, importance, reply_to_message_id, mode, attachments

• GET/messages/search

  Tìm thư trên mọi hộp thư

  Quyền:

  read

  Query:

  q, folder, limit

Spam

Kiểm tra vị trí Inbox/Spam và kéo thư khỏi Spam.

• POST/mailboxes/{id}/messages/{msgId}/move

  Chuyển thư (ví dụ từ Spam về Inbox)

  Quyền:

  move

  Body:

  destination (bắt buộc)

• POST/mailboxes/{id}/unspam

  Kéo toàn bộ hoặc theo người gửi khỏi Spam

  Quyền:

  move

  Body:

  filter

• GET/mailboxes/{id}/placement

  Thư vào Inbox hay Spam

  Quyền:

  read

  Query:

  from, subject, since_minutes

Webhook

Đăng ký URL nhận sự kiện.

Với mỗi sự kiện, Mailera gửi POST JSON tới URL của bạn. Nếu endpoint trả lỗi hoặc không phản hồi, Mailera tự gửi lại với khoảng chờ tăng dần.

Để xác minh, tính HMAC-SHA256 của chuỗi timestamp, dấu chấm và body bằng secret của webhook, rồi so sánh với header chữ ký.

Header đi kèm: X-MailHub-Event X-MailHub-Delivery X-MailHub-Timestamp X-MailHub-Signature

• GET/webhooks

  Danh sách webhook

  Quyền:

  webhooks

• POST/webhooks

  Tạo webhook (secret ký chỉ trả về một lần)

  Quyền:

  webhooks

  Body:

  url (bắt buộc), events, group_id

• PATCH/webhooks/{id}

  Bật/tắt, đổi sự kiện hoặc URL của webhook

  Quyền:

  webhooks

• DELETE/webhooks/{id}

  Xoá webhook

  Quyền:

  webhooks