業務システム

Gmail APIの使い方:OAuthスコープの選び方とPythonでの送信・受信・ラベル操作、Pub/Sub通知

Gmail APIの使い方:OAuthスコープの選び方とPythonでの送信・受信・ラベル操作、Pub/Sub通知

Gmail APIは、GmailのメールボックスをHTTPのREST APIで操作するための公式APIです。メールの送信、検索と取得、ラベルの付け替え、新着メールのPush通知までがプログラムから操作できる範囲です。この記事では、Google Cloudでの有効化とOAuth同意画面の設定から、Pythonでの送信・受信・ラベル操作のコード、watchとCloud Pub/Subを使った新着通知、毎分のクォータと送信上限、審査が必要になるスコープの避け方までを、業務システムに組み込む実装者の目線で順に整理します。コードは2026年11月時点の公式クライアントライブラリで書いています。

まとめ:Gmail APIで送信と受信を実装する手順とスコープ選びの要点

送信だけなら、スコープは gmail.send の1つに絞ります。これは「機密」区分で、読み取り系の「制限付き」スコープより審査の負担が軽い区分です。メールの中身を読む、ラベルを付け替えるといった処理が要るときだけ gmail.readonly や gmail.modify を足します。

実装の流れは、APIの有効化、OAuthクライアントの作成、Pythonライブラリの導入、トークンの保存、メソッドの呼び出しの5段階です。送信はMIME形式のメールをbase64URLにして messages.send へ渡すだけで、受信は messages.list の検索演算子で対象を絞ってから messages.get で中身を取ります。

新着をすぐ処理したいならポーリングではなく watch とPub/Subを使い、通知を受けたら history.list で差分を取ります。ただし1日に数百通を超える一斉配信やシステムの通知メールには、Gmailアカウントの送信上限があるため向きません。その場合は配信専用のサービスを選びます。

Gmail APIでできる操作とSMTP・IMAPとの違い、無料枠とクォータ

最初に、どの操作にどのメソッドを使い、1回の呼び出しでどれだけクォータを消費するかを押さえておくと、設計の段階で上限に当たる場所が見えます。

送信・検索・ラベル変更・Push通知の4操作と消費クォータの比較表

公式のGmail APIの使用量の上限では、メソッドごとに消費する「クォータユニット」が決まっています。業務システムでよく使う操作を並べると次のとおりです。

操作 メソッド 消費ユニット
メールの送信 messages.send 100
メールIDの一覧・検索 messages.list 5
メール1通の取得 messages.get 20(full・rawは60)
ラベルの付け替え messages.modify 5
新着通知の登録 watch 100
変更履歴の取得 history.list 2

同じ取得でも、format を full や raw にすると3倍のユニットを使います。一覧画面に差出人と件名だけを出すなら metadata で十分です。SMTPやIMAPと比べたときの違いは、ラベルや検索演算子、変更履歴といったGmail固有の機能をそのまま呼べる点にあります。Gmail側でPOPの受信や外部アカウントの取り込みが終わる流れはGmailのPOP受信終了と代替手段の解説で扱っています。

無料で使える範囲と、ユーザー単位で毎分6,000ユニットの上限

クォータは、プロジェクト全体で毎分1,200,000ユニット、1ユーザーあたり毎分6,000ユニットです(2026年11月時点)。messages.send は100ユニットなので、1つのアカウントから送れるのは計算上毎分60通までになります。この値は2026年5月1日以降に作られたプロジェクトに適用される新しい上限で、2025年11月から2026年4月までに利用実績があるプロジェクトは従来の値を引き継ぎます。

料金は、1プロジェクトで1日80,000,000ユニットまでは追加料金がかかりません。超過分は2026年後半から課金される予定で、詳細は少なくとも90日前に通知されると公式ページに書かれています。上限を超えると時間単位のエラーが返るため、再試行には切り詰めた指数バックオフを使ってください。待ち時間の設計はAPIレート制限と429の設計が参考になります。

検証環境の準備:APIの有効化とOAuth同意画面・クライアントIDの作成

手順は公式のPythonクイックスタートに沿っています。Python 3.10.7以上と、Gmailが使えるGoogleアカウントが前提です。

Cloudコンソールでの設定手順とPythonライブラリのインストール

Google Cloudコンソールでの作業は次の4つです。

  1. プロジェクトを作り、APIライブラリでGmail APIを有効にする
  2. Google Auth platformの「ブランディング」でアプリ名とサポート用メールを入れ、対象を「内部」か「外部」から選ぶ
  3. 「データアクセス」で使うスコープを登録する
  4. 「クライアント」でアプリケーションの種類をデスクトップアプリにしてOAuthクライアントIDを作り、JSONを credentials.json として保存する

ライブラリは次のコマンドで入れます。2026年11月21日時点のPyPIでは、google-api-python-clientが2.202.0、google-auth-oauthlibが1.5.0でした。

