elmeg-demo/email

Elmeg Email Service

Transactional email layer for Elmeg using Amazon SES v2 with stored templates.

Purpose

This module provides a production-ready email service for user-initiated transactional emails:

• Email Verification – Sent after user registration
• Password Reset – Sent when user requests password recovery
• Security Alerts – Sent for account security events (new logins, password changes)

Compliance Note: This service is strictly for transactional, user-initiated emails. No newsletters, marketing emails, or cold outreach. No purchased or third-party email lists are used.

Requirements

• Node.js >= 18.0.0
• AWS account with SES verified domain
• SES templates deployed (see below)

Environment Variables

# Required
AWS_ACCESS_KEY_ID=AKIA...           # IAM user with SES permissions
AWS_SECRET_ACCESS_KEY=...           # IAM user secret key
AWS_SES_REGION=us-east-1            # SES region (domain must be verified here)
EMAIL_FROM=noreply@elmeg.xyz        # Verified sender address

# Optional
FRONTEND_URL=https://elmeg.xyz      # For generating email links
SUPPORT_EMAIL=support@elmeg.xyz     # Contact email in templates

Installation

cd email
npm install
npm run build

Deploy Templates to SES

Before sending emails, deploy the templates to AWS SES:

npm run deploy-templates

This creates/updates three templates in SES:

• ELMEG_EMAIL_VERIFICATION
• ELMEG_PASSWORD_RESET
• ELMEG_SECURITY_ALERT

Usage

import {
  sendVerificationEmail,
  sendPasswordResetEmail,
  sendSecurityAlertEmail,
  generateVerificationLink,
  generateResetLink,
} from "@elmeg/email-service";

// After user registration
await sendVerificationEmail({
  to: "user@example.com",
  userName: "John",
  verificationLink: generateVerificationLink(token),
});

// After password reset request
await sendPasswordResetEmail({
  to: "user@example.com",
  userName: "John",
  resetLink: generateResetLink(token),
});

// After suspicious login
await sendSecurityAlertEmail({
  to: "user@example.com",
  userName: "John",
  securityEventDescription: "New sign-in from Chrome on Windows at 10:30 AM",
});

Template Placeholders

Placeholder	Description	Templates
{{app_name}}	"Elmeg"	All
{{user_name}}	User's name or email prefix	All
{{support_email}}	Support contact	All
{{verification_link}}	Email verification URL	Verification
{{reset_link}}	Password reset URL	Password Reset
{{security_event_description}}	Event details	Security Alert

AWS SES Setup Checklist

1. Verify Domain – Add elmeg.xyz in SES console with DKIM records
2. Request Production Access – Move out of sandbox to send to any address
3. Create IAM User – With ses:SendEmail and ses:SendTemplatedEmail permissions
4. Deploy Templates – Run npm run deploy-templates

Compliance & Best Practices

Requirement	Implementation
User-initiated only	All emails triggered by user actions
No purchased lists	Only registered users receive emails
Bounce handling	SES automatically suppresses bounced addresses
Complaint handling	SES suppresses addresses that report spam
Unsubscribe	N/A for transactional (required action emails)

Error Handling

All send functions return a structured result:

interface EmailResult {
  success: boolean;
  messageId?: string;  // SES message ID on success
  error?: {
    code: string;      // Error code from SES
    message: string;   // Human-readable error message
  };
}

File Structure

email/
├── src/
│   ├── email-service.ts   # Main service module
│   └── examples.ts        # Usage examples
├── scripts/
│   └── deploy-templates.ts # Template deployment script
├── templates/
│   └── README.md          # Template documentation
├── package.json
├── tsconfig.json
└── README.md              # This file