{"record":{"id":"14a4136d230ad926","repo":"jstedfast/MailKit","slug":"the-imap-server-does-not-support-annotations","errorCode":null,"errorMessage":"The IMAP server does not support annotations.","messagePattern":"The IMAP server does not support annotations\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolder.cs","lineNumber":4428,"sourceCode":"\t\t\t\tthrow new InvalidOperationException (\"The UTF8 extension has not been enabled.\");\n\n\t\t\treturn format;\n\t\t}\n\n\t\tImapCommand QueueAppendCommand (FormatOptions options, IAppendRequest request, CancellationToken cancellationToken)\n\t\t{\n\t\t\tif (options == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (options));\n\n\t\t\tif (request == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (request));\n\n\t\t\tCheckState (false, false);\n\n\t\t\tvar format = CreateAppendOptions (options);\n\n\t\t\tif (request.Annotations != null && request.Annotations.Count > 0 && (Engine.Capabilities & ImapCapabilities.Annotate) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support annotations.\");\n\n\t\t\tint numKeywords = request.Keywords != null ? request.Keywords.Count : 0;\n\t\t\tvar builder = new StringBuilder (\"APPEND %F \");\n\t\t\tvar list = new List<object> {\n\t\t\t\tthis\n\t\t\t};\n\n\t\t\tif ((request.Flags & SettableFlags) != 0 || numKeywords > 0) {\n\t\t\t\tImapUtils.FormatFlagsList (builder, request.Flags, numKeywords);\n\t\t\t\tbuilder.Append (' ');\n\t\t\t}\n\n\t\t\tif (request.Keywords != null) {\n\t\t\t\tforeach (var keyword in request.Keywords)\n\t\t\t\t\tlist.Add (keyword);\n\t\t\t}\n\n\t\t\tif (request.InternalDate.HasValue) {","sourceCodeStart":4410,"sourceCodeEnd":4446,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolder.cs#L4410-L4446","documentation":"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.","triggerScenarios":"Appending a message whose AppendRequest.Annotations has entries to a server without ANNOTATE capability (e.g. typical Dovecot/Cyrus without annotation config).","commonSituations":"Porting code from an annotation-capable server (Cyrus IMAP with annotations) to one without; unconditionally setting annotations on all uploads.","solutions":["Check (client.Capabilities & ImapCapabilities.Annotate) != 0 before attaching annotations, and skip them if unsupported.","Store annotations out-of-band (e.g. custom headers) when the server lacks ANNOTATE.","Wrap in try/catch on NotSupportedException and retry without annotations."],"exampleFix":"// before\nrequest.Annotations.Add (\"/comment\", \"hello\");\nfolder.Append (options, request);\n// after\nif ((client.Capabilities & ImapCapabilities.Annotate) != 0)\n    request.Annotations.Add (\"/comment\", \"hello\");\nfolder.Append (options, request);","handlingStrategy":"validation","validationCode":"if (request.Annotations?.Count > 0 && (client.Capabilities & ImapCapabilities.Annotate) == 0) request.Annotations.Clear ();","typeGuard":"bool SupportsAnnotations (ImapClient c) => (c.Capabilities & ImapCapabilities.Annotate) != 0;","tryCatchPattern":"try { folder.Append (options, request); } catch (NotSupportedException) when (request.Annotations?.Count > 0) { request.Annotations.Clear (); folder.Append (options, request); }","preventionTips":["Gate annotation usage on the Annotate capability check at session start","Keep annotation data in a parallel structure so it can be stored out-of-band if unsupported","Avoid unconditionally populating Annotations in shared upload helpers"],"tags":["imap","mailkit","annotations","not-supported","append"],"backgroundTag":"unsupported-operation","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}