既存トークンを使うか、OAuth で接続するか
Mailera は Outlook.com、Hotmail、Microsoft 365 を Microsoft Graph 経由で接続します。既存トークンを使う必要がなければ、「Microsoftでサインイン」を選んでください。Microsoft の同意画面で接続でき、秘密情報を手作業で受け渡す機会を減らせます。
リフレッシュトークン（更新トークン）は、アクセストークンの期限が切れたときに、新しいトークンを取得するための資格情報です。Microsoft の更新トークンの説明では、ユーザーとクライアントの組み合わせにひもづくとされています。別のアプリの client_id に置き換えて使うものではありません。
Mailera の製品概要にあるとおり、接続するのは既存のメールボックスです。新しいメールボックスやアドレスは作成しません。接続方法は Microsoft メールボックスの接続案内でも確認できます。
取り込む前の確認事項
| 確認項目 | 確認する内容 |
|---|---|
| 管理権限 | 自分が管理し、接続を許可されたメールボックスか |
| 取得経路 | どのユーザー・アプリで発行したトークンか |
client_id | 発行先アプリの Application (client) ID と一致するか |
| アカウント種別 | 個人用か、組織の Microsoft 365 か |
| Microsoft 側の同意 | アプリに必要な Graph 権限が付与されているか |
| Mailera の役割 | 画面から追加できる Admin または Leader か |
client_id はアプリ登録で割り当てられる識別子です。定義は Microsoft の認可コードフローを参照してください。
Mailera API キーの import は、Mailera への取り込みを許可する権限です。Microsoft Graph のメールアクセス権限を付与するものではありません。Graph の権限リファレンスに従い、Microsoft 側ではユーザーまたは管理者の同意が必要です。取り込みで同意手続きを省略することはできません。
組織のメールボックスを接続する場合は、Microsoft 365 の Graph 設定チェックリストで組織側の設定も確認してください。
取り込み行の入力形式
形式は email:password:refresh_token:client_id で、1 行に 1 メールボックスを記載します。
| 欄 | 内容・扱い |
|---|---|
email | 接続対象のメールアドレス |
password | 形式上の第 2 欄。欄名だけを根拠に通常のサインインパスワードを入力しないでください |
refresh_token | 対象ユーザーとクライアントに発行された更新トークン。秘密情報として扱います |
client_id | トークンの発行先アプリの識別子 |
並びだけを示す例は mailbox@example.com:[伏せ字]:[更新トークンの伏せ字]:[クライアント ID の伏せ字] です。この例をそのまま取り込まないでください。
password 欄の入力内容に迷う場合は、通常のパスワードを試すのではなく「Microsoftでサインイン」で接続してください。Microsoft メールボックスの接続にアプリパスワードは使いません。
区切り文字はコロン、縦棒、セミコロン、タブに対応します。.txt ファイルのアップロードもできますが、トークンを共有フォルダーや一時ファイルに残さないでください。画面共有を止め、クリップボード履歴やデバッグログにも注意します。
画面から取り込む手順
- 「メールボックス」から「メールボックスを追加」を開き、「一括貼り付け」を選びます。
- まず自分のテスト用メールボックス 1 件を入力し、取り込み先グループを選びます。
- 同じアドレスが存在する場合の処理を、スキップまたは上書きから選びます。既存設定を変更したくない場合は、スキップを選んでください。
- 「インポートを開始」を押し、進捗画面で成功・エラー・スキップの結果を確認します。エラーを CSV 出力する場合は、共有前に秘密情報が含まれていないか確認してください。
- 「メールボックス」に戻り、対象アドレスを確認します。Microsoft へのサインイン確認には
GET /mailboxes/{id}/statusを使い、最終同期はGET /mailboxes/{id}のdata.last_sync_atで確認します。続けて、自分のテストメールを開き、本文まで読めるか確認します。
取り込み結果、Microsoft への認証、メール取得の順に確認してください。前の段階で成功していても、次の確認は省かないでください。
API で取り込む場合の違い
取り込みと読み取りでは必要な権限が異なります。リクエスト本文などの詳細は Mailera API ドキュメントを参照してください。
| 操作 | エンドポイント | 権限 |
|---|---|---|
| 一括取り込み | POST /mailboxes/import | import |
| 進捗・行ごとの結果 | GET /mailboxes/import に job_id を指定 | import |
| Microsoft へのサインイン確認 | GET /mailboxes/{id}/status | read |
| 最終同期の取得 | GET /mailboxes/{id} の data.last_sync_at | read |
| メール一覧 | GET /mailboxes/{id}/messages | read |
| メール本文 | GET /mailboxes/{id}/messages/{msgId} | read |
「設定」で「キーを作成」を開き、「メールボックスのスコープ」を対象グループに絞ります。取り込み用キーと、接続後の読み取り用キーは分けてください。キーは作成時に一度だけ表示されます。
次の例では、保護した実行環境に $MAILERA_API_KEY と対象の $MAILBOX_ID を設定しておきます。キーや更新トークンの値をコマンド履歴へ直接書かないでください。
curl --silent --show-error \
"https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
-H "Authorization: Bearer $MAILERA_API_KEY"data の subject、from、received_at で対象メールを確認します。取得したメッセージの id を $MESSAGE_ID に設定し、本文を取得します。
curl --silent --show-error \
"https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $MAILERA_API_KEY"data.body.text または data.body.html の内容を確認してください。自分のテストメールを選び、レスポンスをそのまま共有ログへ出さないようにします。なお、一括取り込みはメールボックスの登録機能です。Mailera は一括・マーケティング送信を提供していません。
よくあるエラーの切り分け
| 症状 | 確認先 | 次の操作 |
|---|---|---|
| 行の取り込みに失敗 | 欄の順序と区切り文字 | 1 行 1 メールボックスの形式に直します |
| スキップされた | 同じアドレスの登録と重複時の選択 | 既存メールボックスを確認し、更新が必要か判断します |
| 認証に失敗 | トークンの発行元と client_id | 発行時の組み合わせと照合します |
| 以前は接続できた | Microsoft 側の失効・再認証要求 | 対話的に再サインインします |
| 同意や追加認証が必要 | Microsoft 側の要求と組織の設定 | 必要に応じて管理者へ確認します |
| 取り込み成功後も本文を読めない | 接続状態、一覧取得、本文取得の各結果 | どの段階で失敗したかを分けます |
Microsoft 側で invalid_grant が返った場合、期限切れと即断しないでください。無効、解析不能、欠落など、認証情報を利用できない複数の状況を含みます。interaction_required はユーザーの操作が必要なことを示します。意味は Microsoft の認証・認可エラー一覧で確認できます。
更新トークンは期限前でも失効する場合があります。失効時は再サインインして新しいトークンを取得し、接続を設定し直します。同じ値を何度も貼り付けても、失効や同意の問題は解決しません。
接続後の秘密情報とエージェントを守る
一括貼り付けで渡したトークンは、保存前に暗号化され、再表示されません。ただし、入力前に端末やファイルへ残したコピーは別に管理する必要があります。運用上の確認には Mailera のセキュリティ案内も参照してください。
Microsoft では、新しいトークンの取得に使っても、古い更新トークンは自動では失効しません。新しいものを取得したら、古いコピーを安全に削除してください。
漏えい時は対象を分けて対応します。Mailera API キーを失効させると、そのキーによる呼び出しは直ちに拒否されます。一方、Microsoft の更新トークンは Microsoft 側の失効手順で対応してください。Mailera のメールボックス削除だけで対応を終えないでください。
AI エージェントにつなぐ場合、受信メールは信頼できないデータであり、命令ではありません。本文に書かれた指示で秘密情報を送信したり、外部操作を実行したりさせないでください。エージェント用キーは read など必要最小限にし、取り込み用キーを流用しません。送信を許可する場合は実行前に人の確認を挟みます。
関連記事：メールプロバイダーとエージェントの接続。
