يتيح لك هذا التركيب المتقدّم استخدام طلبات البحث
لفلترة الرسائل حسب سمات مثل المرسِل أو التاريخ أو التصنيف، على سبيل المثال لا الحصر. على سبيل المثال، يسترد طلب البحث التالي جميع الرسائل التي أرسلها المستخدم في كانون الثاني (يناير) 2014:
GET https://www.googleapis.com/gmail/v1/users/me/messages?q=in:sent after:2014/01/01 before:2014/02/01
بالإضافة إلى طلبات البحث، يمكنك أيضًا فلترة الرسائل وسلاسل المحادثات حسب التصنيف باستخدام المَعلمة labelIds. يتيح لك ذلك البحث عن الرسائل وسلاسل المحادثات التي تم تطبيق تصنيفات النظام أو المستخدم المحددة عليها. لمزيد من المعلومات، راجِع مرجع الطريقتَين messages.list أو threads.list.
الاختلافات بين البحث والفلترة: واجهة مستخدم Gmail مقابل Gmail API
تنفّذ واجهة مستخدم Gmail توسيع الاسم المستعار الذي يتيح لها استنتاج اسم مستعار للحساب من حساب Google Workspace. على سبيل المثال، لنفترض أنّ لديك حسابًا بعنوان myprimary@mycompany.net وأنّ المشرف أعدّ اسمًا مستعارًا لهذا الحساب وهو myalias@mycompany.net. إذا أرسل myalias@mycompany.net رسالة إلكترونية، ولكنك بحثت عن "from: myprimary@mycompany.net)"، ستظهر الرسالة الإلكترونية التي أرسلها myalias@mycompany.net كنتيجة بحث في واجهة مستخدم Gmail، ولكن ليس في ردّ واجهة برمجة التطبيقات.
تتيح واجهة مستخدم Gmail للمستخدمين إجراء عمليات بحث على مستوى سلسلة المحادثات، ولكن لا تتيحها واجهة برمجة التطبيقات.
تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Searching for Messages\n\nYou can search or filter files using the\n[`messages.list`](/workspace/gmail/api/v1/reference/users/messages/list) and\n[`threads.list`](/workspace/gmail/api/v1/reference/users/threads/list) methods.\nThese methods accept the `q` parameter which supports most of the same\n[advanced search syntax](https://support.google.com/mail/answer/7190) as\nthe Gmail web-interface. For a list of search and filter differences between\nthe Gmail UI and Gmail API, see\n[Search filter differences: Gmail UI versus Gmail API](#differences).\n\nThis advanced syntax allows you to use search queries\nto filter messages by properties such as the sender, date, or label to name a\nfew possibilities. For example, the following query retrieves all messages sent\nby the user in January of 2014: \n\n GET https://www.googleapis.com/gmail/v1/users/me/messages?q=in:sent after:2014/01/01 before:2014/02/01\n\n| **Warning:** All dates used in the search query are interpreted as midnight on that date in the PST timezone. To specify accurate dates for other timezones pass the value in seconds instead: \n|\n| ```\n| ?q=in:sent after:1388552400 before:1391230800\n| ```\n\nIn addition to search queries, you can also filter messages and threads by label\nwith the `labelIds` parameter. This allows you to search for messages and\nthreads with the specified system or user labels applied. For more information,\nsee the [`messages.list`](/workspace/gmail/api/v1/reference/users/messages/list) or\n[`threads.list`](/workspace/gmail/api/v1/reference/users/threads/list) method reference.\n\nSearch and filter differences: Gmail UI versus Gmail API\n--------------------------------------------------------\n\n- The Gmail UI performs *alias expansion* which allows it to infer an\n account alias from a Google Workspace account. For example, suppose you have an\n account\n of `myprimary@mycompany.net` and your admin sets up an alias for that account of\n `myalias@mycompany.net`. If `myalias@mycompany.net` sends an email, but you\n search for \"`from: myprimary@mycompany.net)`\" the email sent by\n `myalias@mycompany.net` shows up as a search result the Gmail UI, but not in\n the API response.\n\n- The Gmail UI allows users to perform thread-wide searches, but the API\n doesn't."]]
