jstedfast/MailKit · error · NotSupportedException

The IMAP server does not support the STARTTLS extension.

Error message

The IMAP server does not support the STARTTLS extension.

What it means

When connecting with SecureSocketOptions.StartTls, MailKit checks the server's IMAP CAPABILITIES for the STARTTLS capability. If the server never advertised STARTTLS, upgrading the connection is impossible, so a NotSupportedException is thrown instead of sending credentials in plaintext.

Solutions

1. Use SecureSocketOptions.SslOnConnect with port 993 if the server supports implicit TLS
2. If the server genuinely lacks TLS, use SecureSocketOptions.None (insecure; avoid) and confirm this is acceptable
3. Check server configuration to re-enable STARTTLS if it was disabled
4. Inspect the CAPABILITIES response (trace/log) to confirm what the server advertises

Example fix

// before
await client.ConnectAsync("imap.example.com", 143, SecureSocketOptions.StartTls);
// after
await client.ConnectAsync("imap.example.com", 993, SecureSocketOptions.SslOnConnect);

await client.ConnectAsync(host, port, SecureSocketOptions.None, cb); // then inspect
bool supportsStartTls = (client.Capabilities & ImapCapabilities.StartTLS) != 0;

try {
	await client.ConnectAsync(host, port, SecureSocketOptions.StartTls);
} catch (NotSupportedException) {
	await client.ConnectAsync(host, 993, SecureSocketOptions.SslOnConnect); // implicit TLS fallback
}

When it happens

Trigger: Connect(host, port, SecureSocketOptions.StartTls, ...) against a server whose CAPABILITIES response lacks STARTTLS — typically a server that only offers implicit TLS on port 993, or one with STARTTLS disabled in its config.

Common situations: Pointing the client at port 993 (implicit TLS) while requesting StartTls; server admins disabling STARTTLS; using a proxy/gateway that strips the capability; older or minimal IMAP servers without TLS support.

Related errors

• The IMAP server does not support the STARTTLS extension.
• The POP3 server does not support the STLS extension.
• No credentials could be found for the IMAP server.
• The ImapClient is not connected.
• The IMAP server does not support the COMPRESS extension.

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

Appendix: source

Thrown at MailKit/Net/Imap/AsyncImapClient.cs:542

			connecting = true;

			var imap = new ImapStream (stream, ProtocolLogger);

			try {
				await engine.ConnectAsync (imap, cancellationToken).ConfigureAwait (false);
			} catch {
				connecting = false;
				throw;
			}

			try {
				// Only query the CAPABILITIES if the greeting didn't include them.
				if (engine.CapabilitiesVersion == 0)
					await engine.QueryCapabilitiesAsync (cancellationToken).ConfigureAwait (false);

				if (options == SecureSocketOptions.StartTls && (engine.Capabilities & ImapCapabilities.StartTLS) == 0)
					throw new NotSupportedException ("The IMAP server does not support the STARTTLS extension.");

				if (starttls && (engine.Capabilities & ImapCapabilities.StartTLS) != 0) {
					var ic = engine.QueueCommand (cancellationToken, null, "STARTTLS\r\n");

					await engine.RunAsync (ic).ConfigureAwait (false);

					if (ic.Response == ImapCommandResponse.Ok) {
						try {
							var tls = new ExtendedSslStream (stream, false, ValidateRemoteCertificate);
							imap.SetStream (tls);

							await SslHandshakeAsync (tls, host, cancellationToken).ConfigureAwait (false);
						} catch (Exception ex) {
							throw SslHandshakeException.Create (ref sslValidationInfo, ex, true, "IMAP", host, port, 993, 143);
						}

						engine.IsSecure = true;

View on GitHub (pinned to 9d3859a785)