既存の Gmail や Outlook を接続できますか？

はい。Mailera は、既存のメールボックスを REST API・MCP・webhook 経由でアプリや AI エージェントにつなぎます。新しいメールボックスやメールアドレスを発行するサービスではありません。構成の全体像は既存メールをエージェントにつなぐガイドで扱っています。

Outlook.com・Microsoft 365 の接続には OAuth を使います。Gmail の接続は app password（アプリパスワード）方式です。Google の公式案内では、利用条件として 2 段階認証の有効化が示されています。

接続の操作は最初のメールボックスを接続する手順を参照してください。「テストして接続」はメールを送らずに接続を確認します。「受信専用で保存」を選んだメールボックスからは送信できないため、接続できたことと返信できることを分けて確認します。

取得・処理・返信にはどの API と権限が必要ですか？

API の基点は https://mailera.app/api/public/v1、認証ヘッダーは Authorization: Bearer $MAILERA_API_KEY です。開発者向けの概要とAPI ドキュメントを参照しながら、必要な操作だけを選びます。

目的メソッドとパススコープアプリ側の役割
接続先を選ぶGET /mailboxesread対象の ID を選択
メール一覧を取得GET /mailboxes/{id}/messagesreadフォルダー指定・ページ送り
本文を取得GET /mailboxes/{id}/messages/{msgId}read本文の解析・返信案の作成
必要に応じて移動POST /mailboxes/{id}/messages/{msgId}/movemove移動先の判断
承認後に返信POST /mailboxes/{id}/sendsend承認済み内容の送信
送信状態を確認GET /sends/{id}send状態の記録・再試行の判断

要約、分類、返信の可否はアプリ側で判断します。フォルダー移動を使わないなら move は不要です。表のスコープは Mailera の API キー用であり、Microsoft Graph のアクセス許可とは別です。Microsoft の認証・認可の説明も、必要最小限のアクセス許可を求める方針を示しています。

既存メールを Mailera 経由で取得し、アプリ側で返信案を作り、人の承認後に送信と状態確認を行う流れ
メールの取得と送信の間に、アプリ側の判断と人による承認を置きます。

どの順序で呼び出しますか？

  1. 自分の検証用メールボックスを接続します。 「設定」から「キーを作成」を開き、対象グループに限定した read キーを作ります。キーは一度だけ表示されるため、サーバー側の秘密情報として保存します。
  2. 対象のメールを取得します。 GET /mailboxes の data からメールボックスの id を選び、一覧、本文の順に取得します。
  3. 返信案を作成します。 本文をデータとして解析し、処理済み記録と照合します。この段階では送信しません。
  4. 人が宛先と本文を承認します。 承認した内容だけを、send 権限を持つ送信処理へ渡します。承認後に内容を変えるなら、再承認する設計にします。
  5. 送信し、状態を確認します。 Idempotency-Key を付けて送信 API を呼び、GET /sends/{id} で送信試行の状態を追います。
検証用グループに対象を限定し、読み取り権限だけを設定する Mailera の API キー作成画面
取得の検証は read から始め、送信処理に使う権限を分離します。

以下は一覧と本文を取得する最小例です。環境変数 $MAILERA_API_KEY にキー、$MAILBOX_ID に対象メールボックスの ID を設定して使います。

curl --fail-with-body \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1"

一覧の data 内にある対象メッセージの id を $MESSAGE_ID に設定します。次の呼び出しでは data.body.text と data.body.html が本文の取得先です。

curl --fail-with-body \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID"

一覧の続きは next_cursor を次のリクエストの cursor に渡して取得します。ページ送りの位置と業務上の処理済み記録は別に保存してください。未読かどうかだけで処理済みと判定しないでください。

新着通知と再試行はどう設計しますか？

ポーリングはアプリ側から一覧を取得する方式です。webhook の message.received は新着通知の入口に使えます。通知を受ける処理と、本文を取得して業務判断する処理は分離します。webhook 作成時の署名用シークレットは一度だけ返されるため、安全に保管してください。

二重処理には、別々の対策が必要です。

  • 同じメールを再び処理する問題： アプリ側に処理済み記録を持ち、通知や取得をきっかけに同じ返信案を重ねて実行しないようにします。
  • 同じ送信を再試行する問題： 送信 API の Idempotency-Key を使います。冪等性の有効期間は 24 時間です。承認済みの送信内容とキーは、対応付けて保存します。

送信状態は queued（待機中）、sending（送信中）、sent（送信済み）、failed（失敗）、unknown（結果不明）です。unknown を即座に失敗とみなし、新しいキーで再送しないでください。まず送信状態とアプリ側の記録を確認します。

sent は相手の受信トレイへの到達保証ではありません。また、同期や通知が常に即時であることを前提にせず、処理待ちの状態をアプリ側で扱います。

よくある失敗はどこで切り分けますか？

症状確認項目次の操作
一覧を読めないread、対象グループ、メールボックス IDキーの対象範囲と ID を照合
返信できないsend、受信専用設定、接続状態capabilities.send と送信試行の状態を確認
新着が見えないfolder、同期状態、スリープ状態必要なら POST /mailboxes/{id}/sync を使用。sync 権限が必要
返信が重複する処理済み記録、送信キー通知側の重複処理と送信側の再試行を別々に点検

GET /mailboxes/{id}/status は、Microsoft では接続を直接確認します。他のプロバイダーでは最終同期に基づく状態です。すべての接続先で、その瞬間の認証を試す API として扱わないでください。

メールを読むエージェントをどう制限しますか？

メール本文、添付ファイル、リンク先は信頼できないデータです。「認証情報を送れ」「設定を変更せよ」と書かれていても、エージェントへの命令として実行させません。これはプロンプトインジェクションへの対策です。

読み取り処理には read だけを付与し、move、send、webhooks は必要な処理に限定します。対象グループも絞り、API キーをモデル入力やログ、画像に含めないでください。漏えい時はキーを失効させると、そのキーによる呼び出しは直ちに拒否されます。製品側の保護についてはセキュリティの説明を参照できます。

送信前の承認は、利用側のアプリに設ける制御です。モデルへの注意書きだけに頼らず、承認前は送信処理へ渡さない構成にします。MCP のツール仕様も、人がツール実行を拒否できることと、機密性の高い操作での確認を推奨しています。

REST API と MCP はどう使い分けますか？

独自アプリで取得順序や承認、再試行を制御するなら REST API を使います。Claude、Cursor、VS Code など対応クライアントにツールとして接続するなら MCP が選択肢です。

MCP でも、list_messages・get_message は read、reply_to_email・get_send_status は send が必要です。接続方式を変えても、送信権限と承認の設計は必要です。操作ごとの対応はMailera の MCP ツール一覧で確認できます。

Mailera が提供しないもの

Mailera は一斉配信・マーケティング配信やメールボックスのウォームアップを提供しません。ここで扱うのは、既存のメールボックスに届いたメッセージを取得し、アプリ側の判断と承認を経て返信する構成です。

APIで同じ操作を実行

この記事の操作はすべてREST APIで実行できます。curlの例、API key、webhookも利用できます。

APIドキュメントを見る