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/mikel/mail 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 7mo ago
• 15 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago

_{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 mikel/mail repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mikel/mail.

What it runs against: a local clone of mikel/mail — 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 mikel/mail | 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 ≤ 229 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mikel/mail. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mikel/mail.git
#   cd mail
#
# 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 mikel/mail and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mikel/mail(\\.git)?\\b" \\
  && ok "origin remote is mikel/mail" \\
  || miss "origin remote is not mikel/mail (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 "lib/mail.rb" \\
  && ok "lib/mail.rb" \\
  || miss "missing critical file: lib/mail.rb"
test -f "lib/mail/message.rb" \\
  && ok "lib/mail/message.rb" \\
  || miss "missing critical file: lib/mail/message.rb"
test -f "lib/mail/header.rb" \\
  && ok "lib/mail/header.rb" \\
  || miss "missing critical file: lib/mail/header.rb"
test -f "lib/mail/field.rb" \\
  && ok "lib/mail/field.rb" \\
  || miss "missing critical file: lib/mail/field.rb"
test -f "lib/mail/parsers.rb" \\
  && ok "lib/mail/parsers.rb" \\
  || miss "missing critical file: lib/mail/parsers.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 229 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~199d)"
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/mikel/mail"
  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).

Mail is a pure Ruby library for generating, parsing, and sending email messages according to RFC standards. It provides a single unified API to construct email objects programmatically, parse raw email strings into structured objects, and send via SMTP/POP3. Unlike its predecessor TMail, it leverages modern Ruby's superior text encoding support to handle MIME multipart messages, attachments, and character encodings cleanly. Modular single-library structure under lib/mail/: core Message class in lib/mail.rb; email field types in lib/mail/fields/ (BCC, CC, Date, Content-Type, etc.); encoding/transfer mechanisms in lib/mail/encodings/; structured element parsing in lib/mail/elements/ (Address, ContentType, DateTime); and envelope/body management in lib/mail/envelope.rb and lib/mail/body.rb. Uses Ragel state machine for parsing complex headers.

Ruby on Rails developers and other Ruby application developers who need to send transactional emails, parse incoming email, or manipulate email structures programmatically without wrestling with low-level SMTP/MIME details. Also used by email service integrations and background job systems that handle email delivery.

Production-ready and actively maintained. The project has 3.3MB of Ruby code across 60+ files, comprehensive test coverage via GitHub Actions CI, and supports Ruby 2.5+ through 3.2+ plus JRuby and TruffleRuby. The codebase is stable with structured field parsing, encoding support, and attachment handling well-established. However, commit recency and open issue volume are not visible from provided data—check GitHub directly for latest activity.

Low technical risk for standard use cases. The library has minimal external dependencies (managing through Ragel for parsing, ~37KB). Main risks: single-maintainer (mikel) may limit responsiveness; email standards are complex and edge cases in parsing obscure messages could cause failures; breaking changes to the public API would affect many dependent gems in the Rails ecosystem. Check GitHub Issues for current bug backlog and PR response times.

Exact current work is not visible from file data alone, but the repo structure shows active maintenance of RFC compliance: 60+ field types, 8 encoding schemes (base64, quoted-printable, 7bit, 8bit, binary, uuencode), and address/date parsing via Ragel. Check .github/workflows/test.yml for CI scope and CHANGELOG.rdoc for recent fixes.

git clone https://github.com/mikel/mail.git && cd mail && bundle install && bundle exec rake test

Daily commands: bundle exec rake test (runs full test suite). For interactive exploration: bundle console opens a Ruby REPL with mail loaded. No server to start—this is a library, not an application.

• lib/mail.rb — Entry point that requires and exposes all Mail gem functionality; every developer must understand the public API surface here.
• lib/mail/message.rb — Core Message class representing email objects; the primary abstraction that handles headers, body, attachments, and serialization.
• lib/mail/header.rb — Header management system that parses and stores all email headers using a FieldList; critical for understanding message metadata handling.
• lib/mail/field.rb — Field abstraction that routes different header types to specialized field classes; fundamental to the plugin-like field system.
• lib/mail/parsers.rb — Parser registry and dispatch system for all RFC 5322 compliant email parsing; required to understand how raw email text is deserialized.
• lib/mail/encodings.rb — Encoding and transfer-encoding system that handles Base64, Quoted-Printable, and 7/8bit; critical for message body transformations.
• lib/mail/configuration.rb — Global configuration and delivery method setup; all contributors must know how delivery backends are registered and selected.