python3 -m pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

社内のWorkspaceユーザーだけが使うツールなら、手順2で「内部」を選びます。取引先など組織外のアカウントにも使わせる場合だけ「外部」にします。

gmail.sendと制限付きスコープを分け、審査の重さで選ぶ判断

公式のGmail APIのスコープ一覧は、スコープを非機密・機密・制限付きの3つに分けています。業務でよく使うものを並べます。

スコープ できること 区分
gmail.labels ラベルの作成・変更 非機密
gmail.send 送信のみ 機密
gmail.readonly メールの読み取り 制限付き
gmail.modify 読み取りとラベル変更 制限付き
mail.google.com 完全削除を含む全操作 制限付き

制限付きスコープを使う外部向けアプリは、制限付きスコープ用の検証が必要です。さらに、そのスコープで得たデータをサーバーに保存したり送ったりする場合はセキュリティ評価も必要です。全権限の mail.google.com は、ゴミ箱を通さず即座に完全削除する必要がある場合だけ要求するよう公式に書かれています。OAuthの認可の仕組みそのものはOAuth 2.0の仕組みと認可フローの解説、スコープを社内で統制する考え方はGASのOAuthスコープと管理者統制の実務が参考になります。

テスト公開のままだとリフレッシュトークンが7日で切れる落とし穴

対象を「外部」にして公開ステータスが「テスト」のままだと、発行されるリフレッシュトークンは7日で失効します。GoogleのOAuth 2.0の解説ページに明記されている仕様で、名前・メールアドレス・プロフィールだけを求める場合を除きます。

検証中は動いていた夜間バッチが、1週間後に突然 invalid_grant で止まる、という形で表に出ます。本番で外部ユーザー向けに使うなら、公開ステータスを「本番」に切り替え、必要な検証を済ませてから運用に入ります。

Python送信のMIME作成とbase64URL形式のmessages.send

公式のメール送信ガイドのとおり、Gmail APIはRFC 2822に準拠したMIMEメールをbase64URLで符号化し、メッセージの raw に入れて送ります。Pythonなら標準ライブラリの email モジュールで組み立てられます。

認証とトークン保存を共通化するPythonの初期化関数の実装例

送信・受信・通知のどの処理でも使うので、認証とサービスの生成を1つの関数にまとめます。初回はブラウザで同意画面が開き、以後は token.json のリフレッシュトークンで更新されます。

import os
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# 送信と、受信メールのラベル付け替えに必要な最小限のスコープ
SCOPES = [
    "https://www.googleapis.com/auth/gmail.send",
    "https://www.googleapis.com/auth/gmail.modify",
]

def get_service():
    creds = None
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
            creds = flow.run_local_server(port=0)
        # 取得したトークンを保存し、次回からは同意画面を出さない
        with open("token.json", "w") as f:
            f.write(creds.to_json())
    return build("gmail", "v1", credentials=creds)

スコープを変えたときは token.json を消して同意をやり直します。送信しかしないプログラムなら、リストを gmail.send だけにしてください。

EmailMessageで本文とPDF添付を組み、messages.sendで送る例

本文と添付ファイルを持つメールを作り、base64URLに変換して送る関数です。userId に me を渡すと、認証したユーザー自身のアカウントから送られます。

import base64
import os
from email.message import EmailMessage

def send_mail(service, to, subject, body, pdf_path=None):
    msg = EmailMessage()
    msg["To"] = to
    msg["Subject"] = subject
    msg.set_content(body)
    if pdf_path:
        with open(pdf_path, "rb") as f:
            msg.add_attachment(f.read(), maintype="application", subtype="pdf",
                               filename=os.path.basename(pdf_path))
    # MIME全体をbase64URLにしてrawに入れる
    raw = base64.urlsafe_b64encode(msg.as_bytes()).decode()
    sent = service.users().messages().send(userId="me", body={"raw": raw}).execute()
    return sent["id"]

service = get_service()
print(send_mail(service, "[email protected]", "請求書の送付", "今月分の請求書を添付します。", "invoice.pdf"))

宛先は1通あたり500件までという上限がAPI側にあります。From を省くと認証したアカウントのアドレスになり、別のアドレスで送るにはGmailの「送信元アドレス」に登録済みである必要があります。

Pythonでメールを受信・検索する:messages.listの検索条件とラベル操作

受信側の処理は「IDの一覧を取る」「1通ずつ中身を取る」「処理済みの印を付ける」の3段階に分けると、クォータの消費を抑えやすくなります。

検索演算子qで未読の請求書メールだけに絞り込むPythonコード例

messages.list の q には、Gmailの検索窓と同じ演算子を書けます。対象を絞ってから messages.get を呼ぶほど、1通20ユニットの取得回数が減ります。

