Transactional Email (@wrelik/email)
Relevant source files
The following files were used as context for generating this wiki page:
The @wrelik/email package serves as the standardized adapter for transactional email services within the Wrelik ecosystem. It provides a vendor-agnostic interface that wraps the Resend SDK, ensuring that application-level code does not interact with third-party providers directly. This architecture supports the core principle of reducing vendor lock-in and enforcing best practices across all Wrelik applications.
Sources: README.md:12-18, DECISIONS.md:14-16, packages/email/src/index.ts:1-7
Architecture and Integration
The package follows an "adapter-first" architecture. It abstracts the underlying Resend service, providing a simplified API for sending emails and managing templates. To prevent direct vendor usage, the project's ESLint configuration explicitly forbids importing directly from the resend package in application code, mandating the use of @wrelik/email instead.
Sources: README.md:23-31, packages/eslint-config/index.js:23-26
Initialization Flow
Before sending emails, the module must be initialized with an API key and a default "from" address. This sets up a singleton Resend client used for all subsequent calls.
A flowchart showing the initialization process of the email client.
Sources: packages/email/src/index.ts:7-11
Core Functionality
The package provides two primary methods for sending communications: direct email transmission and template-based dispatch.
Email Transmission
The sendEmail function is the primary low-level interface. It handles merging provided options with the default configuration (such as the sender address).
| Parameter | Type | Description |
|---|---|---|
to | string | string[] | Recipient email address(es). |
subject | string | The subject line of the email. |
html | string (Optional) | HTML content of the email. |
text | string (Optional) | Plain text content of the email. |
from | string (Optional) | Overrides the default sender address. |
tags | Array<{name, value}> | Custom metadata tags for tracking. |
Sources: packages/email/src/index.ts:18-35
Template Registry
The package includes a Template Registry that allows developers to define type-safe renderers for emails. This separates the data logic from the presentation layer.
A sequence diagram illustrating how templates are defined and subsequently dispatched.
Sources: packages/email/src/index.ts:40-62
Error Handling
The package integrates with @wrelik/errors to provide consistent error reporting. If a template is requested that does not exist in the registry, the package throws a ValidationError. Errors encountered during the transmission process via the Resend client are caught and re-thrown with descriptive failure messages.
Sources: packages/email/src/index.ts:2, 33-35, 54-56
Configuration and Dependencies
The package is built using tsup and supports both CommonJS and ESM formats.
| Dependency | Purpose |
|---|---|
resend | Underlying vendor SDK for email delivery. |
@wrelik/errors | Internal workspace dependency for standard error types. |
vitest | Used for running the test suite. |
Sources: packages/email/package.json:16-25
Conclusion
The @wrelik/email package is a critical infrastructure component that standardizes how Wrelik applications communicate with users. By wrapping Resend and providing a centralized template registry, it ensures that transactional emails are sent reliably while maintaining a clean boundary between application business logic and third-party delivery services.
Sources: README.md:37-40, DECISIONS.md:20-24