Add a new header field type

1. Create field class in lib/mail/fields/ inheriting from StructuredField or UnstructuredField (lib/mail/fields/my_custom_field.rb)
2. Implement custom parsing/serialization logic; use elements from lib/mail/elements/ if needed (lib/mail/fields/my_custom_field.rb)
3. Register field in Field.field_map hash by field name so Field.new('My-Custom') routes correctly (lib/mail/field.rb)
4. Add accessor method to Message class to allow message.my_custom = value (lib/mail/message.rb)

Add a new delivery method

1. Create delivery class in lib/mail/network/delivery_methods/ inheriting from Base (lib/mail/network/delivery_methods/my_backend.rb)
2. Implement deliver! method that accepts a Message and performs delivery (lib/mail/network/delivery_methods/my_backend.rb)
3. Register delivery method in Configuration.instance.delivery_method call (lib/mail/configuration.rb)
4. Add configuration options in Configuration class for your method (e.g., host, port) (lib/mail/configuration.rb)

Add support for a new content transfer encoding

1. Create encoder class in lib/mail/encodings/ with encode() and decode() class methods (lib/mail/encodings/my_encoding.rb)
2. Register encoding name in Encodings.register('my-encoding', MyEncoding) (lib/mail/encodings.rb)
3. Update ContentTransferEncodingElement to recognize the new encoding name if parsing needed (lib/mail/elements/content_transfer_encoding_element.rb)
4. Verify Body class correctly applies encoding via message.body.encoding = 'my-encoding' (lib/mail/body.rb)

Add a new parser for a header format

1. Create Ragel grammar file (.rl) in lib/mail/parsers/ defining syntax (lib/mail/parsers/my_parser.rl)
2. Generate Ruby parser from Ragel file using ragel compiler (lib/mail/parsers/my_parser.rb)
3. Create element class in lib/mail/elements/ to hold parsed result (lib/mail/elements/my_element.rb)
4. Register parser in Parsers module and use in corresponding Field class (lib/mail/parsers.rb)

• Pure Ruby (no native extensions) — Portability across Ruby implementations and platforms; easier maintenance and installation
• Ragel-generated parsers — RFC 5322 compliance; finite-state machine approach handles complex email syntax reliably
• Net::SMTP, Net::POP3, Net::IMAP — Leverage Ruby stdlib for network I/O; no external C dependencies; pluggable delivery/retrieval
• Unicode/multibyte character handling — Ruby 1.9+ native support for encodings; proper charset conversion for international email

• Eager parsing of headers on message creation

  • Why: Simplicity; intuitive object-oriented API for developers
  • Consequence: Higher memory footprint and startup latency for large messages; not ideal for streaming huge attachments

• Separate Field classes per

  • Why: undefined
  • Consequence: undefined

Email parsing is highly forgiving by design (handles malformed headers gracefully) but strict serialization (to_s) produces RFC-compliant output—roundtrip may normalize whitespace/encoding. Character encoding must match Ruby file encoding or set explicitly. MIME multipart boundary generation is automatic but can be overridden via Content-Type header (risky if not careful). Net::SMTP requires working network; tests may hang if DNS/SMTP unreachable.

