If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jstedfast/MailKit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit today
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 82% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jstedfast/MailKit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jstedfast/MailKit.

What it runs against: a local clone of jstedfast/MailKit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jstedfast/MailKit | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jstedfast/MailKit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jstedfast/MailKit.git
#   cd MailKit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jstedfast/MailKit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jstedfast/MailKit(\\.git)?\\b" \\
  && ok "origin remote is jstedfast/MailKit" \\
  || miss "origin remote is not jstedfast/MailKit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "MailKit/IMailService.cs" \\
  && ok "MailKit/IMailService.cs" \\
  || miss "missing critical file: MailKit/IMailService.cs"
test -f "MailKit/Net/Imap/ImapClient.cs" \\
  && ok "MailKit/Net/Imap/ImapClient.cs" \\
  || miss "missing critical file: MailKit/Net/Imap/ImapClient.cs"
test -f "MailKit/Net/Smtp/SmtpClient.cs" \\
  && ok "MailKit/Net/Smtp/SmtpClient.cs" \\
  || miss "missing critical file: MailKit/Net/Smtp/SmtpClient.cs"
test -f "MailKit/Net/Pop3/Pop3Client.cs" \\
  && ok "MailKit/Net/Pop3/Pop3Client.cs" \\
  || miss "missing critical file: MailKit/Net/Pop3/Pop3Client.cs"
test -f "MailKit/BodyPart.cs" \\
  && ok "MailKit/BodyPart.cs" \\
  || miss "missing critical file: MailKit/BodyPart.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jstedfast/MailKit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MailKit is a cross-platform .NET library that provides IMAP, POP3, and SMTP protocol implementations for sending, receiving, and managing emails programmatically. Built on top of MimeKit (its companion MIME parsing library), it handles the full email lifecycle including authentication, message parsing, attachment handling, and server interaction across Windows, Linux, and macOS. Modular structure with separate NuGet packages: MailKit/ contains the core IMAP/POP3/SMTP client implementations; MimeKit (external dependency) handles MIME parsing and message building. Documentation/ holds Sandcastle docs and live examples. AotCompatibility/ tests .NET AOT (Ahead-of-Time) compilation support. Tests are organized per-protocol (ImapExamples.cs, Pop3Examples.cs, etc.). PowerShell scripts in root manage builds; .github/workflows drives CI.

.NET developers building email clients, automation tools, or server applications that need to integrate email capabilities without implementing RFC 5321/5322 protocols from scratch. Enterprise developers and system administrators who need cross-platform email handling in C#.

Highly mature and production-ready. The project shows strong maintenance signals: extensive CI/CD via GitHub Actions (main.yml, codeql.yml, aot-compatibility.yml), code coverage tracking via Coveralls, Coverity static analysis integration, and official NuGet packages (MailKit, MailKitLite, MimeKit, MimeKitLite) with thousands of daily downloads. Actively developed with comprehensive documentation and examples.

Low-to-moderate risk. Single maintainer (jstedfast) is the primary driver, which is common knowledge in .NET email library circles—mitigate by following release notes closely. No unusual dependency chains visible in file structure (self-contained protocol implementations). Breaking changes are rare given the stable API surface. Main risk: tight coupling to .NET ecosystem means Windows/.NET framework deprecations could impact; monitor .NET EOL schedules.

Recent focus includes AOT (Ahead-of-Time) compilation compatibility validation (AotCompatibility project and aot-compatibility.yml workflow), Dependabot-managed dependency updates, and CodeQL security scanning. Documentation and examples are actively maintained. Parallel development of MimeKit and MailKit is coordinated via .gitmodules.

git clone https://github.com/jstedfast/MailKit.git && cd MailKit && dotnet restore && dotnet build. Or if you need a specific protocol, reference the NuGet package directly: dotnet add package MailKit in your project.

Daily commands: dotnet build MailKit.sln for the full solution. For examples: dotnet run --project Documentation/Examples/ or reference specific example files like ImapExamples.cs. CI uses .github/workflows/main.yml which runs tests on Linux and Windows.

