MCP Tools Reference: gmailmcp.googleapis.com

الأداة: list_drafts

تعرض هذه الأداة مسودّات الرسائل الإلكترونية من حساب Gmail الخاص بالمستخدم الذي تم التحقّق من هويته.

يمكن لهذه الأداة فلترة المسودّات استنادًا إلى سلسلة طلب بحث وتتيح تقسيم النتائج على صفحات. تعرض هذه الأداة قائمة بالمسودّات، بما في ذلك أرقام تعريفها ومواضيعها (ما لم يتم ضبط view على DRAFT_VIEW_METADATA_ONLY). يمكن استخدام page_token لتقسيم النتائج على صفحات. لاسترداد الصفحات اللاحقة من النتائج، استخدِم page_token الذي تم عرضه في الردّ السابق.

تتحكّم المَعلمة view في الحقول التي يتم ملؤها في الردّ. تلقائيًا (أو باستخدام DRAFT_VIEW_FULL)، يتم عرض المحتوى الكامل. استخدِم DRAFT_VIEW_METADATA_ONLY لاستبعاد المحتوى الحسّاس، مثل الموضوع والنص.

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة list_drafts في OneMCP.

طلب 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 RPC.

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)، يتم عرض المحتوى الكامل، الذي يتضمّن رقم تعريف المسودّة ورقم تعريف السلسلة والرسائل المرسَلة إلى المستلِمين والنسخ إلى والنسخ المخفية الوجهة والتاريخ والموضوع والنص. استخدِم DRAFT_VIEW_METADATA_ONLY لاستبعاد الموضوع والنص.

DraftView

عملية تعداد للتحكّم في الحقول التي يتم ملؤها للمسودّات في الردّ على ListDrafts.

عمليات التعداد
DRAFT_VIEW_UNSPECIFIED تتم مطابقة هذه القيمة مع DRAFT_VIEW_FULL للتوافق مع الأنظمة القديمة.
DRAFT_VIEW_METADATA_ONLY البيانات الوصفية فقط: لا تتضمّن الموضوع وplaintext_body وhtml_body.
DRAFT_VIEW_FULL البيانات الوصفية + المحتوى الذي ينشئه المستخدم (السلوك التلقائي)

مخطط النتائج

رسالة الردّ لـ ListDrafts RPC.

ListDraftsResponse

تمثيل 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

قائمة بعناوين البريد الإلكتروني للمستلِمين في الحقل "نسخة إلى" التي تم استخراجها من العناوين
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