• RFC 5322 (Internet Message Format) — Mail's entire field-parsing and serialization logic is built on RFC 5322 syntax rules; knowing this spec explains why certain characters require escaping and how headers are normalized
• MIME Multipart Messages (RFC 2045–2049) — Attachments, HTML+text alternatives, and embedded images all rely on MIME multipart structure; Mail abstracts this via Body and PartsList but you must understand boundaries and Content-Disposition
• Content Transfer Encoding (Base64, Quoted-Printable) — Mail's lib/mail/encodings/ implements these schemes to ensure binary attachments and non-ASCII text survive SMTP transport; choosing the right encoding affects message size and compatibility
• Ragel State Machine Compiler — Mail uses Ragel-generated parsers in lib/mail/elements/ to safely parse complex RFC header syntax (addresses with quoted strings, date/time zones, etc.); Ragel grammar is compiled to optimized Ruby code
• Address Parsing (RFC 5321 SMTP vs RFC 5322 Mailbox) — Mail distinguishes envelope addresses (SMTP Return-Path, lib/mail/envelope.rb) from message headers (From, To, CC); mismatched parsing causes delivery and reply-to failures
• Character Encoding & Internationalized Email (RFC 6531) — Modern Ruby handles UTF-8 natively, but Mail must serialize non-ASCII headers using RFC 2047 MIME-encoded-word syntax; understanding this prevents mojibake (garbled text) in email clients
• Field Inheritance Pattern (CommonField, CommonAddressField) — Mail uses deep inheritance hierarchies (CommonField → CommonAddressField → BccField) to share parsing/serialization logic; understanding this pattern is key to extending Mail for custom headers

• ruby/net-smtp — Standard library SMTP client that Mail wraps; understanding Net::SMTP internals helps debug delivery issues
• jruby/jruby — Mail explicitly tests against JRuby 9.2+ in CI; critical for Java ecosystem Ruby deployments
• rails/rails — ActionMailer depends on Mail; Rails developers are primary users and ActionMailer documentation links to Mail
• ruby-truffleruby/truffleruby — Mail tests against TruffleRuby; performance-critical email systems may use this JVM alternative
• vmg/redcarpet — Similar mature, actively-maintained pure-Ruby library handling a complex standard (Markdown); architectural parallel for reference

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 tests for encoding edge cases in lib/mail/encodings/

The encodings directory has 8 different encoding implementations (7bit, 8bit, base64, binary, identity, quoted_printable, transfer_encoding, unix_to_unix) but there's no visibility into test coverage for edge cases like invalid input, boundary conditions, and round-trip encoding/decoding. Adding focused test cases would prevent regressions and improve reliability for a core feature.

• [ ] Create test/mail/encodings/ directory structure mirroring lib/mail/encodings/
• [ ] Add test_base64.rb covering valid/invalid input, line wrapping, and round-trip encoding
• [ ] Add test_quoted_printable.rb covering special characters, soft line breaks, and RFC 2047 compliance
• [ ] Add test_transfer_encoding.rb for the base class and polymorphic behavior
• [ ] Add integration tests in test/mail/ to verify encoding selection based on content type

Add integration tests for all field types in lib/mail/fields/

There are 30+ field implementations (from_field, to_field, bcc_field, resent_* fields, etc.) but no clear test coverage visibility. These fields are critical RFC 5322 compliance points. Adding structured tests would ensure parsing/serialization correctness and catch regressions when the common field base classes change.

• [ ] Create test/mail/fields/test_common_fields.rb to test inheritance chain (CommonField, NamedStructuredField, NamedUnstructuredField)
• [ ] Add test/mail/fields/test_address_fields.rb covering From, To, CC, BCC, ReplyTo, ResendFrom parsing with edge cases (quoted names, international addresses)
• [ ] Add test/mail/fields/test_date_fields.rb for Date, ResendDate field parsing and timezone handling
• [ ] Add test/mail/fields/test_message_id_fields.rb for MessageID, InReplyTo, References validation
• [ ] Add property-based tests verifying round-trip: parse(serialize(field)) == field

Add GitHub Actions workflow for testing against multiple Ruby versions and mail dependencies

The test.yml workflow exists but likely has limited configuration. The mail gem needs to support multiple Ruby versions (2.7+) and compatibility with different versions of dependencies like mail parsers. Adding a matrix build would catch version-specific bugs early and provide confidence in backwards compatibility.

• [ ] Review existing .github/workflows/test.yml and identify current Ruby version coverage
• [ ] Extend test.yml to use matrix strategy testing Ruby 2.7, 3.0, 3.1, 3.2, 3.3, and head
• [ ] Add separate workflow for testing against optional dependencies (different mime-types versions if applicable)
• [ ] Add workflow step to test gemspec validation (bundle exec gem build)
• [ ] Document minimum supported Ruby version in README.md if not already present

