Mailera API

概要

すべてのエンドポイントは共通のベース URL 配下にあり、JSON を送受信します。

1. 1アカウントと専用のワークスペースを無料で作成します。
2. 2設定 → API key を開き、キーを作成してスコープを選択します。
3. 3すべてのリクエストで X-API-Key ヘッダーにキーを指定します。

成功時のレスポンスには data フィールドが含まれます。エラー時には code と message を含む error フィールドが返されます。

認証

X-API-Key ヘッダーに API key を指定します。キーは mh_live_ で始まり、作成時に一度だけ表示されます。紛失した場合は、新しいキーを作成して古いキーを失効させてください。

同じキーを Bearer token として指定した Authorization ヘッダーも使用できます。

キーは IP 許可リストで制限できます。リスト外の IP からの呼び出しには 403 が返されます。

制限とページネーション

キーごとに毎分 300 件までリクエストできます。超過すると、Retry-After ヘッダー付きの 429 が返されます。

一覧には next_cursor が返されます。その値を cursor パラメーターに指定すると、次のページを取得できます。データがなくなると next_cursor は null になります。

limit パラメーターで 1 ページあたりの件数を指定します。

メールボックス

メールボックスの追加、確認、同期、一時停止、削除を行います。

• GET/mailboxes

  メールボックス一覧を取得

  スコープ:

  read

  クエリ:

  status, q, cursor, limit

• POST/mailboxes/import

  メールボックスを一括インポート（email:password:refresh_token:client_id、または | 区切り）

  スコープ:

  import

  ボディ:

  lines, text, group_id, duplicate_mode

• GET/mailboxes/import

  インポートの進捗と行ごとの結果を取得

  スコープ:

  import

  クエリ:

  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

メール

メールの閲覧、検索、OTP コードの取得、メールの送信を行います。

• GET/mailboxes/{id}/messages

  フォルダー内のメール一覧を取得

  スコープ:

  read

  クエリ:

  folder, unread, cursor, limit

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

  メール 1 件を本文とともに取得

  スコープ:

  read

• GET/mailboxes/{id}/otp

  最新の OTP コードを取得

  スコープ:

  read

  クエリ:

  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

  クエリ:

  q, folder, limit

迷惑メール

受信トレイ／迷惑メールへの振り分け結果を確認し、迷惑メールから移動します。

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

  メールを移動（例：迷惑メールから受信トレイへ）

  スコープ:

  move

  ボディ:

  destination (必須)

• POST/mailboxes/{id}/unspam

  すべてのメール、または特定の送信者のメールを迷惑メールから移動

  スコープ:

  move

  ボディ:

  filter

• GET/mailboxes/{id}/placement

  受信トレイと迷惑メールのどちらに届いたかを確認

  スコープ:

  read

  クエリ:

  from, subject, since_minutes

webhook

イベントを受信する URL を登録します。

イベントごとに、Mailera は指定の URL に JSON を POST します。エンドポイントがエラーを返すか応答しない場合、待機時間を徐々に延ばしながら再送します。

検証するには、タイムスタンプ、ドット、ボディを連結した文字列の HMAC-SHA256 を 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