{"record":{"id":"0b0777344c4a2905","repo":"jstedfast/MailKit","slug":"the-imap-server-does-not-support-the-create-special-use","errorCode":null,"errorMessage":"The IMAP server does not support the CREATE-SPECIAL-USE extension.","messagePattern":"The IMAP server does not support the CREATE-SPECIAL-USE extension\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolder.cs","lineNumber":999,"sourceCode":"\n\t\tImapCommand QueueCreateCommand (string name, IEnumerable<SpecialFolder> specialUses, CancellationToken cancellationToken, out string encodedName)\n\t\t{\n\t\t\tif (name == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (name));\n\n\t\t\tif (!ImapEngine.IsValidMailboxName (name, DirectorySeparator))\n\t\t\t\tthrow new ArgumentException (\"The name is not a legal folder name.\", nameof (name));\n\n\t\t\tif (specialUses == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (specialUses));\n\n\t\t\tCheckState (false, false);\n\n\t\t\tif (!string.IsNullOrEmpty (FullName) && DirectorySeparator == '\\0')\n\t\t\t\tthrow new InvalidOperationException (\"Cannot create child folders.\");\n\n\t\t\tif ((Engine.Capabilities & ImapCapabilities.CreateSpecialUse) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support the CREATE-SPECIAL-USE extension.\");\n\n\t\t\tvar uses = new StringBuilder ();\n\t\t\tuint used = 0;\n\n\t\t\tforeach (var use in specialUses) {\n\t\t\t\tvar bit = (uint) (1 << ((int) use));\n\n\t\t\t\tif ((used & bit) != 0)\n\t\t\t\t\tcontinue;\n\n\t\t\t\tused |= bit;\n\n\t\t\t\tif (uses.Length > 0)\n\t\t\t\t\tuses.Append (' ');\n\n\t\t\t\tswitch (use) {\n\t\t\t\tcase SpecialFolder.All:       uses.Append (\"\\\\All\"); break;\n\t\t\t\tcase SpecialFolder.Archive:   uses.Append (\"\\\\Archive\"); break;","sourceCodeStart":981,"sourceCodeEnd":1017,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolder.cs#L981-L1017","documentation":"MailKit throws this NotSupportedException from ImapFolder.Create when special-use flags (e.g. \\\\Sent, \\\\Drafts per RFC 6154) are requested but the IMAP server did not advertise the CREATE-SPECIAL-USE capability. The library refuses to send a CREATE command with USE parameters that the server would reject anyway.","triggerScenarios":"Calling IMailFolder.Create (via QueueCreateCommand) with a IEnumerable<SpecialFolder> specialUses argument while (Engine.Capabilities & ImapCapabilities.CreateSpecialUse) == 0 — i.e. the server's CAPABILITY response lacks CREATE-SPECIAL-USE.","commonSituations":"Targeting older or minimal IMAP servers (Exchange before 2016, some proxies, Dovecot with limited configs) that don't implement RFC 6154; hardcoding SpecialFolder flags in code that runs against multiple backends.","solutions":["Check ImapClient.Capabilities for ImapCapabilities.CreateSpecialUse before passing specialUses to Create","Call Create without special-use flags and set the special-use attribute server-side (config or a SETMETADATA/ADMIN step) instead","Upgrade or reconfigure the IMAP server to support RFC 6154 CREATE-SPECIAL-USE","Wrap the create call in try/catch for NotSupportedException and fall back to a plain Create"],"exampleFix":"// before\nvar sent = client.GetFolder(SpecialFolder.Sent); // throws when unsupported\nvar folder = client.GetFolder(client.PersonalNamespaces[0]).Create(sent, \"Archive\", true);\n// after\nImapClient imap = (ImapClient)client;\nIEnumerable<SpecialFolder> uses = (imap.Capabilities & ImapCapabilities.CreateSpecialUse) != 0\n    ? new[] { SpecialFolder.Archive }\n    : Enumerable.Empty<SpecialFolder>();\nvar folder = client.GetFolder(client.PersonalNamespaces[0]).Create(uses, \"Archive\", true);","handlingStrategy":"validation","validationCode":"if (((ImapClient)client).Capabilities.HasFlag(ImapCapabilities.CreateSpecialUse))\n    folder.Create(new[] { SpecialFolder.Archive }, \"Archive\", true);\nelse\n    folder.Create(\"Archive\", true);","typeGuard":"bool SupportsSpecialUse(IMailClient client) =>\n    client is ImapClient imap && (imap.Capabilities & ImapCapabilities.CreateSpecialUse) != 0;","tryCatchPattern":null,"preventionTips":["Check Capabilities before using capability-gated IMAP features","Log the server's CAPABILITY string at connect time to know what is supported","Provide fallbacks that create plain folders when extensions are missing"],"tags":["imap","mailkit","unsupported-capability","special-use"],"backgroundTag":"unsupported-operation","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}