ankane/ahoy_email
52.2
Adequate · 6 November 2026
766
lines of production code
Ruby
primary language
4
measurements over time
What this system is
This system is a Ruby gem for tracking email engagement, specifically monitoring message opens and link clicks. It provides a secure, modular architecture that records these events to databases or Redis, supporting both ActiveRecord and Mongoid backends. The library handles URL signature verification to prevent open redirects and allows for customizable UTM parameter tracking and message history storage.
How it got here
2014 — AhoyEmail v4.0.0 architectural rewrite
8 changes.
This period marked the release of AhoyEmail v4.0.0, featuring a major architectural overhaul from an interceptor-based system to a modular, subscriber-based design. The update introduced robust email click and open tracking with HMAC-SHA256 security, replaced legacy generators with manual migration requirements, and raised minimum Ruby and Rails version constraints.
2015–2018 — test infrastructure and coverage expansion
4 changes.
This period focused on establishing a robust testing foundation by adding comprehensive unit and integration tests for email tracking, click analytics, and UTM parameter handling. The work included setting up internal test infrastructure with SQLite and Mongoid support, along with creating test fixtures and mailer classes to validate core library functionality and edge cases.
2021–2022 — Mongoid and encryption support
4 changes.
This period focused on expanding Ahoy's generator capabilities to support Mongoid as an alternative data store alongside Active Record. It also introduced experimental encryption support for message tracking and added CI infrastructure to test compatibility with Rails 8.0 and newer Mongoid versions.
Features
Added generators for Ahoy clicks tracking with ActiveRecord and Mongoid support
Users can now generate the database schema and models for Ahoy clicks tracking. For ActiveRecord applications, a new migration is created that defines the \ahoy\_clicks\ table (including campaign and token fields) and adds a campaign index to the \ahoy\_messages\ table; this migration respects the application's configured primary key type. For Mongoid applications, a new \Ahoy::Click\ model is generated with fields for campaign and token and an index on the campaign field.
lib/generators/ahoy/clicks · high confidence
Removals
Removed legacy install generator for Ahoy Email
The \InstallGenerator\ class, which previously handled the creation of the \create\_ahoy\_messages\ migration file, has been removed from the codebase. This change eliminates the legacy generator mechanism, meaning users can no longer rely on this specific generator to scaffold the initial database migration for Ahoy Email.
_lib/generators/ahoy\email · high confidence
Behavioural changes
Added Click model and updated Message model for email tracking
A new Ahoy::Click model has been introduced to track email clicks, mapping to the 'ahoy\_clicks' database table. The existing Ahoy::Message model has been updated to explicitly set its table name to 'ahoy\_messages' and now includes an optional, polymorphic belongs\_to association with the User model, allowing messages to be linked to various user types without requiring a user record.
app/models · high confidence
AhoyEmail v4.0.0: Major rewrite with new tracking architecture and HMAC-SHA256 security
This release introduces a complete architectural overhaul of the email tracking system. The legacy \Interceptor\ has been removed and replaced with a new \Mailer\ concern that uses \after\_action\ callbacks to process emails, allowing for more granular control via \has\_history\, \utm\_params\, and \track\_clicks\ class methods. Tracking is now handled by dedicated subscribers (\DatabaseSubscriber\, \RedisSubscriber\, \MessageSubscriber\) that decouple storage logic, supporting both ActiveRecord and Mongoid. Security has been strengthened by transitioning to HMAC-SHA256 for link signatures, removing support for legacy secret token generation, and enforcing strict keyword validation for options. The processor now defaults to HTML5 parsing when available and only tracks absolute HTTP/HTTPS links, while UTM parameters are stored on the message model rather than being included in links by default.
_lib/ahoy\email · high confidence
Configurable API mode and new click tracking routes
The engine's routing is now conditional: the main mount point at /ahoy is only active when the new AhoyEmail.api configuration option is enabled, allowing users to disable the API entirely. Additionally, the engine now exposes a dedicated /ahoy/click route for tracking email clicks, while retaining legacy /ahoy/messages/:id/open and /ahoy/messages/:id/click routes for backward compatibility.
config · high confidence
Enhanced email click tracking with signature verification and open redirect protection
The MessagesController now implements a robust \click\ action that verifies URL signatures using HMAC to prevent open redirects, falling back to a configurable invalid redirect URL or a 404 error if verification fails. It supports both legacy and new parameter formats for tracking clicks, publishes click events to subscribers, and skips unnecessary application controller filters to ensure reliable tracking. The \open\ action has been updated to serve a transparent GIF for open tracking instead of logging to stdout.
app/controllers · high confidence
Major architectural overhaul of email tracking and configuration
The library has been refactored from a simple interceptor-based approach to a modular, subscriber-based architecture. This change replaces the previous \AhoyEmail::Interceptor\ with new \Observer\, \Processor\, and \Tracker\ components, allowing for more flexible event handling via \database\_subscriber\, \message\_subscriber\, and \redis\_subscriber\. Configuration is now centralized in \AhoyEmail\ with explicit accessors for \secret\_token\, \default\_options\, \subscribers\, and \track\_method\, enabling users to customize UTM parameters, click analytics, and message history storage more granularly. The dependency list has also expanded to include \nokogiri\, \addressable\, and \safely\, reflecting the new parsing and error-handling capabilities.
lib · high confidence
Removed default email tracking migration template
The default installation migration template for the \ahoy\_messages\ table has been removed from the generator. This means that running the installer will no longer automatically create the database schema for tracking email metrics such as opens, clicks, and content, requiring users to manually define or opt-in to this tracking structure if needed.
_lib/generators/ahoy\email/templates · high confidence
Support for Mongoid and Active Record encryption in Ahoy generators
The Ahoy installation generators for clicks and messages now support Mongoid as an alternative data store alongside Active Record. When both libraries are present, users are prompted to choose between Active Record (default) and Mongoid. Additionally, the messages generator includes experimental support for Active Record encryption via a new \--encryption\ option, while retaining the deprecated \--unencrypted\ flag for backward compatibility.
lib/generators/ahoy · high confidence
Updated message model generator with encryption options and primary key support
The generator for the Ahoy::Message model now supports explicit encryption configuration via the --encryption flag, allowing users to choose between Lockbox, Active Record encryption, or no encryption. For Active Record, the generated migration and model templates now respect the application's primary\_key\_type configuration and handle MySQL-specific string length limits. The generator also adapts to Lockbox 1.0 syntax (using has\_encrypted instead of encrypts) and provides corresponding encrypted field structures for both Active Record and Mongoid backends.
lib/generators/ahoy/messages · high confidence
Test coverage
Added Mongoid test support files; Added comprehensive test suite for email tracking and analytics; Added internal test infrastructure for database schema and configuration; Added test fixtures for mailer tracking and history features.
Dependencies
Added CI gemfiles for Rails 8.0 and Mongoid 8/9
New gemfiles have been added to the gemfiles directory to enable continuous integration testing against Rails 8.0.0 (via actionmailer80.gemfile) and Mongoid 8 and 9 (via mongoid8.gemfile and mongoid9.gemfile). These files define the specific dependency constraints required to verify compatibility with these newer versions of Rails and Mongoid.
gemfiles · high confidence
Updated dependencies and raised minimum Ruby/Rails versions
The gem now requires Ruby 3.3 or higher and depends on Action Mailer 7.2 or newer, dropping support for older versions. Development dependencies have been explicitly added to the Gemfile (including Rake, Minitest, Action Mailer 8.1, ActiveRecord 8.1, Combustion, SQLite3, and Redis) to streamline local testing and CI, while the gemspec itself now lists specific runtime dependencies for Addressable, Nokogiri, and Safely Block.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 52 → 52 (-0.3)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 61 → 61 (+0.0)
- Architecture 69 → 69 (+0.0)
- Maturity 54 → 54 (+0.0)
- Readiness 72 → 71 (-1.1)
- Security 42 → 41 (-0.6)
- Domain Modelling 100 → 100 (+0.0)
Resolved (5)
- Duplicate campaigns method across Database and Redis subscribers. Similar to stats, this indicates a fragmented API for retrieving campaign data without a shared abstraction.
- Duplicate stats method across Database and Redis subscribers with identical signatures. This redundancy suggests a lack of a unified statistics interface, making it difficult to swap backends without checking for method existence.
- Duplicate intent across subscriber implementations with identical signatures but different storage backends. While technically distinct implementations, the API surface exposes redundant method names for the exact same semantic action (tracking a send event) across different storage adapters without a shared interface or base class hinting at this polymorphism.
- Three different subscriber classes expose track_click with identical signatures. This creates a fragmented API where the same operation is available on multiple distinct types without a clear hierarchy or shared interface, leading to potential confusion about which subscriber to use in different contexts.
- Two different generator classes (for Clicks and Messages) both expose copy_migration with identical signatures. While the domains are distinct, the method name is generic and could be confusing if the generators were ever used interchangeably or if the method behavior differs subtly between domains.
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
ankane/ahoy_email was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit d5c36723eaef5c75c926815b22f1e27c5a25121a — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.