def find_invoices(service):
    res = service.users().messages().list(
        userId="me",
        q="is:unread has:attachment subject:請求書 newer_than:7d",
        maxResults=50,
    ).execute()
    found = []
    for m in res.get("messages", []):
        # 一覧表示に使うヘッダーだけを取り、ユニットの消費を抑える
        detail = service.users().messages().get(
            userId="me", id=m["id"], format="metadata",
            metadataHeaders=["From", "Subject", "Date"],
        ).execute()
        headers = {h["name"]: h["value"] for h in detail["payload"]["headers"]}
        found.append((m["id"], headers.get("From"), headers.get("Subject")))
    return found

添付ファイルの中身が要る場合は、format="full" で部品の構造を取り、messages.attachments.get で添付のデータを取得します。どちらも消費ユニットが大きいので、本当に添付を読む通に限って呼びます。

処理済みラベルを作り、messages.modifyで未読を外す付け替えの例

取り込んだメールを二重に処理しないよう、処理が終わったら専用のラベルを付けて未読を外します。ラベルの作成は最初の1回だけです。

def ensure_label(service, name="処理済み"):
    labels = service.users().labels().list(userId="me").execute().get("labels", [])
    for lb in labels:
        if lb["name"] == name:
            return lb["id"]
    created = service.users().labels().create(
        userId="me",
        body={"name": name, "labelListVisibility": "labelShow", "messageListVisibility": "show"},
    ).execute()
    return created["id"]

def mark_done(service, msg_id, label_id):
    service.users().messages().modify(
        userId="me", id=msg_id,
        body={"addLabelIds": [label_id], "removeLabelIds": ["UNREAD"]},
    ).execute()

検索条件に -label:処理済み を足しておけば、処理の途中で落ちても再実行で同じメールを拾い直せます。

新着メールをPub/Sub通知で受け取る:watchの登録とhistory.listの差分

数分おきに messages.list を呼ぶポーリングは、メールが来ていない時間もクォータを使います。公式のPush通知のガイドで紹介されているのは、Cloud Pub/Subのトピックに変更を通知させる方式です。Pub/Subのトピックとサブスクリプションの関係はCloud Pub/Subの仕組みとPythonでの送受信で解説しています。

トピック作成とgmail-api-pushへの発行権限を付与するgcloud手順

Gmailが通知を書き込めるよう、トピックへの発行権限を [email protected] に与えます。

gcloud pubsub topics create gmail-inbox
gcloud pubsub topics add-iam-policy-binding gmail-inbox \
  --member="serviceAccount:[email protected]" \
  --role="roles/pubsub.publisher"
gcloud pubsub subscriptions create gmail-inbox-sub --topic=gmail-inbox

組織のポリシーで外部ドメインのメンバー追加を禁じていると、2行目が失敗します。その場合はこのサービスアカウントを例外として許可します。

watchを1日1回更新し、historyIdで差分を取る処理の流れとコード

watch の登録は7日で切れるため、少なくとも7日ごとに呼び直す必要があり、公式は1日1回の更新を勧めています。通知の本文に入るのはメールアドレスと新しい historyId だけなので、前回保存した historyId から history.list で差分を取ります。

from googleapiclient.errors import HttpError

def start_watch(service, project_id):
    # 戻り値のhistoryIdを保存し、expirationより前に再登録する
    return service.users().watch(userId="me", body={
        "topicName": f"projects/{project_id}/topics/gmail-inbox",
        "labelIds": ["INBOX"],
        "labelFilterBehavior": "INCLUDE",
    }).execute()

def added_since(service, start_history_id):
    ids = []
    req = service.users().history().list(
        userId="me", startHistoryId=start_history_id, historyTypes=["messageAdded"])
    try:
        while req is not None:
            res = req.execute()
            for h in res.get("history", []):
                for a in h.get("messagesAdded", []):
                    ids.append(a["message"]["id"])
            req = service.users().history().list_next(req, res)
    except HttpError as e:
        if e.resp.status == 404:
            # 履歴の保持期間を過ぎたので、messages.listによる完全同期へ切り替える
            return None
        raise
    return ids

通知は監視するユーザーごとに毎秒1件までで、超えた分は捨てられます。通知を受けた処理がラベルを付け替え、その変更がまた通知を生むループにも注意してください。labelIds を受信トレイに絞っておくと防ぎやすくなります。

Push通知の欠落と履歴の404に備える定期同期のフォールバック

公式ガイドは、通知が遅れたり届かなかったりする場合があるとして、一定時間通知が来なければ history.list を呼ぶ仕組みを用意するよう求めています。夜間に1回、前回の historyId から差分を取る定期処理を置くのが現実的な形です。

もう1つの備えは404です。同期のガイドによると、変更履歴は通常1週間以上残るものの、期間はそれより短いこともあり、範囲外の startHistoryId を渡すとHTTP 404が返ります。その場合は messages.list で直近のメールを取り直す完全同期に切り替えます。上のコードで None を返しているのはこの分岐です。

