MailKit one-click unsubscribe: RFC 8058 code example

MailKit and MimeKit let .NET applications add RFC 8058 headers directly to a MimeMessage. Use them for marketing and subscribed messages, not ordinary transactional messages such as receipts or password resets.

Required headers

• List-Unsubscribe: include HTTPS; mailto can be an additional fallback.
• List-Unsubscribe-Post: List-Unsubscribe=One-Click: requests an RFC 8058 POST.
• Process requests within 48 hours; prefer immediate suppression.

Sample MailKit code (MimeKit)

using MailKit.Net.Smtp;
using MimeKit;

var message = new MimeMessage();
message.From.Add(new MailboxAddress("Product Updates", "[email protected]"));
message.To.Add(MailboxAddress.Parse("[email protected]"));
message.Subject = "Service notice";

var token = "abcd1234"; // signed token per recipient

message.Headers.Add("List-Unsubscribe", $"<https://example.com/unsub/{token}>, <mailto:[email protected]?subject=unsubscribe>");
message.Headers.Add("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");

message.Body = new BodyBuilder
{
    TextBody = "Plain text body",
    HtmlBody = "<p>HTML body with a visible unsubscribe link below.</p>"
}.ToMessageBody();

using var client = new SmtpClient();
await client.ConnectAsync("smtp.example.com", 587, MailKit.Security.SecureSocketOptions.StartTls);
await client.AuthenticateAsync("smtp-user", "smtp-pass");
await client.SendAsync(message);
await client.DisconnectAsync(true);

Notes:

• Keep the unsubscribe link visible in the HTML/text body.
• Accept POST without a login, cookie, or CSRF token and return a successful response quickly.
• Sign tokens; never expose raw emails in query strings.

Handling the endpoint

• Accept POST with List-Unsubscribe=One-Click; reserve GET for a human-facing preference page.
• Immediately suppress the address from the subscription list represented by the token.
• Keep essential transactional mail separate from subscription mail.
• Log timestamp, token/list, IP for audit.

Testing checklist

• Send to Gmail/Yahoo; confirm both headers appear in the raw message.
• Click the link; ensure instant suppression and a 200 response.
• Attempt a follow-up send within 24 hours; the unsubscribed address must be excluded.
• Track complaint rates; keep under 0.1%.

Where SMTP Zen helps

SMTP Zen provides authenticated SMTP delivery for your MailKit clients. Add the headers above, wire your suppression endpoint, and stay aligned with Gmail/Yahoo one-click expectations without switching to a marketing platform.