為 AI Agent 連接 Gmail

驗證方式

• OAuth 2.0

開啟本機控制台，選擇服務並設定憑證。OAuth 服務需要你在對應平台上註冊自己的 OAuth 應用。

此連接器需要重點檢查什麼

此 get_profile 範例讀取信箱身分和統計資訊，不讀取郵件內文。檢查 emailAddress 是否為目標信箱；messagesTotal 和 threadsTotal 為計數，historyId 為游標。執行前確認已授予所需 Gmail 讀取 scope。

呼叫前檢查 Action

範例用途

讀取已連接的 Gmail 信箱資料與統計。

Action 所需權限範圍

• https://www.googleapis.com/auth/gmail.readonly

從執行中的實例讀取 Schema，在執行前確認必填參數、權限和帳號連線。

curl -s http://localhost:3000/v1/actions/gmail.get_profile

連接帳號後，依自己的資源調整範例參數。如果 runtime 已啟用驗證，還需加入 runtime Bearer Token。

curl -s -X POST \
  http://localhost:3000/v1/actions/gmail.get_profile \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

理解呼叫結果

HTTP 執行環境回應包含 success、message、data 和 meta。請檢查 success 及 Action 輸出 Schema，不要只看 HTTP 狀態碼。執行中繼資料包含 executionId 時，可用來定位已遮蔽敏感資訊的執行記錄。下方僅展示回應結構，並非真實 API 呼叫結果。

{
  "success": true,
  "message": "OK",
  "data": {
    "emailAddress": "reader@example.com",
    "messagesTotal": 12,
    "threadsTotal": 8,
    "historyId": "12345"
  },
  "meta": {}
}

呼叫失敗時如何排查

• 驗證失敗時，先核對端點和憑證類型：管理端憑證用於 /api，執行環境 Bearer 權杖用於 /v1 和 /mcp。服務提供者的 API Key 不能取代執行環境權杖。
• 權限遭拒時，檢查 Action 所需 scopes、執行環境 Action 規則和連線授權。權杖有效也不代表有權使用所選帳號。
• 結果為空或資源缺失時，檢查連線帳號及其對目標資源的存取權限。完成授權不代表能存取所有工作區、頻道或文件。
• 重試前先檢查錯誤與執行記錄。對於會修改服務資料的 Action，先確認操作是否已完成，不要盲目重複請求。

下一步

對於支援的服務，OOMOL 負責 OAuth 應用設定與託管執行環境。帳戶選擇與權限授權仍由你完成。