v0.4.0 — link / small / attach / inline_image / info_row + RFC 8058 unsubscribe + Minitest 6 + plaintext fixes

[rameerez]

Summary

This PR is the v0.4.0 Goodmail DX, correctness, deliverability, and Rails integration release.

The end-state is deliberately small for users: in a Rails mailer, keep your normal Action Mailer headers and write one Goodmail block:

goodmail_mail(headers_for(:confirmation_instructions, opts), locale: record.locale) do
  text "Confirm your account below."
  button "Confirm my account", confirmation_url(record, confirmation_token: token)
  sign
end

Goodmail now owns the mechanical work users should not have to do: render config scoping, mailer context, plaintext generation, CSS inlining, attachment fan-out, inline CID pinning, Action Mailer header filtering, multipart assembly, and RFC 8058 unsubscribe headers.

The final cleanup also removes duplicated internal work: Goodmail.compose now calls Goodmail.render once, then passes already inlined HTML, cleaned plaintext, and attachment descriptors into Goodmail's internal Action Mailer action. The internal mailer no longer runs its own second Premailer/plaintext pipeline.

Why this exists

The downstream trigger was production-style email work in real Rails applications and app templates: plaintext artifacts, inline image/CID issues, unsubscribe header correctness, attachment behavior, and repeated app-level glue in Pay, Devise, and custom mailers.

The conclusion from the audit is that this belongs in Goodmail. Host apps should write product-specific copy and pass their native Action Mailer headers; they should not manually bridge Goodmail.render into mail, copy ivars, pin CIDs, strip render-only keys, or rebuild multipart trees.

Major changes

Action Mailer-native integration

• Adds private helpers auto-installed on ActionMailer::Base:
  • goodmail_mail(...) { ... }
  • goodmail_render_parts(...) { ... }
  • goodmail_mail_parts(parts, headers, unsubscribe_url:)
• Helpers stay private so Rails does not expose them as deliverable mailer actions.
• DSL blocks keep normal mailer context: mailer ivars and private helper methods remain available.
• locale: wraps the DSL render in I18n.with_locale.
• Attachments are applied before mail, then Action Mailer's documented block form builds text/html responses.
• Goodmail forwards Action Mailer's normal header surface (date:, return_path:, delivery options, custom "X-..." headers, etc.) and strips only Goodmail render-only keys (preheader:, unsubscribe_url:, locale:, context:, config:, configuration:, layout_path:).
• layout_path: works through Goodmail.compose, Goodmail.render, and the Action Mailer helpers without leaking as a mail header.

Single render pipeline

• Goodmail.render is now the single source of truth for DSL evaluation, layout rendering, Premailer CSS inlining, plaintext cleanup, and attachment descriptor collection.
• Goodmail.compose renders once, then passes rendered strings and attachment descriptors to Goodmail::Mailer.compose_message.
• Goodmail::Mailer now only does the Action Mailer handoff: unsubscribe headers, attachment application, and block-form mail.
• This removes the old duplicate Premailer/plaintext path and avoids drift between render and compose.

New DSL helpers

• link(text, url)
• small(text)
• info_row(label, value)
• attach(filename, content, mime_type:, inline:)
• inline_image(filename, content, alt:, width:, height:, mime_type:)

Attachments and inline images

• EmailParts carries attachments descriptors.
• attach accepts raw bytes or a filesystem path.
• Binary strings containing NUL bytes no longer crash path detection.
• Inline image Content-IDs are generated as RFC 2392-shaped IDs using a reserved .invalid domain, then pinned onto the actual Mail part.
• Duplicate inline filenames raise Goodmail::Error early because Action Mailer's attachment hash is keyed by filename in custom render fan-out paths.
• Non-inline duplicate filenames remain allowed.

Deliverability

• Adds RFC 8058-compatible one-click unsubscribe support:
  • List-Unsubscribe: <https://...>
  • List-Unsubscribe-Post: List-Unsubscribe=One-Click
• One-click POST is emitted only for HTTPS URLs.
• Non-HTTPS values still get classic List-Unsubscribe without falsely advertising one-click support.
• README documents that the final sender/provider must DKIM-sign these headers.

Sources:

• RFC 8058 Section 3.1: https://www.rfc-editor.org/rfc/rfc8058#section-3.1
• Gmail sender guidelines: https://support.google.com/mail/answer/81126
• Yahoo sender best practices: https://senders.yahooinc.com/best-practices/

Plaintext, Encoding, and Rendering Fixes

• Hidden preheaders no longer leak into plaintext.
• Outlook MSO/VML button labels no longer duplicate in plaintext.
• Standalone company-name image alt lines no longer leak into plaintext.
• info_row renders as Label: Value in plaintext while preserving table layout in HTML.
• UTF-8 / accented characters / emoji survive HTML and plaintext generation by pinning Premailer input encoding to UTF-8.
• Button labels preserve caller casing instead of forcing capitalization.

Per-Render Config and Downstream DX

