Gmail API 怎麼申請？Google Cloud 建立 OAuth 2.0 用戶端的步驟教學

網站的聯絡表單、訂單通知要寄信，有些人會選擇用 Gmail 來寄。要讓網站程式「代替你的 Gmail 帳號寄信」，比較安全的做法是使用 Gmail API 搭配 OAuth 2.0 授權：網站不需要知道你的 Gmail 密碼，而是由你登入 Google、同意授權，網站拿到一組權杖（token）來寄信。

這篇整理在 Google Cloud Console 申請的一般流程。Google 的後台介面偶爾會改版，選單名稱可能跟文中不完全一樣，但步驟的大方向是相同的。

先想清楚：你真的需要 Gmail API 嗎？

Gmail API 設定步驟多，還要自己寫程式處理授權。如果只是要讓網站寄出表單通知，下面這些做法通常更簡單：

• 使用網域信箱的 SMTP：用公司網域的信箱寄信，寄件人看起來也比較正式。設定方式可以參考用 Gmail 收發公司企業信箱。
• WordPress 網站：安裝 WP Mail SMTP 這類寄信外掛，外掛裡通常有 Google／Gmail 的寄信方式，設定頁會告訴你要在 Google Cloud 填入哪些資料，不用自己寫程式（但下面 Google Cloud 端的步驟還是要做）。
• Gmail 的 SMTP 加上應用程式密碼：Google 已經不允許用 Gmail 的帳號密碼直接登入 SMTP 寄信，要先開啟兩步驟驗證，再建立「應用程式密碼」來使用。
• 專門的寄信服務：寄送量比較大、或需要追蹤寄送狀況時，可以考慮交易型郵件服務。

另外要注意，Gmail 帳號每天可以寄出的信件數量有上限，不適合用來寄電子報或大量通知。

確定要自己串接 Gmail API，再往下做。

步驟一：建立 Google Cloud 專案

1. 用要寄信的 Google 帳號登入 Google Cloud Console。
2. 點畫面上方的專案選擇器，選「新增專案」。
3. 輸入專案名稱（例如「網站寄信」），建立後確認上方已經切換到這個專案。

步驟二：啟用 Gmail API

1. 從左側選單進入「API 和服務」→「程式庫」，或直接用上方的搜尋框。
2. 搜尋「Gmail API」，點進去按「啟用」。

步驟三：設定 OAuth 同意畫面

同意畫面就是使用者授權時，Google 顯示「某某應用程式想要存取你的 Google 帳戶」的那個頁面。Google 近年把這部分的設定整理到「Google Auth Platform」底下，找不到「OAuth 同意畫面」的話，可以找這個名稱。

需要設定的內容：

• 應用程式名稱、使用者支援電子郵件、開發人員聯絡資訊：照實填寫。
• 使用者類型（目標對象）：
• • 「內部」：只有同一個 Google Workspace 組織裡的帳號能授權，不需要 Google 審查。只有使用 Google Workspace 的公司可以選。
  • 「外部」：任何 Google 帳號都能授權。一般的 Gmail 帳號只能選這個。
• 測試使用者：「外部」類型在「測試」狀態時，只有列在測試使用者名單裡的帳號能授權，記得把要寄信的 Gmail 帳號加進去。

權限範圍（scope）只選需要的

Gmail API 的權限分很多種。只要寄信的話，權限用 https://www.googleapis.com/auth/gmail.send 就夠了，它只能寄信，不能讀取信箱的內容。

讀取、修改信件的權限屬於 Google 管制比較嚴格的類別，公開給外部使用者使用的應用程式，需要通過 Google 的審查。自己網站寄信用的話，不要要求用不到的權限。

步驟四：建立 OAuth 用戶端 ID

1. 進入「API 和服務」→「憑證」（新版介面也可以在 Google Auth Platform 的用戶端頁面建立）。
2. 選「建立憑證」→「OAuth 用戶端 ID」。
3. 應用程式類型選「網頁應用程式」。
4. 在「已授權的重新導向 URI」填入你網站接收授權結果的網址，例如 https://www.example.com/oauth/google-callback.php。
5. 建立完成後，會得到用戶端 ID 和用戶端密鑰，可以下載成 JSON 檔。建立當下就把它下載、保存好。

