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. אפשר לאחזר פרטים נוספים על ההודעה באמצעות method 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 (שעון UTC).
[null,null,["עדכון אחרון: 2025-07-25 (שעון UTC)."],[],[],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)."]]