• Goodmail.compose, Goodmail.render, goodmail_mail, and goodmail_render_parts accept config: / configuration: for tenant/product-specific branding.
• Overrides are scoped via Goodmail.with_config; apps do not need to mutate global Goodmail.config around a delivery.
• Devise and Pay-style mailers can pass their native header hashes directly to goodmail_mail(...).
• Downstream apps no longer need app-level goodmail_render wrappers or manual Goodmail.render(..., context: self) glue.

Action Mailer Source Audit

I cloned Rails to /tmp/rails and audited the Action Mailer README plus every file under actionmailer/lib/**/*.rb at Rails commit debbd18c562df17d01944c475e9291d927910b58.

Key Rails contracts Goodmail now follows:

• Mailer actions assign ivars and call mail; templates/actions read that state: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/README.rdoc#L20-L37
• Public methods become mailer actions through action_methods; Goodmail helpers stay private: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/base.rb#L614-L618
• Attachments must be added before mail; late writes raise: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/base.rb#L766-L781
• mail owns defaults, delivery behavior, response collection, MIME assembly, inline wrapping, content type, and sort order: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/base.rb#L875-L907
• Rails assigns arbitrary message headers while excluding only framework render keys: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/base.rb#L972-L976
• Block-form mail uses ActionMailer::Collector response bodies: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/collector.rb#L25-L29
• Inline and regular attachments are assembled by Action Mailer, including related/mixed nesting: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/base.rb#L1024-L1042
• ActionMailer::MessageDelivery lazily processes mailer actions: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/message_delivery.rb#L22-L35
• deliver_later serializes only mailer action arguments: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/message_delivery.rb#L142-L155
• Delivery jobs replay the mailer class/action/args: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/mail_delivery_job.rb#L21-L28
• Rails preview CID lookup matches cid: URLs against attachment CIDs: https://github.com/rails/rails/blob/debbd18c562df17d01944c475e9291d927910b58/actionmailer/lib/action_mailer/inline_preview_interceptor.rb#L33-L57

Inline implementation comments reference the exact Rails source locations where the contract matters.

Backward Compatibility

• Existing Goodmail.compose callers keep working.
• Existing Goodmail.render callers keep working; EmailParts#attachments defaults to [].
• goodmail_mail_parts tolerates legacy parts objects without attachments.
• Apps do not need per-class include Goodmail::ActionMailerIntegration; helpers are installed once on ActionMailer::Base.
• Important caveat: Goodmail.compose evaluates the Ruby DSL block before returning ActionMailer::MessageDelivery, because Ruby blocks are not Active Job-serializable. For fully native Action Mailer lazy action execution in host apps, use goodmail_mail / goodmail_render_parts inside real mailer actions.

Downstream Verification

Verified with the local gem path in three downstream Rails codebases:

• a production-style Rails application with a broad transactional mailer surface
• a Rails application template
• a tenant/product-branded Rails application

Results:

• Production-style app full suite: 893 runs, 5126 assertions, 0 failures
• Production-style app Goodmail/mail preview lint: 15 files inspected, no offenses detected
• Production-style app Mailcatcher delivery readback:
  • Preview runner delivered 15 fresh Goodmail messages, IDs 332-346.
  • All had nonblank plaintext and HTML.
  • No Goodmail render-only header leaks.
  • Inline image emails delivered valid PNG CID attachments.
  • Latest inline image attachment endpoints returned 200 OK, valid image/png, 1280 x 720, 152972 bytes.
  • A separate regular attach smoke email delivered goodmail-smoke.txt as multipart/mixed; Mailcatcher returned 200 OK, correct filename/content-disposition, and exact attachment body.
  • No private external asset/API URLs leaked in message sources.
• Rails app template full suite: 46 runs, 289 assertions, 0 failures
• Rails app template Goodmail mailer lint: 7 files inspected, no offenses detected
• Tenant/product-branded app full suite: 227 runs, 1064 assertions, 0 failures
• Tenant/product-branded app Goodmail mailer lint: 11 files inspected, no offenses detected

Known unrelated downstream output:

• Two downstream Rails apps emit Rails 8.2 route deprecation warnings from config/routes.rb:2.
• One development environment only includes List-Unsubscribe when an unsubscribe URL is configured.

Test Plan

• bundle exec rake test - 253 tests, 913 assertions, 0 failures, 0 errors, 0 skips
• COVERAGE=1 bundle exec rake test - 100.0% line coverage, 87.96% branch coverage
• bundle exec rubocop - 15 files inspected, no offenses detected
• bundle exec rake build - goodmail 0.4.0 built to pkg/goodmail-0.4.0.gem
• git diff --check && git diff --cached --check
• Production-style downstream app full suite
• Production-style downstream app Mailcatcher plaintext/html/header/inline-attachment/readback verification
• Rails app template full suite
• Tenant/product-branded downstream app full suite

Release State

Current pushed head: 19da4a76aa2d18d467e83a7720a62a0f970a138e (Use generic OSS references).

This PR is production-release-ready from the gem audit, Rails Action Mailer source audit, downstream app suites, and Mailcatcher delivery verification. After merge, remaining maintainer steps are tagging v0.4.0 and pushing the built gem.