jstedfast/MailKit · error · NotSupportedException

The IMAP server does not support the CREATE-SPECIAL-USE…

Error message

The IMAP server does not support the CREATE-SPECIAL-USE extension.

What it means

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.

Solutions

1. Check ImapClient.Capabilities for ImapCapabilities.CreateSpecialUse before passing specialUses to Create
2. Call Create without special-use flags and set the special-use attribute server-side (config or a SETMETADATA/ADMIN step) instead
3. Upgrade or reconfigure the IMAP server to support RFC 6154 CREATE-SPECIAL-USE
4. Wrap the create call in try/catch for NotSupportedException and fall back to a plain Create

Example fix

// before
var sent = client.GetFolder(SpecialFolder.Sent); // throws when unsupported
var folder = client.GetFolder(client.PersonalNamespaces[0]).Create(sent, "Archive", true);
// after
ImapClient imap = (ImapClient)client;
IEnumerable<SpecialFolder> uses = (imap.Capabilities & ImapCapabilities.CreateSpecialUse) != 0
    ? new[] { SpecialFolder.Archive }
    : Enumerable.Empty<SpecialFolder>();
var folder = client.GetFolder(client.PersonalNamespaces[0]).Create(uses, "Archive", true);

if (((ImapClient)client).Capabilities.HasFlag(ImapCapabilities.CreateSpecialUse))
    folder.Create(new[] { SpecialFolder.Archive }, "Archive", true);
else
    folder.Create("Archive", true);

bool SupportsSpecialUse(IMailClient client) =>
    client is ImapClient imap && (imap.Capabilities & ImapCapabilities.CreateSpecialUse) != 0;

When it happens

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

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

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 SPECIAL-USE nor XLIST…
• An ImapFolder has not been opened.
• Annotation attribute specifiers cannot be empty.
• Annotation attribute specifiers cannot contain '*' or '%'.
• Annotation entry paths cannot be empty.

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

Appendix: source

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

		ImapCommand QueueCreateCommand (string name, IEnumerable<SpecialFolder> specialUses, CancellationToken cancellationToken, out string encodedName)
		{
			if (name == null)
				throw new ArgumentNullException (nameof (name));

			if (!ImapEngine.IsValidMailboxName (name, DirectorySeparator))
				throw new ArgumentException ("The name is not a legal folder name.", nameof (name));

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

			CheckState (false, false);

			if (!string.IsNullOrEmpty (FullName) && DirectorySeparator == '\0')
				throw new InvalidOperationException ("Cannot create child folders.");

			if ((Engine.Capabilities & ImapCapabilities.CreateSpecialUse) == 0)
				throw new NotSupportedException ("The IMAP server does not support the CREATE-SPECIAL-USE extension.");

			var uses = new StringBuilder ();
			uint used = 0;

			foreach (var use in specialUses) {
				var bit = (uint) (1 << ((int) use));

				if ((used & bit) != 0)
					continue;

				used |= bit;

				if (uses.Length > 0)
					uses.Append (' ');

				switch (use) {
				case SpecialFolder.All:       uses.Append ("\\All"); break;
				case SpecialFolder.Archive:   uses.Append ("\\Archive"); break;

View on GitHub (pinned to 9d3859a785)