2.0.0

ErmesMail 2.0.0 — Release Notes

Date: 2025-09-08

Full Changelog: 1.1.0...2.0.0

Summary

Version: 2.0.0

Major release containing breaking API changes, STARTTLS support, improved testability and CI updates. This file documents the highlights, breaking changes, migration steps, files changed, and verification notes since 1.1.0.

Highlights

• STARTTLS support (opportunistic and required).
• Explicit SMTPConfig.SecurityMode and expressive factory methods to replace boolean-heavy constructors.
• SSL (implicit TLS) and STARTTLS are mutually exclusive by design.
• Improved testability: HtmlEmailFactory + dependency injection for SendEmailTask.
• Consolidated integration tests into IntegrationScenariosIT with conditional execution (Mailpit probe + external provider support).
• CI updated to support Mockito inline mock-maker (ByteBuddy agent) and adjusted test argLine.
• Updated documentation (README.md) and added smtp-integration.properties.example.
• Deprecated individual integration tests removed.

Breaking changes

• The boolean-heavy SMTPConfig constructors have been removed. Code using constructors like:

// removed in 2.0
new SMTPConfig("host", 25, "user", "pass", false /*ssl*/);

must be migrated to the explicit factory methods:

SMTPConfig.forPlain("host", 25, "user", "pass");
SMTPConfig.forSsl("smtp.example.com", 465, "user", "pass", 465);
SMTPConfig.forStartTlsOptional("smtp.example.com", 587, "user", "pass");
SMTPConfig.forStartTlsRequired("smtp.example.com", 587, "user", "pass");

Because the public API changed, callers must be recompiled against 2.0.0.

Migration guide (quick)

1. Replace old SMTPConfig(...) constructor invocations with the appropriate SMTPConfig.for* factory method above.
2. If your tests instantiate SendEmailTask directly, prefer injecting a HtmlEmailFactory or use DefaultHtmlEmailFactory.
3. If your CI uses Mockito inline mock-maker, ensure the ByteBuddy agent is available and test argLine includes it (see pom.xml and .github/workflows/ci.yml).

CLI changes

• New flags:
  • --starttls — enable opportunistic STARTTLS
  • --starttls-required — require STARTTLS
  • --sslon — implicit SSL (SMTPS) (mutually exclusive with STARTTLS flags)

Example (plain SMTP local test):

java -jar target/ermes-mail.jar -h localhost -p 1025 -f [email protected] -s "subj" -b "html body" --to [email protected]

Files changed / added (overview)

• Core/API

  • src/main/java/com/softinstigate/ermes/mail/SMTPConfig.java — added SecurityMode + factory methods
  • src/main/java/com/softinstigate/ermes/mail/SendEmailTask.java — STARTTLS/SSL configuration and HtmlEmailFactory injection
  • src/main/java/com/softinstigate/ermes/mail/HtmlEmailFactory.java (new)
  • src/main/java/com/softinstigate/ermes/mail/DefaultHtmlEmailFactory.java (new)
  • src/main/java/com/softinstigate/ermes/mail/Main.java — CLI flags & validation

• Tests

  • src/test/java/.../SMTPConfigTest.java (new)
  • src/test/java/.../MainCliTest.java (new)
  • src/test/java/.../SendEmailTaskTest.java (new)
  • src/test/java/.../IntegrationScenariosIT.java (new, canonical IT)
  • Deprecated individual IT files removed

• Build & CI

  • pom.xml — version bumped to 2.0.0-SNAPSHOT; Mockito/ByteBuddy and test argLine adjustments
  • .github/workflows/ci.yml — ByteBuddy provisioning & argLine usage

• Docs & examples

  • README.md updated with CLI flags, migration note and integration test instructions
  • smtp-integration.properties.example added

Tests & CI

• Unit tests: JUnit 5 + Mockito (inline mock-maker).
• Integration tests (conditional):
  • local-plain-mailpit — probes localhost:1025 and skips when Mailpit not reachable.
  • external-smtps-conditional — runs only when env vars or smtp-integration.properties present.
• CI updated to ensure the ByteBuddy agent is available for inline mocking and to pass the agent via argLine to surefire/failsafe.

Security & credentials

• Do not commit credentials. Use a git-ignored smtp-integration.properties or environment variables with these keys:
  • SMTP_INTEGRATION_HOST
  • SMTP_INTEGRATION_PORT
  • SMTP_INTEGRATION_USERNAME
  • SMTP_INTEGRATION_PASSWORD
  • SMTP_INTEGRATION_SENDER
  • SMTP_INTEGRATION_RECIPIENT
  • SMTP_INTEGRATION_SSLPORT (optional)

Enable JavaMail debug for troubleshooting with:

mvn -Dmail.debug=true -DfailIfNoTests=false verify

Verification performed (dev)

• Unit tests added and executed locally during development.
• Integration tests executed conditionally; external SMTPS scenario was verified with -Dmail.debug=true to confirm TLS handshake evidence.