b4cddf41ea
- Fork elmeg-demo codebase for multi-band support - Add data importer infrastructure with base class - Create band-specific importers: - phish.py: Phish.net API v5 - grateful_dead.py: Grateful Stats API - setlistfm.py: Dead & Company, Billy Strings (Setlist.fm) - Add spec-kit configuration for Gemini - Update README with supported bands and architecture
147 lines
4 KiB
Markdown
147 lines
4 KiB
Markdown
# 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
|
||
```
|