---
id: "SAAS-013"
title: "Email Module"
type: "Module"
status: "Published"
priority: "P1"
module: "email"
version: "1.0.0"
created_date: "2026-01-07"
updated_date: "2026-01-10"
---

# SAAS-013: Email Module

## Metadata

| Campo | Valor |
|-------|-------|
| Codigo | SAAS-013 |
| Modulo | Email |
| Prioridad | P1 |
| Estado | Completado |
| Fase | 5 - Integraciones |
| Sprint | Sprint 4 |
| Fecha Implementacion | 2026-01-07 |
| Ultima Actualizacion | 2026-01-10 |

---

## Descripcion

Modulo de email con soporte multi-proveedor (SendGrid, AWS SES, SMTP) integrado con el sistema de notificaciones. Permite a los tenants enviar correos electronicos transaccionales, notificaciones y comunicaciones personalizadas utilizando templates y variables dinamicas.

---

## Objetivos

1. Proporcionar un sistema de envio de email robusto y multi-proveedor
2. Permitir envio de emails simples (texto/HTML) y con templates
3. Soportar attachments y campos CC/BCC
4. Integrarse con el modulo de notificaciones existente
5. Implementar fallback logging cuando no hay proveedor configurado
6. Soportar bulk email con batches

---

## Alcance

### Incluido

- Envio de emails simples (texto/HTML)
- Templates con variables dinamicas
- Soporte para attachments (base64)
- Campos CC/BCC
- Bulk email (batches de 10)
- Fallback logging cuando no hay proveedor configurado
- Integracion con sistema de notificaciones
- Multi-proveedor: SendGrid, AWS SES, SMTP

### Excluido

- Email marketing masivo
- Tracking de opens/clicks (futuro)
- Templates almacenados en base de datos (futuro)
- Queue de emails con BullMQ (futuro)
- Rate limiting por tenant (futuro)

---

## Proveedores Soportados

| Proveedor | Estado | Notas |
|-----------|--------|-------|
| SendGrid | Completado | API v3 |
| AWS SES | Completado | SES v2 (simplificado) |
| SMTP | Parcial | Requiere nodemailer |

---

## Arquitectura

```
apps/backend/src/modules/email/
├── email.module.ts          # Modulo global
├── index.ts
├── dto/
│   ├── send-email.dto.ts    # DTOs de envio
│   └── index.ts
├── services/
│   ├── email.service.ts     # Servicio principal
│   └── index.ts
└── templates/               # Templates (futuro)
```

---

## Configuracion

### Variables de Entorno

```env
# Provider selection
EMAIL_PROVIDER=sendgrid          # sendgrid | ses | smtp

# Common settings
EMAIL_FROM=noreply@example.com
EMAIL_FROM_NAME=Template SaaS
EMAIL_REPLY_TO=support@example.com

# SendGrid
SENDGRID_API_KEY=SG.xxxxx

# AWS SES
AWS_SES_REGION=us-east-1
AWS_SES_ACCESS_KEY_ID=AKIAXXXXXXX
AWS_SES_SECRET_ACCESS_KEY=xxxxx

# SMTP (fallback)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user
SMTP_PASSWORD=password
SMTP_SECURE=false
```

---

## API del Servicio

### sendEmail(dto: SendEmailDto): Promise<EmailResult>

```typescript
await emailService.sendEmail({
  to: { email: 'user@example.com', name: 'User Name' },
  subject: 'Welcome!',
  html: '<h1>Welcome</h1>',
  text: 'Welcome',
  cc: [{ email: 'copy@example.com' }],
  attachments: [{
    filename: 'doc.pdf',
    content: 'base64...',
    contentType: 'application/pdf'
  }]
});
```

### sendTemplateEmail(dto: SendTemplateEmailDto): Promise<EmailResult>

```typescript
await emailService.sendTemplateEmail({
  to: { email: 'user@example.com' },
  templateKey: 'welcome',
  variables: {
    userName: 'John',
    appName: 'Template SaaS'
  }
});
```

---

## Templates Incluidos

| Key | Descripcion |
|-----|-------------|
| welcome | Email de bienvenida |
| password_reset | Reset de contrasena |
| invitation | Invitacion a tenant |
| notification | Notificacion generica |

---

## Estructura de Respuesta

```typescript
interface EmailResult {
  success: boolean;
  messageId?: string;
  provider: 'sendgrid' | 'ses' | 'smtp';
  error?: string;
}
```

---

## Integracion con Notificaciones

El modulo de email esta integrado con NotificationsService. Cuando se crea una notificacion con `channel: 'email'`:

```typescript
await notificationsService.create({
  userId: 'uuid',
  channel: 'email',
  email: 'user@example.com',     // Requerido para email
  userName: 'User Name',          // Opcional
  title: 'Subject',
  message: 'Body content',
  actionUrl: 'https://app.com/action'
}, tenantId);
```

---

## Comportamiento sin Configuracion

Cuando no hay proveedor configurado:
- Los emails se loguean en consola
- `EmailResult.success = true`
- `EmailResult.messageId = 'mock-{timestamp}'`

---

## Entregables

- [x] EmailModule backend con servicio multi-proveedor
- [x] DTOs validados (send-email.dto.ts)
- [x] Integracion con NotificationsService
- [x] Soporte SendGrid API v3
- [x] Soporte AWS SES v2
- [x] Fallback logging para desarrollo

---

## Criterios de Aceptacion

- [x] Envio de email simple (texto/HTML) funciona
- [x] Envio con template funciona
- [x] Attachments se envian correctamente
- [x] CC/BCC funcionan
- [x] Fallback logging funciona sin proveedor
- [x] Integracion con notificaciones funciona

---

## Archivos Creados

| Archivo | Descripcion |
|---------|-------------|
| `modules/email/email.module.ts` | Modulo global |
| `modules/email/services/email.service.ts` | Servicio multi-proveedor |
| `modules/email/dto/send-email.dto.ts` | DTOs validados |
| `config/env.config.ts` | Variables de email |

---

## Archivos Modificados

| Archivo | Cambio |
|---------|--------|
| `app.module.ts` | Import EmailModule |
| `notifications/services/notifications.service.ts` | Integracion EmailService |
| `notifications/dto/create-notification.dto.ts` | Campos email, userName |

---

## Dependencias

| Modulo | Tipo | Descripcion |
|--------|------|-------------|
| SAAS-002 (Tenants) | Requerido | tenant_id en operaciones |
| SAAS-007 (Notifications) | Requerido | Canal de notificacion |

---

## Proximos Pasos

1. [ ] Implementar SMTP con nodemailer
2. [ ] AWS SES con SDK v3 (firma v4)
3. [ ] Templates desde DB (notification_templates)
4. [ ] Queue de emails con BullMQ
5. [ ] Tracking de opens/clicks
6. [ ] Rate limiting por tenant

---

## Referencias

- [INT-003-email](../02-integraciones/INT-003-email.md)
- [SAAS-007-notifications](./SAAS-007-notifications.md)
- [SendGrid API v3](https://docs.sendgrid.com/api-reference)
- [AWS SES v2 API](https://docs.aws.amazon.com/ses/latest/APIReference-V2/)
- [Nodemailer](https://nodemailer.com/)

---

**Ultima actualizacion:** 2026-01-10
**Version:** 1.0.0
**Autor:** Claude Code (Reestructuracion Documental)