email-system

Architecture

The email system is in internal/email/ and follows a multi-layered pipeline:

Service (orchestrator)
  |-- VariableResolver  -> resolves template variables from 4 sources
  |-- Renderer          -> renders templates with 3 supported engines
  |-- Sender            -> sends via SMTP (or logs in dev mode)
  |-- Repository        -> DB access for types, templates, server configs

Entry point: email.Service.SendEmailWithContext(appID, emailTypeCode, toEmail, userID, vars)

Send Pipeline

1. VariableResolver.ResolveVariables()  -- build final variable map
2. resolveTemplate()                     -- find the right template
3. Renderer.RenderTemplate()             -- render subject, HTML, text
4. resolveSMTPConfigForTemplate()        -- find the right SMTP config
5. Sender.Send()                         -- deliver via SMTP

Template Resolution Chain

Defined in internal/email/service.go method resolveTemplate:

1. DB: app-specific template
   WHERE app_id = ? AND email_type_id = ? AND is_active = true

2. DB: global default template
   WHERE app_id IS NULL AND email_type_id = ? AND is_active = true

3. Hardcoded fallback
   defaults.go -> GetDefaultTemplate(typeCode)

SMTP Resolution Chain

Defined in internal/email/service.go method resolveSMTPConfig:

1. DB: per-app config
   WHERE app_id = ? AND is_active = true AND is_default = true

2. DB: global config
   WHERE app_id IS NULL AND is_active = true AND is_default = true

3. Empty config -> dev/fallback mode (log to stdout)

With template override (resolveSMTPConfigForTemplate):

1. If template has ServerConfigID -> use that specific config by ID
2. Otherwise -> standard chain above
3. Apply template-level FromEmail/FromName overrides on top

Variable Resolution Pipeline

Defined in internal/email/resolver.go. Resolution priority (lowest to highest):

Variable Sources

All variable constants are in internal/email/types.go.

Template Engines

Defined in internal/email/renderer.go:

The renderer converts all variables to both snake_case and PascalCase forms, so templates can use either style.

Subject lines always use Go template syntax regardless of engine.

Email Types (7 built-in)

Constants in internal/email/types.go:

Default Templates

Defined in internal/email/defaults.go. All use go_template engine, provide both HTML and plain text bodies, and use responsive table-based layout with consistent styling (indigo #4f46e5 primary color, 600px max width).

Service Methods

Typed Send Methods (in internal/email/service.go)

Management Methods

Template CRUD: GetTemplatesByApp, GetGlobalDefaultTemplates, GetTemplateByID, SaveAppTemplate, SaveGlobalTemplate, DeleteTemplate, ResetTemplateToDefault, PreviewTemplate

Email type CRUD: GetAllEmailTypes, GetEmailTypeByCode, CreateEmailType, UpdateEmailType, DeleteEmailType

Server config CRUD: GetServerConfig, SaveServerConfig, DeleteServerConfig, GetAllServerConfigs, etc.

SMTP Sending (internal/email/sender.go)

Uses gopkg.in/mail.v2.

Dev mode: If SMTP host is empty or "smtp.example.com", logs email to stdout (no error).

TLS handling:

• Port 465: implicit SSL (d.SSL = true)
• Other ports: MandatoryStartTLS, MinVersion TLS 1.2

Error behavior:

• Send(): on SMTP failure, logs email as fallback and returns nil (email failure doesn't break business flow)
• SendTest(): always returns errors (for admin testing)

Database Models

• EmailType (pkg/models/email_type.go) -- types with variable definitions as JSONB
• EmailTemplate (pkg/models/email_template.go) -- templates scoped to app or global
• EmailServerConfig (pkg/models/email_server_config.go) -- SMTP configs scoped to app or global

When To Use This Skill

Load this skill when working on email sending, email templates, SMTP configuration, template variables, or any email-related feature.