v1.4.3These docs are for laramail v1.4.3. View changelog

Changelog

All notable changes to laramail are documented here.

v1.4.3

Testing subpath + docs — laramail/testing subpath export and assertion reference tables.

laramail/testing subpath — import MailFake and AssertableMessage from laramail/testing to keep fake mode out of production bundles. Works with all TypeScript moduleResolution settings (node, NodeNext, bundler).
Testing docs — added "Why Mail.fake() over vi.fn()" comparison, subpath import guide, and staging redirect note.
README assertion tables — replaced inline list with quick-reference tables for all assertion methods and AssertableMessage helpers.

Badge fixes + npm discoverability.

Fixed README badge URLs pointing to old domain.
Trimmed comparison table to 8 defensible rows.
Added npm keywords: email-testing, mail-testing, nodemailer-mock, fake-mailer, test-email.

Positioning pivot — Mail.fake() is the headline.

README hero repositioned around Mail.fake() + zero-setup email testing. New one-line pitch: "AdonisJS mailer, but framework-agnostic."
npm description updated to lead with Mail.fake() + Mail.assertSent().
No API changes. No new features. Just the right story in the right place.

Quality & Safety — typed errors, comprehensive test coverage, SMTP pooling.

Error Handling — ConfigurationError, ValidationError, ProviderError, and AllProvidersFailedError replace generic Error throws across all source files. Use instanceof for granular error handling.
SMTP Connection Pooling — pool, maxConnections, maxMessages options in SMTP provider config.
CLI Command Tests — 65 new tests covering all 8 CLI commands.
Provider Tests — 24 new tests for SendGrid and SES providers.
Error Class Tests — 37 tests for typed error hierarchy and integration.
129 new tests (774 total across 51 suites)

Developer Experience — 3 new features for better development and staging workflows.

Log Transport — LogProvider prints formatted email details to console instead of sending. Warns if used in production. No SMTP or API keys needed for local development.
Custom Providers — Mail.extend(driver, factory) registers custom mail providers. Custom providers are checked before built-in drivers, allowing overrides and third-party integrations.
Always-To Redirect — Mail.alwaysTo(address) redirects all emails to a single address, clearing CC/BCC. Perfect for staging environments. Also applies to preview(). Skipped in fake mode.
35 new tests (645 total)

Package renamed to laramail

Postinstall thank-you message

Initial postinstall script

CLI fix

Fixed queue:clear CLI command to use --status/-s option instead of positional argument
CLI now matches documented usage: npx laramail queue:clear --status failed

Queue compatibility fix

queue: Replace colon with underscore in queue names for BullMQ compatibility
- BullMQ does not allow colons (:) in queue names
- Queue names now formatted as laramail_mail instead of laramail:mail

Bug fixes and test improvements

Type handling and error management in preview and queue commands
Improved async/sync handling in image embedding and priority tests
Added comprehensive test coverage for MailFacade, MailManager, Mailable, and QueueManager

CLI Commands — powerful command-line tools for managing your email workflow.

CLI Commands — New CLI tool with queue management, email preview, code generation, and configuration validation.
- queue:work — Start processing queued emails
- queue:status — Show queue job counts and status
- queue:clear — Clear jobs from the queue by status
- queue:retry — Retry failed jobs in the queue
- preview — Preview an email in your browser without sending
- send:test — Send a test email to verify configuration
- make:mailable — Generate a new Mailable class
- config:check — Validate your mail configuration

5 new features expanding the library's email capabilities.

Email Events — Listen to sending, sent, and failed lifecycle events with typed listeners.
Email Preview — Render emails in the browser during development without actually sending them.
Email Priority — Set priority headers (high, normal, low) on outgoing messages.
Embedded Images — Attach inline images via CID references for rich HTML emails.
Rate Limiting — Throttle outgoing email with per-provider rate limits and configurable strategies.

Provider Failover — automatic failover chains with retries, delays, and callbacks.

FailoverManager class for managing provider chains
failover config option (global and per-mailer)
onFailover callback for monitoring provider switches
MailResponse now includes provider, failoverUsed, failoverAttempts
Testing utilities: MailFake.simulateFailures() / resetFailures()
AssertableMessage failover methods: wasFailoverUsed(), getProvider(), getFailoverAttempts(), getResponse()

See the Provider Failover docs and Migration Guide for adoption details.

Version	Key Feature
v0.7.0	Markdown Mail — renderer, components, themes
v0.6.0	Queue support — Bull, BullMQ, sync driver
v0.5.0	Testing utilities — `Mail.fake()`, assertions, `AssertableMessage`
v0.4.0	Template engines — Handlebars, EJS, Pug + Mailable classes