用戶端密鑰要保管好

• JSON 檔和用戶端密鑰不要放在網站公開的資料夾裡，也不要上傳到 GitHub 等公開的地方。
• 放在網站根目錄以外的位置，再由程式用路徑讀取。
• 不小心外流的話，到 Google Cloud 刪除這個用戶端，重新建立一組，並更新網站上的設定。

步驟五：在網站程式裡完成授權

Google Cloud 的設定完成後，網站程式要做的事情是：

1. 把使用者（也就是你自己）導向 Google 的授權頁面，登入並按「允許」。
2. Google 把授權碼送回剛剛設定的重新導向網址。
3. 網站用授權碼換到存取權杖（access token）與更新權杖（refresh token）。
4. 寄信時用存取權杖呼叫 Gmail API。存取權杖大約一小時就會過期，過期時再用更新權杖換一組新的。

實作上建議使用 Google 官方提供的程式庫，不要自己拼湊授權流程。例如 PHP 可以用 Composer 安裝官方的用戶端程式庫：

composer require google/apiclient

幾個容易漏掉的地方：

• 要拿到更新權杖，授權網址要帶 access_type=offline（PHP 程式庫是 setAccessType('offline')）。
• 更新權杖通常只在第一次授權時給。之後想重新取得，要在授權網址加上 prompt=consent，或到 Google 帳戶的安全性設定裡移除這個應用程式的存取權，再重新授權。
• 更新權杖要存在安全的地方（資料庫，或網站目錄以外的檔案），它等於寄信的鑰匙。

用 Gmail API 寄信時，信件內容要先組成標準的郵件格式（寄件人、收件人、主旨、內文），再用 Base64URL 編碼後送出。各種程式語言的寫法，可以參考 Google 官方的 Gmail API 文件。

發布狀態：測試中與正式版

設定完成後，「外部」類型的應用程式預設是「測試」狀態：

• 只有測試使用者能授權。
• 測試狀態下取得的更新權杖，7 天後就會失效，網站會突然寄不出信。

所以長期使用時，要把發布狀態改成正式版（發布應用程式）。使用 Gmail 相關權限的應用程式，Google 可能會要求驗證；還沒通過驗證時，授權畫面會出現「Google 尚未驗證這個應用程式」的警告，自己的帳號可以按「進階」繼續。實際的審查要求，請以 Google 當下的規定為準。

「內部」類型（Google Workspace）的應用程式沒有這個 7 天的限制。

常見錯誤

出現 redirect_uri_mismatch

程式送出的重新導向網址，跟 Google Cloud 裡設定的不一致。兩邊必須完全一樣：http 或 https、有沒有 www、結尾有沒有斜線，都要相同。

出現 access_denied，無法授權

「外部」類型的測試狀態下，授權的帳號不在測試使用者名單裡。到同意畫面的設定把帳號加進去。

出現 invalid_grant

更新權杖失效了，常見的原因：

• 測試狀態下已經超過 7 天。
• 在 Google 帳戶裡移除了這個應用程式的存取權。
• 變更了 Google 帳號的密碼（含有 Gmail 權限的更新權杖會因此失效）。
• 更新權杖超過 6 個月沒有使用。

處理方式是重新走一次授權流程，取得新的更新權杖。

延伸閱讀

• 用 Gmail 收發公司企業信箱：寄件（SMTP）設定與 Gmail 停用 POP 後的收信方式
• WordPress 留言審核通過自動寄信通知留言者（含回覆通知程式碼）
• .htaccess 用法大全：轉址、HTTPS、安全防護、壓縮與快取常用設定（WordPress 適用）

網站表單寄不出信、通知信跑進垃圾信匣，是很多網站都遇過的困擾。正威網路行銷是 25 年經驗的基隆網頁設計工作室，也提供網站維護託管，網站寄信的問題歡迎來聊聊。