# 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

```bash
# 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

```bash
cd email
npm install
npm run build
```

## Deploy Templates to SES

Before sending emails, deploy the templates to AWS SES:

```bash
npm run deploy-templates
```

This creates/updates three templates in SES:

- `ELMEG_EMAIL_VERIFICATION`
- `ELMEG_PASSWORD_RESET`
- `ELMEG_SECURITY_ALERT`

## Usage

```typescript
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:

```typescript
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
```