Document: 21-email-architecture.md
Version: 1.0.0

Purpose

This document defines the email architecture and communication standards used across all Rundown projects.

Email is a core communication channel for many applications. It is responsible for delivering transactional and operational messages to users, clients, and administrators in a reliable and maintainable manner.

This document establishes how email functionality should be designed, integrated, and maintained.

Email Philosophy

Email should be treated as an infrastructure service rather than application logic.

The application determines what message should be sent.

The email provider determines how that message is delivered.

This separation reduces coupling and allows providers to be replaced without affecting business logic.

Standard Email Provider

Rundown standardizes on:

Resend

Reasons include:

• Modern API

• Excellent developer experience

• Strong React Email support

• Reliable deliverability

• Simple integration

Alternative providers may be introduced only when project requirements justify them.

Responsibilities

The email layer owns:

• Message delivery

• Template rendering

• Provider communication

• Delivery status

• Retry handling (where applicable)

Non-Responsibilities

The email layer should not own:

• Business rules

• User authentication

• Form validation

• Frontend presentation

• Database operations

Email communicates outcomes; it should not decide application behaviour.

Email Categories

Transactional Emails

Examples:

• Password reset

• Email verification

• Order confirmation

• Invoice delivery

• Account creation

• Shipping updates

Transactional emails are triggered by user actions or business events.

Operational Emails

Examples:

• Contact form notifications

• Internal alerts

• Error notifications

• System reports

Operational emails are intended for administrators or internal users.

Marketing Emails

Examples:

• Newsletters

• Promotions

• Product launches

• Announcements

Marketing emails should remain separate from transactional communication and comply with applicable consent requirements.

Email Templates

All email templates should be:

• Reusable

• Version controlled

• Responsive

• Accessible

• Branded consistently

Rundown standardizes on:

React Email

Templates should remain independent of provider-specific implementation details.

Triggering Emails

Emails should be triggered by business events.

Examples:

• Order placed

• Contact form submitted

• User registered

• Password reset requested

Business logic determines when an email should be sent.

The email layer is responsible only for delivery.

Queueing

Projects with high email volume should introduce background processing or queues.

Examples:

• Bulk newsletters

• Import notifications

• Large transactional workloads

Small projects may send emails synchronously when appropriate.

Delivery Reliability

Applications should:

• Handle provider failures gracefully.

• Retry failed deliveries when appropriate.

• Log delivery attempts.

• Avoid duplicate messages.

Email delivery should never interrupt critical business workflows unless the email itself is essential to the workflow.

Security

Email systems should:

• Protect API credentials.

• Validate recipient addresses.

• Prevent header injection.

• Limit abuse of public forms.

• Avoid exposing sensitive information in messages.

Environment variables should be used for all provider credentials.

Monitoring

Monitor:

• Delivery success

• Bounce rates

• Failed sends

• Spam complaints (where applicable)

Monitoring helps identify delivery issues before they affect users.

Engineering Decision

Email Provider Strategy

Status: Accepted

Decision

Rundown standardizes on Resend with React Email for all production email functionality.

Reasoning

This combination provides:

• Excellent developer experience.

• Reusable component-based templates.

• Reliable delivery.

• Simple integration with the Rundown technology stack.

Business logic remains provider-independent, allowing future migration if required.

Email Checklist

Before implementing email functionality, verify:

• Does the application require email?

• Is the correct email category identified?

• Are templates reusable?

• Are provider credentials secured?

• Are failures handled gracefully?

• Are emails triggered by business events?

• Is monitoring configured where appropriate?

Summary

The email architecture provides reliable communication between the application and its users.

By separating business events from message delivery, Rundown applications remain modular, maintainable, and flexible while ensuring a consistent communication experience.

Related Documents

• 12-system-architecture.md

• 13-architecture-boundaries.md

• 18-authentication-authorization.md

• 19-api-architecture.md

Related ADRs

• ADR-001: Repository Structure