Method: users.messages.list
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تعرض هذه الطريقة الرسائل في صندوق بريد المستخدم. للاطّلاع على مثال على الاستخدام، يُرجى الانتقال إلى عرض رسائل Gmail.
طلب HTTP
GET https://gmail.googleapis.com/gmail/v1/users/{userId}/messages
يستخدِم عنوان URL بنية تحويل الترميز gRPC.
مَعلمات المسار
| المعلمات |
userId |
string
عنوان البريد الإلكتروني للمستخدم يمكن استخدام القيمة الخاصة me للإشارة إلى المستخدم الذي تمّت مصادقته.
|
مَعلمات طلب البحث
| المعلمات |
maxResults |
integer (uint32 format)
الحدّ الأقصى لعدد الرسائل المطلوب عرضها القيمة التلقائية لهذا الحقل هي 100. الحد الأقصى المسموح به لهذه القيمة هو 500.
|
pageToken |
string
رمز مميّز للصفحة لاسترداد صفحة معيّنة من النتائج في القائمة.
|
q |
string
عرض الرسائل التي تتطابق مع طلب البحث المحدّد فقط يتوافق مع تنسيق طلب البحث نفسه المستخدَم في مربع بحث Gmail. مثلاً: "from:someuser@example.com rfc822msgid:<somemsgid@example.com>
is:unread" لا يمكن استخدام المَعلمة عند الوصول إلى واجهة برمجة التطبيقات باستخدام النطاق gmail.metadata.
|
labelIds[] |
string
عرض الرسائل التي تتضمّن تصنيفات تطابق جميع أرقام تعريف التصنيفات المحدّدة فقط قد تتضمّن الرسائل في سلسلة محادثات تصنيفات لا تتضمّنها الرسائل الأخرى في سلسلة المحادثات نفسها. لمزيد من المعلومات، يُرجى الاطّلاع على إدارة التصنيفات في الرسائل وسلاسل المحادثات.
|
includeSpamTrash |
boolean
تضمين الرسائل من SPAM وTRASH في النتائج
|
نص الطلب
يجب أن يكون نص الطلب فارغًا.
نص الاستجابة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
| تمثيل JSON |
{
"messages": [
{
object (Message)
}
],
"nextPageToken": string,
"resultSizeEstimate": integer
} |
| الحقول |
messages[] |
object (Message)
قائمة الرسائل يُرجى العِلم أنّ كل مرجع رسالة يحتوي على id وthreadId فقط. يمكن استرداد تفاصيل إضافية عن الرسالة باستخدام طريقة messages.get.
|
nextPageToken |
string
رمز مميز لاسترداد الصفحة التالية من النتائج في القائمة
|
resultSizeEstimate |
integer (uint32 format)
إجمالي عدد النتائج المقدَّر
|
نطاقات الأذونات
يجب توفير أحد نطاقات OAuth التالية:
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.metadata
لمزيد من المعلومات، يمكنك الاطّلاع على دليل التفويض.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Method: users.messages.list\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Query parameters](#body.QUERY_PARAMETERS)\n- [Request body](#body.request_body)\n- [Response body](#body.response_body)\n - [JSON representation](#body.ListMessagesResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [Try it!](#try-it)\n\nLists the messages in the user's mailbox. For example usage, see [List Gmail messages](https://developers.google.com/workspace/gmail/api/guides/list-messages).\n\n### HTTP request\n\n`GET https://gmail.googleapis.com/gmail/v1/users/{userId}/messages`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n| Parameters ||\n|----------|-----------------------------------------------------------------------------------------------------------|\n| `userId` | `string` The user's email address. The special value `me` can be used to indicate the authenticated user. |\n\n### Query parameters\n\n| Parameters ||\n|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `maxResults` | `integer (`[uint32](https://developers.google.com/discovery/v1/type-format)` format)` Maximum number of messages to return. This field defaults to 100. The maximum allowed value for this field is 500. |\n| `pageToken` | `string` Page token to retrieve a specific page of results in the list. |\n| `q` | `string` Only return messages matching the specified query. Supports the same query format as the Gmail search box. For example, `\"from:someuser@example.com rfc822msgid:\u003csomemsgid@example.com\u003e is:unread\"`. Parameter cannot be used when accessing the api using the gmail.metadata scope. |\n| `labelIds[]` | `string` Only return messages with labels that match all of the specified label IDs. Messages in a thread might have labels that other messages in the same thread don't have. To learn more, see [Manage labels on messages and threads](https://developers.google.com/workspace/gmail/api/guides/labels#manage_labels_on_messages_threads). |\n| `includeSpamTrash` | `boolean` Include messages from `SPAM` and `TRASH` in the results. |\n\n### Request body\n\nThe request body must be empty.\n\n### Response body\n\nIf successful, the response body contains data with the following structure:\n\n| JSON representation |\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"messages\": [ { object (/workspace/gmail/api/reference/rest/v1/users.messages#Message) } ], \"nextPageToken\": string, \"resultSizeEstimate\": integer } ``` |\n\n| Fields ||\n|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `messages[]` | `object (`[Message](/workspace/gmail/api/reference/rest/v1/users.messages#Message)`)` List of messages. Note that each message resource contains only an `id` and a `threadId`. Additional message details can be fetched using the [messages.get](/workspace/gmail/api/v1/reference/users/messages/get) method. |\n| `nextPageToken` | `string` Token to retrieve the next page of results in the list. |\n| `resultSizeEstimate` | `integer (`[uint32](https://developers.google.com/discovery/v1/type-format)` format)` Estimated total number of results. |\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://mail.google.com/`\n- `\n https://www.googleapis.com/auth/gmail.modify`\n- `\n https://www.googleapis.com/auth/gmail.readonly`\n- `\n https://www.googleapis.com/auth/gmail.metadata`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent)."]]
