最終更新日：2026年8月5日

はじめに

Google Apps Script (GAS) でGmailのデータを取得し、処理を行う場合、GmailApp もしくは Gmail API を使用する方法があります。GmailApp はGASの内部サービスであり、GCP（Google Cloud Platform）での特別な設定は不要です。一方、Gmail API を利用する場合は、GCPプロジェクトの作成とAPIの有効化が必要となります。

本記事では、Gmail APIをGASで利用する際のGCPプロジェクト設定と認証の流れについて詳しく解説します。

---

Gmail APIをGASで利用する場合のGCP設定が必要な理由

GASはGoogleのクラウド環境上で実行されるため、通常のスクリプトであればOAuthの処理はGAS側が自動で行います。しかし、Gmail APIを利用する場合は以下の理由でGCPプロジェクトの設定が必要になります。

1. Gmail APIを有効にする必要がある
   • Gmail.Users.Messages.list() などのAPIメソッドはGCPプロジェクトで有効化されたGmail APIを通じて動作します。
2. APIの認可スコープの管理
   • Gmail APIを利用する場合、https://www.googleapis.com/auth/gmail.readonly などのOAuthスコープを明示的に指定する必要があります。
3. 実行権限の管理
   • GASが特定のGmailアカウントに対して適切な権限を持っているかどうかをGoogleが認証するため、GCPプロジェクトを通じて管理する仕組みが必要となります。

---

GCPの設定手順

Gmail APIを使用するために、GCPで必要な設定を行います。

1. GCPプロジェクトの作成

1. Google Cloud Consoleにアクセス
2. 新しいプロジェクトを作成（既存のプロジェクトがある場合は流用可）
3. プロジェクト名を入力し、作成をクリック

2. Gmail APIの有効化

1. 「APIとサービス」 > 「ライブラリ」 へ移動
2. 「Gmail API」を検索し、クリック
3. 「有効にする」 ボタンを押す

3. GASの「サービス」からGmail APIを追加

1. GASのエディタを開く
2. 「サービス」 をクリック
3. 「サービスを追加」 を選択し、「Gmail API」を追加

4. （必要な場合のみ）標準GCPプロジェクトとの関連付け

GASプロジェクトには、作成時に自動で割り当てられる「デフォルトのGCPプロジェクト」が紐付いています。この場合、上記の手順3で「サービス」にGmail APIを追加するだけでAPIも自動的に有効化されるため、追加の作業は不要です。

一方、課金管理やIAM権限を既存のGCPプロジェクトにまとめたいなどの理由で「標準GCPプロジェクト」を明示的に紐付ける場合は、以下の対応が必要です。

1. GASエディタ左側の「プロジェクトの設定」（歯車アイコン）を開く
2. 「Google Cloud Platform（GCP）プロジェクト」欄で「プロジェクトを変更」をクリックし、紐付けたいプロジェクト番号を入力
3. 紐付けた標準GCPプロジェクト側でも、Google Cloud Consoleの「APIとサービス」＞「ライブラリ」からGmail APIを手動で有効化する（デフォルトプロジェクトと異なり自動では有効化されない）

なお、機密性の高いスコープ（gmail.modify など）を組織外のユーザー向けに公開する場合は、Google Cloud Consoleの「APIとサービス」＞「Google Auth Platform」（旧称：OAuth同意画面）でアプリ情報や公開ステータスの設定が別途必要になる場合があります。個人・社内利用の範囲であれば、この設定を意識する必要はほとんどありません。

---

Google Apps Script（GAS）でGmail APIを利用するコード例

以下は、Gmail APIを利用して最新のメールを取得するGASスクリプトの例です。

function listRecentEmails() {
  const messages = Gmail.Users.Messages.list('me', { maxResults: 5 });

  if (!messages.messages) {
    console.log("メールが見つかりませんでした");
    return;
  }

  messages.messages.forEach(msg => {
    const message = Gmail.Users.Messages.get('me', msg.id);
    console.log("件名: " + getHeader(message, "Subject"));
    console.log("送信者: " + getHeader(message, "From"));
    console.log("日時: " + new Date(parseInt(message.internalDate)));
    console.log("=================================");
  });
}

function getHeader(message, name) {
  const headers = message.payload.headers;
  const foundHeader = headers.find(header => header.name === name);
  return foundHeader ? foundHeader.value : "不明";
}

実行時の注意点

• 初回実行時に Gmail へのアクセス許可 を求めるダイアログが表示されるので、許可する。
• Gmail.Users.Messages.list() を使うためには、GCPの Gmail API の有効化 が必要。
• スクリプトが正しく動作しない場合は、Scopes の設定を確認し、https://www.googleapis.com/auth/gmail.readonly を追加する。

---

GmailAppとGmail APIの使い分け