• MailKit/IMailService.cs — Core abstraction defining the unified interface for IMAP, POP3, and SMTP protocols that all mail service implementations must follow.
• MailKit/Net/Imap/ImapClient.cs — Primary entry point for IMAP protocol handling; essential for understanding how the library manages IMAP connections and operations.
• MailKit/Net/Smtp/SmtpClient.cs — Primary entry point for SMTP protocol handling; critical for mail sending functionality and SMTP-specific features.
• MailKit/Net/Pop3/Pop3Client.cs — Primary entry point for POP3 protocol handling; essential for understanding the POP3 implementation and message retrieval.
• MailKit/BodyPart.cs — Core abstraction for MIME body parts; foundational for message structure parsing and manipulation across all protocols.
• MailKit/Folder/IMailFolder.cs — Interface defining folder operations (append, fetch, search, delete); critical for understanding IMAP folder abstraction.
• MailKit.sln — Solution file organizing all projects; required reference for building and understanding project structure.

Add Support for a New SASL Authentication Mechanism

1. Create new class inheriting from SaslMechanism in MailKit/Security/ directory (MailKit/Security/SaslMechanism.cs)
2. Implement Challenge(challenge) and IsAuthenticated property to handle authentication handshake (MailKit/Security/[NewMechanism].cs)
3. Register mechanism in IMAP, SMTP, and POP3 clients' authentication capability checks (MailKit/Net/Imap/ImapClient.cs)
4. Add unit tests verifying mechanism works across all three protocol clients (UnitTests/Net/Imap/ImapClientTests.cs)

Add a New IMAP Extension (RFC)

1. Define capability string and feature properties in ImapCapabilities enum (MailKit/Net/Imap/ImapCapabilities.cs)
2. Add parser for new IMAP response type in ImapEngine parser methods (MailKit/Net/Imap/ImapEngine.cs)
3. Implement extension-specific methods in ImapClient or ImapFolder (MailKit/Net/Imap/ImapClient.cs)
4. Add integration examples in Documentation/Examples/ImapExamples.cs (Documentation/Examples/ImapExamples.cs)

Add New Message Fetch Data Type

1. Define new FetchItem enum value representing the data to fetch (MailKit/Net/Imap/FetchItems.cs)
2. Create corresponding data class storing the fetched information (MailKit/IMessageSummary.cs)
3. Add parser logic in ImapEngine to extract and populate the new data type (MailKit/Net/Imap/ImapEngine.cs)
4. Document new fetch option in ImapFolder.Fetch() XML comments (MailKit/Net/Imap/ImapFolder.cs)

Extend MIME Body Part Handling

1. Create new class inheriting from BodyPart for specialized body part type (MailKit/BodyPart.cs)
2. Override Accept(BodyPartVisitor) for visitor pattern support (MailKit/BodyPartVisitor.cs)
3. Update BodyPartCollection.Create() to instantiate new type based on Content-Type (MailKit/BodyPartCollection.cs)
4. Add example usage in Documentation/Examples/ImapBodyPartExamples.cs (Documentation/Examples/ImapBodyPartExamples.cs)

