Gmail APIは現在、Cloud Pub/Subベースの通知システムを使用している。以前のchannel/resourceIdベースのシステムは廃止された。

Watch登録時の仕様

• topicName（Pub/Subトピック）を指定してwatchを作成する
• レスポンスにはhistoryIdとexpirationのみが含まれる
• channelIdやresourceIdは返されない

// 実装例
const response = await gmail.users.watch({
  userId: 'me',
  requestBody: {
    topicName: 'projects/myproject/topics/gmail-watch',
    labelIds: ['INBOX'],
    labelFilterAction: 'include',
  },
});
// response.data = { historyId: "123456", expiration: "1234567890000" }

Webhook通知の処理

Pub/Subメッセージとして通知が送信され、message.dataをbase64デコードすると以下のJSONが取得できる：

{
  "emailAddress": "user@example.com",
  "historyId": "123456"
}

emailAddressを使用してユーザーを識別する必要がある。以前のようにchannelIdでの識別はできない。

データベース設計の考慮点

• channelIdやresourceIdのカラムは不要
• 代わりにローカルで生成したIDで管理する（例：gmail_watch_id）
• ユーザー識別はemailAddress経由で行うため、Userテーブルとの連携が重要

有効期限の管理

• Watchは最大7日間有効
• 定期的な再登録が必要（推奨：1日1回）
• 既存のWatchを停止してから新規作成する

参照: https://developers.google.com/workspace/gmail/api/guides/push