「結局どちらを使えばいいのか」と迷う方向けに、GmailAppとGmail API（Advanced Gmail Service）の違いを整理します。

まずはGCP設定が不要なGmailAppで要件を満たせるか検討し、差分検知やページング処理など、GmailAppでは実現しづらい要件がある場合にGmail APIへの移行を検討するのがおすすめです。GmailApp利用時に発生しやすい制限や実装上の注意点は、後述の関連記事でも詳しく解説しています。

---

よくあるエラーと対処法

Gmail APIをGASで利用する際に発生しやすいエラーと、その対処法をまとめました。

---

認証関連の注意点

GASではクライアントシークレットは不要

GAS上で実行する場合、Googleの認証管理が自動で行われるため、OAuth 2.0のクライアントシークレットやアクセストークンの管理は不要 です。

GASのスクリプト実行時に求められる認証プロセス

1. 初回実行時にGmailへのアクセス許可を求められる
2. ユーザーが許可を与えると、そのGoogleアカウントで実行可能に
3. GCPプロジェクトの設定が正しく行われていれば、そのままAPIが動作する

なお、GASの認可はスクリプトを実行するGoogleアカウント自身のGmailが対象です。組織内の他のユーザーのメールを扱う場合は、Google Workspaceのドメイン全体の委任（Domain-wide Delegation）とサービスアカウントを使った別の実装が必要になり、本記事で解説しているGAS単体の標準的な認可フローとは異なる点に注意してください。

---

よくある質問（FAQ）

Q. GmailAppだけではダメなのですか？Gmail APIでないとできないことはありますか？

A. シンプルなメール送信や検索であればGmailAppだけで十分な場合がほとんどです。Gmail APIは、変更履歴を効率的に取得するusers.history.listや、より柔軟な検索・ページング処理など、GmailAppにはない機能を必要とする場合に選択します。詳しくは前述の「GmailAppとGmail APIの使い分け」をご覧ください。

Q. Gmail APIを有効化しても動かない場合、まず何を確認すればいいですか？

A. まずGASエディタの「サービス」にGmail APIが追加されているかを確認し、次に紐付けているGCPプロジェクト側でGmail APIが有効化されているか（特に標準GCPプロジェクトを使っている場合）を確認してください。それでも解決しない場合は、初回実行時の認可ダイアログで許可したスコープが正しいかも確認します。

Q. GmailAppやGmail APIで、自分以外（別アカウント）のGmailを操作できますか？

A. 通常はスクリプトの実行者（認可したGoogleアカウント）本人のGmailのみが対象です。組織内の他ユーザーのメールを扱いたい場合は、Google Workspaceのドメイン全体の委任とサービスアカウントを使った実装が必要になります。

Q. GCPプロジェクトの利用に課金は発生しますか？

A. GASからの通常のメール送受信・取得程度のリクエスト量であれば、無料枠の範囲内に収まることがほとんどです。大量のリクエストを行う場合は、Google Cloud Consoleの「割り当てと上限」でクォータの状況を確認しておくと安心です。

---

まとめ

この記事のポイント：

• GmailAppはGCP設定不要、Gmail APIはGCPプロジェクトの作成とAPI有効化が必要
• GCP側の設定は「プロジェクト作成→Gmail APIの有効化→GASの「サービス」に追加」の3ステップが基本
• デフォルトのGCPプロジェクトを使う場合はAPI有効化が自動で行われるが、標準GCPプロジェクトを紐付ける場合はAPIを手動で有効化する必要がある
• GAS上での認証はGoogleの標準フローに従うため、クライアントシークレットの管理は基本的に不要
• 「スコープ不足」「PERMISSION_DENIED」等のエラーは、認可スコープ未許可やGCP側でのAPI未有効化が主な原因

✅ GmailApp を利用する場合、GCP設定は不要。GASの標準機能として利用可能。 ✅ Gmail API を利用する場合は、GCPプロジェクトの作成とAPIの有効化が必要。 ✅ GASでGmail APIを使用する際は、GASの認証フローに従い、クライアントシークレットや手動でのOAuth設定は不要。 ✅ GCP上で 「Gmail API」 を有効化し、GASの 「サービス」 でGmail APIを追加することで動作する。

GASでGmail APIを活用することで、より高度なメール処理が可能になります。GCPの設定さえ正しく行えば、手間なくAPIを活用できるので、ぜひ試してみてください。

---

関連記事

• GmailAppの制限を踏まえたメール取得・添付ファイル処理の実装ポイント — GmailAppを使う場合に直面しやすい制限と実装上のポイントを解説
• Google Apps Scriptの利用が適した事例、適さない事例 — GASそのものが向いているケース・向いていないケースを整理

---

本記事の一部はAIを活用して生成されています。