Method: users.messages.list
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
درخواست HTTP
GET https://gmail.googleapis.com/gmail/v1/users/{userId}/messages
URL از دستور GRPC Transcoding استفاده می کند.
پارامترهای مسیر
| پارامترها |
|---|
userId | string آدرس ایمیل کاربر. مقدار ویژه me می تواند برای نشان دادن کاربر تأیید شده استفاده شود. |
پارامترهای پرس و جو
| پارامترها |
|---|
maxResults | integer ( uint32 format) حداکثر تعداد پیام برای بازگشت. این فیلد به طور پیش فرض 100 است. حداکثر مقدار مجاز برای این فیلد 500 است. |
pageToken | string نشانه صفحه برای بازیابی صفحه خاصی از نتایج در لیست. |
q | string فقط پیام های منطبق با درخواست مشخص شده را برگردانید. از همان فرمت پرس و جو مانند جعبه جستجوی Gmail پشتیبانی می کند. برای مثال، "from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread" . هنگام دسترسی به api با استفاده از دامنه 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
برای اطلاعات بیشتر، به راهنمای مجوز مراجعه کنید.
،
درخواست HTTP
GET https://gmail.googleapis.com/gmail/v1/users/{userId}/messages
URL از دستور GRPC Transcoding استفاده می کند.
پارامترهای مسیر
| پارامترها |
|---|
userId | string آدرس ایمیل کاربر. مقدار ویژه me می تواند برای نشان دادن کاربر تأیید شده استفاده شود. |
پارامترهای پرس و جو
| پارامترها |
|---|
maxResults | integer ( uint32 format) حداکثر تعداد پیام برای بازگشت. این فیلد به طور پیش فرض 100 است. حداکثر مقدار مجاز برای این فیلد 500 است. |
pageToken | string نشانه صفحه برای بازیابی صفحه خاصی از نتایج در لیست. |
q | string فقط پیام های منطبق با درخواست مشخص شده را برگردانید. از همان فرمت پرس و جو مانند جعبه جستجوی Gmail پشتیبانی می کند. برای مثال، "from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread" . هنگام دسترسی به api با استفاده از دامنه 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 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده 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)."]]