• Add comprehensive specs for lib/mail/elements/address_list.rb—currently parsing multiple addresses but test coverage appears sparse for edge cases (malformed commas, quoted local-parts)
• Document the Ragel-generated parser behavior in lib/mail/elements/ with code comments—contributors struggle to understand how Ragel grammar maps to Ruby method calls
• Add example in README or doc/ for handling S/MIME signed and encrypted emails—Mail parses them but no guidance on extracting/verifying signatures

• High · Potential Email Header Injection — lib/mail/fields/, lib/mail/header.rb, lib/mail/field.rb. Mail library handles email headers from user input. The file structure shows extensive field parsing (lib/mail/fields/) and header handling (lib/mail/header.rb). Email header injection attacks could allow attackers to inject arbitrary headers (e.g., BCC, CC) or manipulate message content by injecting newline characters into headers, potentially leading to spam distribution or phishing attacks. Fix: Implement strict input validation and sanitization for all email headers. Reject or escape newline characters (\r, \n) in header values. Use parameterized/structured header APIs and validate header names against a whitelist of allowed headers.
• High · Email Body Injection Risk — lib/mail/body.rb, lib/mail/encodings/. The library processes email bodies (lib/mail/body.rb) with multiple encoding handlers (lib/mail/encodings/). If user-controlled content is passed directly to email bodies without proper escaping, attackers could inject malicious content, executable scripts in HTML emails, or exploit encoding-based attacks. Fix: Implement content sanitization based on the email MIME type. For HTML emails, use a robust HTML sanitization library. Ensure proper encoding handling and validate MIME types. Consider disabling dangerous content types by default.
• High · Unrestricted File Attachments — lib/mail/attachments_list.rb. The attachments handling system (lib/mail/attachments_list.rb) may allow arbitrary file attachments without sufficient validation. This could enable arbitrary file upload attacks, path traversal, or distribution of malicious files. Fix: Implement strict attachment validation including: file type whitelisting, file size limits, filename sanitization to prevent path traversal, and scanning for malicious content. Disable execution permissions on stored attachments.
• Medium · Potential Regex Denial of Service (ReDoS) — lib/mail/elements/address.rb, lib/mail/elements/address_list.rb, lib/mail/fields/. Mail parsing libraries commonly use complex regex patterns for parsing email addresses, headers, and MIME types (visible in lib/mail/elements/ and lib/mail/fields/). Without careful implementation, these could be vulnerable to ReDoS attacks where specially crafted input causes excessive backtracking. Fix: Audit all regular expressions for catastrophic backtracking patterns. Use regex analysis tools. Consider switching from regex to proper RFC 5322 parser libraries. Implement input length limits and timeouts on parsing operations.
• Medium · Charset/Encoding Handling Vulnerabilities — lib/mail/multibyte/, lib/mail/encodings/. The library includes multibyte character handling (lib/mail/multibyte/) and multiple encoding schemes (lib/mail/encodings/). Improper handling of character encodings could lead to encoding-based injection attacks, bypass of validation filters, or information disclosure. Fix: Validate and normalize all character encodings early in processing. Use safe encoding libraries. Test against known encoding attack vectors. Implement strict encoding declarations and reject ambiguous encodings.
• Medium · Missing Dependency Validation — Gemfile. The Gemfile content was not provided for analysis. Without visibility into dependencies, potential vulnerabilities in third-party gems used by this mail library cannot be assessed. Outdated or compromised dependencies could introduce security risks. Fix: Regularly run 'bundle audit' or 'bundler-audit' to check for known vulnerabilities. Keep dependencies updated. Consider using tools like Dependabot for automated dependency monitoring. Document minimum version requirements for security-critical dependencies.
• Low · Potential Information Disclosure through Error Messages — lib/mail/. The library's error handling and exception messages could potentially leak sensitive information about email structure, system paths, or internal implementation details to attackers. Fix: Implement generic error messages for user-facing interfaces. Log detailed errors securely server-side only. Avoid exposing stack traces or implementation details in production error responses.
• Low · Network Security Configuration — undefined. The library interfaces with network delivery methods (lib/mail/network/delivery_methods) for SMTP/POP3 connections. Configuration files or environment-based settings may not enforce secure defaults (TLS/SSL verification). Fix: undefined

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.