MCP Tools Reference: gmailmcp.googleapis.com

工具：list_drafts

列出已驗證使用者 Gmail 帳戶中的草稿電子郵件。

這項工具可根據查詢字串篩選草稿，並支援分頁。系統會傳回草稿清單，包括草稿 ID 和主旨 (除非 view 設為 DRAFT_VIEW_METADATA_ONLY)。您可以使用 page_token 將結果分頁。如要擷取後續頁面的結果，請使用先前回應中傳回的 page_token。

view 參數可控制要在回覆中填入哪些欄位。根據預設 (或使用 DRAFT_VIEW_FULL)，這項函式會傳回完整內容。使用 DRAFT_VIEW_METADATA_ONLY 排除主旨和內文等敏感內容。

下列範例示範如何使用 curl 叫用 list_drafts MCP 工具。

Curl 要求 
curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_drafts",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

ListDrafts 遠端程序呼叫的要求訊息。

ListDraftsRequest

JSON 表示法 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "view": enum (DraftView)
}
欄位

聯集欄位 _page_size。

_page_size 只能是下列其中一項：
pageSize

integer

(選用步驟) 要傳回的草稿數量上限。如未指定，則預設值為 20。允許的最大值為 50。

聯集欄位 _page_token。

_page_token 只能是下列其中一項：
pageToken

string

(選用步驟) 這是從先前的 list_drafts 呼叫收到的權杖，用於擷取下一頁結果。如要擷取第一頁，請將此處留空。這項參數主要用於分頁，從上一次 ListDraft 呼叫停止的位置繼續擷取結果，特別是當符合查詢的草稿數量超過 page_size 限制時。

聯集欄位 _query。

_query 只能是下列其中一項：
query

string

範例：

  • subject:OneMCP Update
  • from:gduser1@workspacesamples.dev
  • to:gduser2@workspacesamples.dev AND newer_than:7d
  • project proposal has:attachment
  • is:unread

使用空格或連字號 (-) 可分隔數字，小數點 (.) 則會使系統將數字判定為小數。舉例來說，系統會將 01.2047-100 判定為兩個數字：01.2047 和 100。

注意：如要確保系統傳回查詢的所有草稿，我們可以重複呼叫工具，直到回覆包含空白的草稿清單為止，藉此將結果分頁。

聯集欄位 _view。

_view 只能是下列其中一項：
view

enum (DraftView)

(選用步驟) 控制草稿清單中草稿的填入欄位。根據預設 (或使用 DRAFT_VIEW_FULL)，這個方法會傳回完整內容，包括草稿 ID、threadID、收件者、副本、密件副本、日期、主旨和內文。使用 DRAFT_VIEW_METADATA_ONLY 排除主旨和內文。

DraftView

列舉，用於控管 ListDrafts 回應中草稿填入的欄位。

列舉
DRAFT_VIEW_UNSPECIFIED 為了確保回溯相容性，會對應至 DRAFT_VIEW_FULL。
DRAFT_VIEW_METADATA_ONLY 僅限中繼資料：不含主旨、plaintext_body、html_body。
DRAFT_VIEW_FULL 中繼資料 + UGC (預設行為)。

輸出內容的結構定義

ListDrafts 遠端程序呼叫的回應訊息。

ListDraftsResponse

JSON 表示法 
{
  "drafts": [
    {
      object (Draft)
    }
  ],
  "nextPageToken": string
}
欄位
drafts[]

object (Draft)

草稿清單。
nextPageToken

string

可在後續呼叫中使用的權杖，用於擷取下一頁草稿。如果符合查詢條件的草稿數量超過 page_size 上限，回應就會包含 next_page_token。如要擷取下一頁結果，請在下一個 ListDraftsRequest 的 page_token 欄位中傳遞這個符記。

草稿

JSON 表示法 
{
  "id": string,
  "subject": string,
  "threadId": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "bccRecipients": [
    string
  ],
  "plaintextBody": string,
  "date": string,
  "htmlBody": string
}
欄位
id

string

草稿資源的專屬 ID。
subject

string

草稿郵件的主旨行。
threadId

string

草稿所屬的執行緒 ID。
toRecipients[]

string

從標頭擷取的「收件者」電子郵件地址清單。
ccRecipients[]

string

從標頭擷取的「副本」收件者電子郵件地址清單。
bccRecipients[]

string

從標頭擷取的「密件副本」收件者電子郵件地址清單。
plaintextBody

string

純文字內文內容 (如有)。
date

string

草稿日期，採用 ISO 8601 格式 (YYYY-MM-DD)。
htmlBody

string

草稿的 HTML 內文 (如有)。

工具註解

破壞性提示：❌ | 等冪提示：❌ | 唯讀提示：✅ | 開放世界提示：❌

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.compose
  • https://www.googleapis.com/auth/gmail.readonly