• .NET (C#) — Cross-platform mail protocol library; .NET provides robust async/await, strong typing, and standard library support for cryptography and networking.
• Async/Await Pattern — Mail operations (network I/O, authentication, message parsing) are I/O-bound; async enables responsive applications without thread-per-connection overhead.
• SASL Framework — Unified abstraction for multiple authentication mechanisms (PLAIN, LOGIN, CRAM-MD5, SCRAM-SHA-256, OAuth2) across IMAP, POP3, and SMTP.
• Visitor Pattern (BodyPartVisitor) — Decouples tree traversal logic from MIME body part structures; enables extensible operations on message parts without modifying core classes.
• TLS/SSL via SslStream — Built-in .NET support for encrypted connections; necessary for secure mail protocol communication.

No required environment variables for basic builds. However: (1) Gmail/Outlook examples in Documentation/Examples/ require OAuth2 credentials to execute as tests—see OAuth2GMailExample.cs and OAuth2ExchangeExample.cs. (2) Some tests may require valid email server credentials or mock servers. (3) .gitmodules references external MimeKit dependency; ensure 'git clone --recursive' or 'git submodule update --init' to get full tree. (4) Windows-only builds may skip some Unix socket tests. (5) AOT tests in AotCompatibility/ require .NET 8+ SDK.

• jstedfast/MimeKit — Companion library providing MIME message parsing, composition, cryptography (S/MIME, OpenPGP), and attachment handling that MailKit depends on
• dotnet/runtime — Provides the .NET runtime, System.Net.Sockets, and System.Security.Cryptography that MailKit builds on; relevant for understanding TLS/AOT constraints
• bouncycastle/bc-csharp — Cryptographic library used by MimeKit (and transitively MailKit) for OpenPGP operations and legacy encryption
• mailcore2/mailcore2 — Historical predecessor C++ email library; MailKit's design was influenced by its API patterns for IMAP/SMTP
• nicolaiarocci/eve — RESTful API framework; some users wrap MailKit clients as HTTP endpoints for serverless email operations

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for OAuth2 examples and authentication flows

The repo contains OAuth2 examples (OAuth2ExchangeExample.cs, OAuth2GMailExample.cs) in Documentation/Examples but there's no evidence of corresponding unit tests in the visible file structure. This is critical for a mail library where authentication is security-sensitive. New contributors can add tests covering successful OAuth2 flows, token refresh, error handling, and edge cases for both Exchange and Gmail providers.

• [ ] Create unit test files for OAuth2 scenarios (e.g., UnitTests/OAuth2ExchangeTests.cs, UnitTests/OAuth2GmailTests.cs)
• [ ] Add tests covering token acquisition, token refresh expiration, invalid credentials, and network failures
• [ ] Reference and test against the existing Documentation/Examples/OAuth2ExchangeExample.cs and OAuth2GMailExample.cs
• [ ] Ensure tests mock external OAuth2 endpoints to avoid live service dependencies
• [ ] Add tests for the SslCertificateValidation.cs example patterns

Expand AotCompatibility testing and documentation with specific protocol edge cases

The repo has an AotCompatibility project (AotCompatibility/AotCompatibility.csproj) but it appears minimal. AOT (Ahead-of-Time) compilation is increasingly important for .NET, especially for email libraries used in serverless/containerized environments. Contributors can expand AotCompatibility/Program.cs to test realistic IMAP, POP3, and SMTP workflows and document any necessary [DynamicallyAccessedMembers] annotations needed across the codebase.

• [ ] Expand AotCompatibility/Program.cs to include realistic IMAP connection/authentication flows, POP3 mailbox operations, and SMTP message sending
• [ ] Test deserialization of mime messages (referenced in Documentation/Examples/MimeMessageLoad.cs and MimeParserExamples.cs) under AOT constraints
• [ ] Document any [DynamicallyAccessedMembers] or reflection-based patterns that require AOT-specific configuration
• [ ] Create a new documentation file Documentation/Content/AOT-Compatibility.aml explaining AOT support and limitations
• [ ] Add validation tests for the examples in Documentation/Examples that may use reflection (e.g., OpenPGPExamples.cs, SMimeExamples.cs)

Add integration tests for proxy and SSL/TLS validation scenarios with mock servers

The repo includes ProxyExamples.cs and SslCertificateValidation.cs examples, but there's no visible test coverage for these security-critical features. Network library contributors should add integration tests using mock IMAP/POP3/SMTP servers to verify proxy handling (CONNECT tunneling, SOCKS5) and custom certificate validation logic work correctly across protocol implementations.

• [ ] Create integration test project (e.g., UnitTests/ProxyIntegrationTests.cs) with mock IMAP/POP3/SMTP servers
• [ ] Add tests covering HTTP CONNECT proxy tunneling, SOCKS5 proxy authentication, and proxy connection failures
• [ ] Reference Documentation/Examples/ProxyExamples.cs and Documentation/Examples/SslCertificateValidation.cs to ensure coverage
• [ ] Add tests for custom certificate validation callbacks with invalid/self-signed certificates
• [ ] Test proxy + StartTLS combinations for protocols that support it (IMAP, SMTP)

• Add missing SMTP extension examples: Documentation/Examples/ has 80+ example files but lacks modern ESMTP extension demos (AUTH XOAUTH2, SMTPUTF8, DSN). Contribute examples showing these negotiation flows.
• Expand POP3 examples: Pop3Examples.cs exists but covers only basic list/fetch/delete. Add examples for STLS upgrade, AUTH mechanism negotiation, and UIDL (unique identifier) usage patterns with real-server walkthroughs.
• Document OAuth2 token refresh lifecycle: OAuth2GMailExample.cs and OAuth2ExchangeExample.cs exist but don't show long-running daemon patterns (when/how to refresh, error handling on 401s). Add a new example demonstrating token refresh loops and persistence.

MailKit appears to be a well-maintained security-conscious project with GitHub security advisory integration and Dependabot configured. However, several medium-severity concerns exist: (1) Limited security support window (only latest version), (2) Potential SSL/TLS validation bypass risks that need verification, (3) Lack of visible dependency vulnerability scanning results, and (4) Documentation examples need security audit to prevent users from learning insecure patterns. The codebase handles sensitive email credentials and protocols, making thorough input validation and secure-by-default configurations critical. No hardcoded secrets or obvious injection vulnerabilities are apparent from the file structure alone, but deeper code review is needed for protocol injection risks.

• Medium · Limited Security Update Support — SECURITY.md. According to SECURITY.md, only the latest version (4.x) receives security fixes. All versions below 4.0 are unsupported, which may leave users of older versions vulnerable to known security issues. This creates a fragmented security landscape where many users may be running vulnerable versions. Fix: Consider extending security support to at least one previous major version (e.g., 3.x). Alternatively, provide clear migration guidelines and deprecation warnings for unsupported versions. Consider automated dependency checks to alert users of unsupported versions.
• Medium · Potential SSL/TLS Certificate Validation Bypass Risk — Documentation/Examples/SslCertificateValidation.cs. The file structure includes 'Documentation/Examples/SslCertificateValidation.cs', which suggests certificate validation is configurable. Email protocols (IMAP, POP3, SMTP) involve sensitive credential transmission. If certificate validation can be disabled or bypassed, it could lead to MITM attacks. Fix: Ensure certificate validation is enforced by default and cannot be easily disabled. Provide clear warnings in documentation about the security risks of disabling certificate validation. Consider requiring explicit opt-in with security warnings for any certificate validation bypass.
• Medium · Missing Dependency Vulnerability Information — Package dependencies (*.csproj files). The dependency file content was not provided for analysis. Without visibility into package dependencies (NuGet packages), it's impossible to identify known vulnerable dependencies. MailKit depends on MimeKit and potentially other libraries that could have security issues. Fix: Implement automated dependency scanning using tools like Dependabot (already configured), NuGet vulnerability scanner, or OWASP Dependency-Check in CI/CD pipeline. Regularly audit and update dependencies. Maintain a Software Bill of Materials (SBOM).
• Low · Documentation Examples May Contain Security Pitfalls — Documentation/Examples/ directory. The presence of OAuth2 examples (OAuth2ExchangeExample.cs, OAuth2GMailExample.cs) and credential handling examples suggests authentication flows are documented. If examples show insecure patterns (storing credentials in plain text, hardcoding secrets, etc.), they could mislead users into implementing vulnerable code. Fix: Audit all example code for security best practices. Ensure examples never contain hardcoded credentials, secrets, or API keys. Include security warnings and best practices in credential handling examples. Consider using placeholder values clearly marked as such.
• Low · Potential Email Protocol Injection Vulnerabilities — MailKit core implementation files (not fully visible in file structure). As a library handling IMAP, POP3, and SMTP protocols, MailKit constructs and parses protocol commands. If user input is not properly sanitized before being sent to email servers, protocol injection attacks (header injection, command injection) could be possible, especially in SMTP message construction. Fix: Implement strict input validation and sanitization for all user-supplied data used in protocol commands. Use parameterized/escaped commands where possible. Conduct security-focused code review of protocol command construction, especially in SMTP module. Consider adding a security linter for protocol-specific injection patterns.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.