MCP Tools Reference: gmailmcp.googleapis.com

ابزار: list_drafts

ایمیل‌های پیش‌نویس را از حساب جیمیل کاربر احراز هویت‌شده فهرست می‌کند.

این ابزار می‌تواند پیش‌نویس‌ها را بر اساس یک رشته پرس‌وجو فیلتر کند و از صفحه‌بندی پشتیبانی می‌کند. این ابزار لیستی از پیش‌نویس‌ها، شامل شناسه‌ها و موضوعات آنها را برمی‌گرداند (مگر اینکه view روی DRAFT_VIEW_METADATA_ONLY تنظیم شده باشد). page_token می‌تواند برای صفحه‌بندی نتایج استفاده شود. برای بازیابی صفحات بعدی نتایج، از page_token برگردانده شده در پاسخ قبلی استفاده کنید.

پارامتر view فیلدهایی را که در پاسخ پر می‌شوند، کنترل می‌کند. به طور پیش‌فرض (یا با DRAFT_VIEW_FULL )، محتوای کامل را برمی‌گرداند. DRAFT_VIEW_METADATA_ONLY برای حذف محتوای حساس مانند موضوع و بدنه استفاده کنید.

نمونه زیر نحوه استفاده از curl برای فراخوانی ابزار list_drafts MCP را نشان می‌دهد.

درخواست کرل 
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
}'

طرحواره ورودی

درخواست پیام برای RPC مربوط به ListDrafts.

درخواست پیش‌نویس‌ها

نمایش JSON 
{

  "pageSize": integer

  "pageToken": string

  "query": string

  "view": enum (DraftView)
}
فیلدها

فیلد یونیون _page_size .

_page_size می‌تواند فقط یکی از موارد زیر باشد:

pageSize

integer

اختیاری. حداکثر تعداد پیش‌نویس‌هایی که باید برگردانده شوند. اگر مشخص نشود، پیش‌فرض ۲۰ است. حداکثر مقدار مجاز ۵۰ است.

فیلد یونیون _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 )، محتوای کامل را برمی‌گرداند که شامل شناسه پیش‌نویس، شناسه رشته، به، cc، bcc، تاریخ، موضوع و بدنه است. DRAFT_VIEW_METADATA_ONLY برای حذف موضوع و بدنه استفاده کنید.

نمای پیش‌نویس

Enum برای کنترل فیلدهای پر شده برای پیش‌نویس‌ها در پاسخ ListDrafts.

انوم‌ها
DRAFT_VIEW_UNSPECIFIED برای سازگاری با نسخه‌های قبلی، به DRAFT_VIEW_FULL نگاشت می‌شود.
DRAFT_VIEW_METADATA_ONLY فقط فراداده: شامل موضوع، متن_بدنه‌ی ساده، و html_body نمی‌شود.
DRAFT_VIEW_FULL فراداده + محتوای تولید شده توسط کاربر (رفتار پیش‌فرض).

طرحواره خروجی

پیام پاسخ برای RPC مربوط به ListDrafts.

پاسخ به پیش نویس های لیست

نمایش JSON 
{
  "drafts": [
    {
      object (Draft)
    }
  ],
  "nextPageToken": string
}
فیلدها
drafts[]

object ( Draft )

فهرست پیش‌نویس‌ها.

nextPageToken

string

یک توکن که می‌تواند در فراخوانی بعدی برای بازیابی صفحه بعدی پیش‌نویس‌ها استفاده شود. اگر تعداد پیش‌نویس‌های منطبق با پرس‌وجو از حد مجاز page_size بیشتر شود، پاسخ حاوی یک next_page_token خواهد بود. برای بازیابی صفحه بعدی نتایج، این توکن را در فیلد page_token از ListDraftsRequest بعدی ارسال کنید.

پیش نویس

نمایش JSON 
{
  "id": string,
  "subject": string,
  "threadId": string,
  "toRecipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "bccRecipients": [
    string
  ],
  "plaintextBody": string,
  "date": string,
  "htmlBody": string
}
فیلدها
id

string

شناسه منحصر به فرد منبع پیش نویس.

subject

string

موضوع پیش‌نویس پیام.

threadId

string

شناسه‌ی تاپیکی که این پیش‌نویس به آن تعلق دارد.

toRecipients[]

string

فهرست آدرس‌های ایمیل گیرنده «به» که از سربرگ‌ها استخراج شده‌اند.

ccRecipients[]

string

فهرست آدرس‌های ایمیل گیرنده «Cc» که از سربرگ‌ها استخراج شده‌اند.

bccRecipients[]

string

فهرست آدرس‌های ایمیل گیرنده «Bcc» که از سربرگ‌ها استخراج شده‌اند.

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