jstedfast/MailKit · error · NotSupportedException

The IMAP server does not support annotations.

Error message

The IMAP server does not support annotations.

What it means

When the IAppendRequest carries annotations (request.Annotations non-empty), the APPEND command needs the IMAP ANNOTATE extension. If ImapCapabilities.Annotate is not advertised by the server, QueueAppendCommand throws NotSupportedException rather than silently dropping the annotations.

Solutions

1. Check (client.Capabilities & ImapCapabilities.Annotate) != 0 before attaching annotations, and skip them if unsupported.
2. Store annotations out-of-band (e.g. custom headers) when the server lacks ANNOTATE.
3. Wrap in try/catch on NotSupportedException and retry without annotations.

Example fix

// before
request.Annotations.Add ("/comment", "hello");
folder.Append (options, request);
// after
if ((client.Capabilities & ImapCapabilities.Annotate) != 0)
    request.Annotations.Add ("/comment", "hello");
folder.Append (options, request);

if (request.Annotations?.Count > 0 && (client.Capabilities & ImapCapabilities.Annotate) == 0) request.Annotations.Clear ();

bool SupportsAnnotations (ImapClient c) => (c.Capabilities & ImapCapabilities.Annotate) != 0;

try { folder.Append (options, request); } catch (NotSupportedException) when (request.Annotations?.Count > 0) { request.Annotations.Clear (); folder.Append (options, request); }

When it happens

Trigger: Appending a message whose AppendRequest.Annotations has entries to a server without ANNOTATE capability (e.g. typical Dovecot/Cyrus without annotation config).

Common situations: Porting code from an annotation-capable server (Cyrus IMAP with annotations) to one without; unconditionally setting annotations on all uploads.

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 IMAP server does not support the UTF8 extension.
• The ImapFolder does not support annotations.
• Value cannot be null. (Parameter 'specifier')
• Annotation attribute specifiers cannot be empty.
• Annotation attribute specifiers cannot contain '*' or '%'.

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolder.cs:4428

				throw new InvalidOperationException ("The UTF8 extension has not been enabled.");

			return format;
		}

		ImapCommand QueueAppendCommand (FormatOptions options, IAppendRequest request, CancellationToken cancellationToken)
		{
			if (options == null)
				throw new ArgumentNullException (nameof (options));

			if (request == null)
				throw new ArgumentNullException (nameof (request));

			CheckState (false, false);

			var format = CreateAppendOptions (options);

			if (request.Annotations != null && request.Annotations.Count > 0 && (Engine.Capabilities & ImapCapabilities.Annotate) == 0)
				throw new NotSupportedException ("The IMAP server does not support annotations.");

			int numKeywords = request.Keywords != null ? request.Keywords.Count : 0;
			var builder = new StringBuilder ("APPEND %F ");
			var list = new List<object> {
				this
			};

			if ((request.Flags & SettableFlags) != 0 || numKeywords > 0) {
				ImapUtils.FormatFlagsList (builder, request.Flags, numKeywords);
				builder.Append (' ');
			}

			if (request.Keywords != null) {
				foreach (var keyword in request.Keywords)
					list.Add (keyword);
			}

			if (request.InternalDate.HasValue) {

View on GitHub (pinned to 9d3859a785)