jstedfast/MailKit · error · InvalidOperationException

Only message events may be specified when SELECTED or…

Error message

Only message events may be specified when SELECTED or SELECTED-DELAYED is used.

What it means

ImapEventGroup.Format() validates the NOTIFY event list: when the event group's mailbox filter is SELECTED or SELECTED-DELAYED (RFC 5465), only message events (MessageNew, MessageExpunge) may be included. Including e.g. MailboxEvents or FlagChange-only/metadata events for the selected filter is invalid and throws InvalidOperationException.

Solutions

Only add ImapEvent.MessageNew and ImapEvent.MessageExpunge (message events) when MailboxFilter is Selected/SelectedDelayed
Move non-message events into a separate ImapEventGroup with MailboxFilter set to Personal or Subscribed
Assert-validate the group before use via ImapClient's AssertFormatEventGroup path in a unit test

Example fix

// before
var group = new ImapEventGroup(ImapMailboxFilter.Selected) {
    Events = { ImapEvent.MessageNew, ImapEvent.MailboxName }
};

// after
var selected = new ImapEventGroup(ImapMailboxFilter.Selected) {
    Events = { ImapEvent.MessageNew, ImapEvent.MessageExpunge }
};
var personal = new ImapEventGroup(ImapMailboxFilter.Personal) {
    Events = { ImapEvent.MailboxName }
};

Defensive patterns

Strategy: validation

Validate before calling

bool IsValidSelectedGroup(ImapEventGroup g) =>
    (g.MailboxFilter != ImapMailboxFilter.Selected && g.MailboxFilter != ImapMailboxFilter.SelectedDelayed)
    || g.Events.All(e => e == ImapEvent.MessageNew || e == ImapEvent.MessageExpunge);

Type guard

null

Try / catch

try {
    client.Notify(eventGroups);
} catch (InvalidOperationException ex) when (ex.Message.Contains("Only message events")) {
    // rebuild group with only message events
}

Prevention

Keep SELECTED groups limited to MessageNew/MessageExpunge
Put non-message events in separate Personal/Subscribed groups
Unit-test event group composition against RFC 5465 rules

When it happens

Trigger: Creating an ImapEventGroup with ImapMailboxFilter.Selected (or SelectedDelayed) and adding non-message events like ImapEvent.MailboxName, SubscriptionChange, or MessageExpunge-incompatible events, then calling Notify / AssertFormatEventGroup.

Common situations: Misreading RFC 5465 NOTIFY semantics - developers assume all event kinds can be attached to the selected mailbox; porting a generic event-group config that worked with Personal/Selected filter to SELECTED.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapEventGroup.cs:138

			bool isSelectedFilter = MailboxFilter == ImapMailboxFilter.Selected || MailboxFilter == ImapMailboxFilter.SelectedDelayed;

			command.Append ('(');
			MailboxFilter.Format (engine, command, args);
			command.Append (' ');

			if (Events.Count > 0) {
				var haveAnnotationChange = false;
				var haveMessageExpunge = false;
				var haveMessageNew = false;
				var haveFlagChange = false;

				command.Append ('(');

				for (int i = 0; i < Events.Count; i++) {
					var @event = Events[i];

					if (isSelectedFilter && !@event.IsMessageEvent)
						throw new InvalidOperationException ("Only message events may be specified when SELECTED or SELECTED-DELAYED is used.");

					if (@event is ImapEvent.MessageNew)
						haveMessageNew = true;
					else if (@event == ImapEvent.MessageExpunge)
						haveMessageExpunge = true;
					else if (@event == ImapEvent.FlagChange)
						haveFlagChange = true;
					else if (@event == ImapEvent.AnnotationChange)
						haveAnnotationChange = true;

					if (i > 0)
						command.Append (' ');

					@event.Format (engine, command, args, isSelectedFilter);
				}
				command.Append (')');

				// https://tools.ietf.org/html/rfc5465#section-5

View on GitHub (pinned to 9d3859a785)