jstedfast/MailKit · error · NotSupportedException

The X-GM-MSGID search term is not supported by the IMAP…

Error message

The X-GM-MSGID search term is not supported by the IMAP server.

What it means

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.

Solutions

1. 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).
2. Ensure you call `imapClient.Authenticate` (and the server supports X-GM-EXT-1) before searching — capabilities are updated during login/ID.
3. Remove or gate the GMailMessageId term so the search works against generic IMAP servers.

Example fix

// before
var uid = folder.Search (SearchQuery.GMailMessageId.Equals (msgId));
// after
if (client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)) {
    var uid = folder.Search (SearchQuery.GMailMessageId.Equals (msgId));
} else {
    var uid = folder.Search (SearchQuery.HeaderContains ("Message-Id", msgId));
}

if (!client.Capabilities.HasFlag (ImapCapabilities.GMailExt1))
    throw new InvalidOperationException ("Server does not support Gmail search extensions; use a fallback query.");

try {
    uids = folder.Search (SearchQuery.GMailMessageId.Equals (msgId));
} catch (NotSupportedException) {
    uids = folder.Search (SearchQuery.HeaderContains ("Message-Id", msgId));
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• The X-GM-THRID search term is not supported by the IMAP…
• The X-GM-LABELS search term is not supported by the IMAP…
• The X-GM-RAW search term is not supported by the IMAP…
• The ImapFolder does not support annotations.
• The IMAP server does not support the Google Mail extensions.

AI-assisted analysis of jstedfast/MailKit@9d3859a785 (2026-09-15). Data as JSON: /api/errors/3d6e3c8b95f7cd82. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolderSearch.cs:367

				builder.Append ("TO ");
				AddTextArgument (builder, args, text.Text, ref charset);
				break;
			case SearchTerm.Uid:
				uid = (UidSearchQuery) query;
				builder.Append ("UID ");
				builder.Append (UniqueIdSet.ToString (uid.Uids));
				break;
			case SearchTerm.Younger:
				if ((Engine.Capabilities & ImapCapabilities.Within) == 0)
					throw new NotSupportedException ("The YOUNGER search term is not supported by the IMAP server.");

				numeric = (NumericSearchQuery) query;
				builder.Append ("YOUNGER ");
				builder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));
				break;
			case SearchTerm.GMailMessageId:
				if ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)
					throw new NotSupportedException ("The X-GM-MSGID search term is not supported by the IMAP server.");

				numeric = (NumericSearchQuery) query;
				builder.Append ("X-GM-MSGID ");
				builder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));
				break;
			case SearchTerm.GMailThreadId:
				if ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)
					throw new NotSupportedException ("The X-GM-THRID search term is not supported by the IMAP server.");

				numeric = (NumericSearchQuery) query;
				builder.Append ("X-GM-THRID ");
				builder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));
				break;
			case SearchTerm.GMailLabels:
				if ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)
					throw new NotSupportedException ("The X-GM-LABELS search term is not supported by the IMAP server.");

				text = (TextSearchQuery) query;

View on GitHub (pinned to 9d3859a785)