Compath Docs

Appearance

IE.2: Templated Email Delivery ​

Summary ​

Compath sends application emails through a shared email service backed by Resend. The service loads an email template by key and language, falls back to English when needed, renders variables, creates an email-type notification delivery record, sends the email, then records sent or failed delivery status.

Role ​

  • Primary: System
  • Secondary: Guest, Client, Counselor, Admin, Resend

Entry Point ​

  • Service call: EmailService.SendTemplatedEmail
  • Common template keys: client_invitation, booking_confirmed, booking_received, booking_request_new, booking_cancelled, booking_reschedule_requested, booking_rescheduled, booking_reschedule_rejected, scheduled_meeting_invitation, instant_meeting_invitation, meeting_updated, assessment_assigned, assessment_completed
  • Admin template management: /admin/system-settings/email-templates/:templateId

Preconditions ​

  • RESEND_API_KEY is configured for email sending.
  • email_templates contains the requested template key and language, or an English fallback.
  • Recipients pass email validation.

Steps ​

  1. A domain service requests a templated email with template key, recipient list, variables, optional recipient user ID, and language.
  2. Email service defaults language to en if none is provided.
  3. Email service loads the template by key and language.
  4. If missing and the language is not English, service tries the English template.
  5. Service renders the subject as plain text and the body as HTML or text using Handlebars-style variables.
  6. Service maps the template key to a notification category where possible.
  7. Service creates a notifications row with notification_type=email, pending delivery status, and the rendered content.
  8. Service calls Resend through EmailClient.SendEmail.
  9. On success, service updates the notification delivery status to sent with attempt count and timestamp.
  10. On failure, service updates the notification delivery status to failed with error details and attempt count.
  11. Email delivery records are not published through SSE because email is a separate channel from in-app notifications.

Diagram ​

Edge Cases ​

  • Template missing: Email send fails before creating a delivery record.
  • Invalid recipient: Resend wrapper rejects invalid email addresses before sending.
  • No recipients: Email client returns validation error.
  • No HTML/text body: Email client returns validation error.
  • Delivery record update failure: Service returns an error even if the email was sent.
  • Email templates vs notification templates: Email delivery records set TemplateID to nil because notification foreign keys point to notification templates, not email templates.
  • Test emails: Admin test emails are sent by the email template service and do not create notification records.

Current Implementation Notes ​

  • Backend: backend/internal/services/email_service.go, backend/pkg/email.go, backend/internal/services/email_template_service.go
  • Templates: backend/scripts/seed_email_templates.sql, backend/scripts/seeds/006_seed_booking_email_templates.sql

Screenshot Status ​

  • Not captured.