{"record":{"id":"3d6e3c8b95f7cd82","repo":"jstedfast/MailKit","slug":"the-x-gm-msgid-search-term-is-not-supported-by-the-imap","errorCode":null,"errorMessage":"The X-GM-MSGID search term is not supported by the IMAP server.","messagePattern":"The X-GM-MSGID search term is not supported by the IMAP server\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":367,"sourceCode":"\t\t\t\tbuilder.Append (\"TO \");\n\t\t\t\tAddTextArgument (builder, args, text.Text, ref charset);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Uid:\n\t\t\t\tuid = (UidSearchQuery) query;\n\t\t\t\tbuilder.Append (\"UID \");\n\t\t\t\tbuilder.Append (UniqueIdSet.ToString (uid.Uids));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Younger:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.Within) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The YOUNGER search term is not supported by the IMAP server.\");\n\n\t\t\t\tnumeric = (NumericSearchQuery) query;\n\t\t\t\tbuilder.Append (\"YOUNGER \");\n\t\t\t\tbuilder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.GMailMessageId:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The X-GM-MSGID search term is not supported by the IMAP server.\");\n\n\t\t\t\tnumeric = (NumericSearchQuery) query;\n\t\t\t\tbuilder.Append (\"X-GM-MSGID \");\n\t\t\t\tbuilder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.GMailThreadId:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The X-GM-THRID search term is not supported by the IMAP server.\");\n\n\t\t\t\tnumeric = (NumericSearchQuery) query;\n\t\t\t\tbuilder.Append (\"X-GM-THRID \");\n\t\t\t\tbuilder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.GMailLabels:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The X-GM-LABELS search term is not supported by the IMAP server.\");\n\n\t\t\t\ttext = (TextSearchQuery) query;","sourceCodeStart":349,"sourceCodeEnd":385,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L349-L385","documentation":"MailKit throws this NotSupportedException in ImapFolderSearch.BuildQuery when a SearchQuery uses SearchTerm.GMailMessageId but the connected IMAP server has not advertised the GMailExt1 (X-GM-EXT-1) capability. The X-GM-MSGID search key is a Gmail-specific extension, so the query can only be built for servers that support it.","triggerScenarios":"Calling ImapFolder.Search (or related Search overloads) with a query containing SearchQuery.GMailMessageId (e.g. `SearchQuery.GMailMessageId.Equals(12345)`) against a non-Gmail or capability-unaware IMAP server.","commonSituations":"Pointing Gmail-specific search code at Outlook, Dovecot, Exchange, or other IMAP servers; connecting to Gmail before authentication so capabilities are not yet fully fetched; caching an ImapClient whose capabilities changed after reconnect.","solutions":["Check `imapClient.Capabilities.HasFlag (ImapCapabilities.GMailExt1)` before building the query, and fall back to a non-Gmail search (e.g. header search on Message-ID).","Ensure you call `imapClient.Authenticate` (and the server supports X-GM-EXT-1) before searching — capabilities are updated during login/ID.","Remove or gate the GMailMessageId term so the search works against generic IMAP servers."],"exampleFix":"// before\nvar uid = folder.Search (SearchQuery.GMailMessageId.Equals (msgId));\n// after\nif (client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)) {\n    var uid = folder.Search (SearchQuery.GMailMessageId.Equals (msgId));\n} else {\n    var uid = folder.Search (SearchQuery.HeaderContains (\"Message-Id\", msgId));\n}","handlingStrategy":"validation","validationCode":"if (!client.Capabilities.HasFlag (ImapCapabilities.GMailExt1))\n    throw new InvalidOperationException (\"Server does not support Gmail search extensions; use a fallback query.\");","typeGuard":null,"tryCatchPattern":"try {\n    uids = folder.Search (SearchQuery.GMailMessageId.Equals (msgId));\n} catch (NotSupportedException) {\n    uids = folder.Search (SearchQuery.HeaderContains (\"Message-Id\", msgId));\n}","preventionTips":["Always check ImapCapabilities.GMailExt1 before using any SearchQuery.GMail* term.","Centralize Gmail-specific query building behind one capability-aware helper.","Authenticate before reading Capabilities — they change after login."],"tags":["imap","gmail","capability-check","not-supported"],"backgroundTag":"unsupported-operation","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}