University of Peradeniya crestSCS Documentation
University of Peradeniya crestSCS Documentation
Department website

Start here

Repository handbookRepository overviewDevelopment

System design

ArchitectureAuthentication and authorizationPublic dataAPI contractsSchemas
UI system

Applications

Department Web applicationPeople applicationProjects applicationPortal application

Services

API serviceGitHub App serviceMailer service
Service internals
Mailer internalsMailer delivery pipelineMailer templates and operations

Shared packages

Schemas packageUI packageTypeScript configuration packageESLint configuration package

Development workflow

Testing and verificationDependency managementDocumentation authoringUI quality assurance

Operations

Continuous integrationEnvironment variablesOperationsSecurityTroubleshooting

Reference

Route referenceGlossary
Service internalsMailer service

Source map, contract boundary, runtime ownership, and verification guide for transactional email delivery.

Mailer internals

services/mailer is a Bun-hosted Hono service that accepts authenticated transactional-email commands and delivers them through SMTP. It owns rendering and delivery, while the API owns the event that decides an email should be sent. It has no application database and is not a general browser-facing mail relay.

Source map

AreaSourceResponsibility
Bun entrysrc/index.tsstarts the server using the validated port
Hono appsrc/app.tsstatic favicon, bearer guard, route mounting, not-found, and error policy
Send routesrc/routes/send.route.tsJSON parsing, contract validation, delivery call, and HTTP status mapping
Validationsrc/validators/send.validator.tsapplies the shared MailerSendRequestSchema at the boundary
Deliverysrc/services/mailer.service.tsresolves raw or named-template content and uses the shared SMTP transporter
Templatessrc/emailsReact Email components and email-only design tokens
Configurationsrc/config/env.tsT3 Env parsing and sender fallback
Contracts@scs/schemasaccepted request union and success/error response union

Supported request shapes

The shared schema accepts either:

  • raw mail with one to 50 validated recipients, a non-empty subject, and at least one of HTML or text; or
  • the named portal-sign-in-otp template with a six-digit code and an expiry from one to 60 minutes.

The current API uses only the named OTP request. Keeping the accepted union in @scs/schemas makes both callers and Mailer compile against the same boundary. Mailer imports that schema directly rather than re-exporting it through a service-local contract file.

Detailed guides:

  • Delivery pipeline covers authentication, validation, rendering, SMTP reuse, and response behavior.
  • Templates and operations covers React Email, plain-text output, configuration, safe extension, and delivery verification.

Verification map

Tests prove shared-schema acceptance and named-template HTML/text rendering. They stop before a real SMTP send. Provider authentication, sender verification, mailbox delivery, and reputation remain deployment checks.

bun --filter '@scs/mailer' lint
bun --filter '@scs/mailer' typecheck
bun --filter '@scs/mailer' typecheck:test
bun --filter '@scs/mailer' test
bun --filter '@scs/mailer' knip

The workspace has no build script. Do not report a missing task as a passing build; Vercel runs the Bun service through its deployment adapter.

GitHub App runtime and recovery

Cloudflare and local runtime modes, bindings, failure evidence, dead-letter handling, and safe recovery.

Mailer delivery pipeline

Request authentication, schema validation, content resolution, SMTP delivery, and error mapping.

On this page

Mailer internalsSource mapSupported request shapesVerification map