本番運用の認証方式と、Gmail APIを採用しない場面の判断基準

手元で動いたコードを業務システムに載せるとき、迷うのは「誰の権限で動かすか」と「そもそもGmail APIでよいか」の2点です。

Workspaceでサービスアカウントとドメイン全体の委任を使う条件

サービスアカウントは自分のメールボックスを持たないため、それだけではGmailを読めません。Google Workspaceの管理者がドメイン全体の委任でクライアントIDとスコープを許可すると、組織内のユーザーに成り代わってAPIを呼べます。共有の受付アドレスを夜間バッチで処理するような、人の同意操作を挟めない処理に向く方式です。

ただし委任は、許可したスコープの範囲で組織内の全ユーザーのメールに届く強い権限です。許可するスコープは処理に必要なものだけにし、鍵を発行したサービスアカウントの管理者を決めておきます。同じGoogleの認証で表計算を読み書きする手順はGoogle Sheets APIのサービスアカウント認証と共通です。

大量配信やシステム通知には配信サービスを選び、Gmailを使わない判断

Gmail APIで送るメールは、そのGmailアカウントから送ったメールとして数えられます。WorkspaceのGmailの送信上限は1ユーザーあたり1日2,000通です。会員向けのお知らせ、パスワード再発行、注文確認のように件数が読めないメールをGmail APIで送る設計は採りません。上限に当たった日に業務が止まるからです。

こうした用途には、Amazon SESのような配信専用サービスを使います。Gmail APIが向くのは、担当者のアカウントから1日数十通の個別のやり取りを自動化する場合や、受信したメールを業務システムに取り込む場合です。Microsoft 365を使う組織なら、同じ用途はMicrosoft Graph APIのsendMailで組みます。受信メールの取り込みを既存の販売管理や問い合わせ管理につなぐ設計は、API開発・システム連携として認証方式と再処理の仕組みまで含めて検討するのが確実です。

Gmail APIの料金・送信上限・認証方式についてよくある質問

Gmail APIを業務システムに組み込むときに、よく確認される点をまとめました。

Gmail APIは無料で使えますか?

2026年11月時点では、1プロジェクトあたり1日80,000,000クォータユニットまでは追加料金がかかりません。この範囲は、1日にメールを数十万通取得してもまだ余る量です。超過分は2026年後半から課金される予定とされ、詳細は少なくとも90日前に通知されます。費用より先に、毎分のクォータと送信上限に当たらない設計かを確かめてください。

Gmail APIで1日に何通まで送信できますか?

APIのクォータでは、1ユーザーあたり毎分6,000ユニット、送信は1通100ユニットなので毎分60通が上限です。それとは別に、Gmailアカウント自体の送信上限があり、Workspaceでは1ユーザー1日2,000通です。API側では、1通の宛先を500件までに制限しています。大量に送る用途には配信専用のサービスを選びます。

個人のGmailアカウントでもサービスアカウントで操作できますか?

できません。サービスアカウントが他人のメールボックスに届くのは、Google Workspaceの管理者がドメイン全体の委任を許可した場合だけです。個人のGmailでは、本人がOAuthの同意画面で許可したトークンを使います。外部・テスト公開のままだとリフレッシュトークンが7日で切れる点にも注意してください。

SMTPやIMAPとGmail APIはどちらを使うべきですか?

既存のメールソフトやライブラリをそのまま使うならSMTP・IMAPで足ります。ラベル操作、Gmailの検索演算子、変更履歴、Push通知を使いたいならGmail APIを選びます。どちらもOAuthでの認証が前提で、パスワードを直接渡す方式に頼った作りは避けてください。

GASのGmailAppとGmail APIはどう使い分けますか?

Googleのアカウント内で完結し、1回の処理が短い自動化ならGASのGmailAppが手軽です。外部のサーバーや既存の業務システムから呼ぶ場合、Push通知で即時に処理したい場合はGmail APIを使います。GASの実行時間の上限と始め方はGASのできること・制限の数値の解説で確認できます。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2025.12.19 コラム アンダーマイニング効果とは?具体例と報酬でやる気が下がる条件、エンハンシング効果との違い
  2. 2026.11.20 テックブログ MAI Code 2とは?Flashとの違い・料金・GitHub Copilotでの使い方【2026年11月】
  3. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装
  4. 2026.11.20 テックブログ 六花亭の不正アクセス:決済画面の改ざんでカード情報約8,000件、対象期間と改ざん検知の手順【11月20日時点】
  5. 2026.11.20 テックブログ 福岡銀行の不正アクセス:FFGインダストリーズ1,221先の漏えい可能性と、分析ツールに認証情報を渡さない実装

RELATED POSTS 関連記事

目次