API Mail

Architecture

Route	Description
POST /api/publique/mail/send	Envoyer une campagne
GET /api/publique/mail/job/:id	Statut campagne
GET /api/publique/mail/templates	Lister templates (actifs)
GET /api/publique/mail/templates/categories	Catégories
GET /api/publique/mail/templates/:id	Détail template
GET /api/privee/mail/templates	Lister templates (tous)
POST /api/privee/mail/templates	Créer template
PATCH /api/privee/mail/templates/:id	Modifier template
DELETE /api/privee/mail/templates/:id	Supprimer template
GET /api/privee/mail/templates/categories	Catégories
GET /api/privee/mail/templates/:id	Détail template
PATCH /api/privee/mail/templates/:id/reactivate	Réactiver
GET /api/privee/mail/monitoring/stats	Statistiques
GET /api/privee/mail/monitoring/history	Historique

---

Exemples

Envoyer une Campagne

curl -X POST http://localhost:3000/api/publique/mail/send \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 1,
    "clientIds": ["CLI_001", "CLI_002"],
    "variables": {"prenom": "Jean", "nom": "Dupont"}
  }'

Réponse:

{ "jobId": "123e4567...", "clientCount": 2, "status": "pending" }

Suivre une Campagne

curl http://localhost:3000/api/publique/mail/job/123e4567-e89b-41d4-a716-446655440000

Réponse:

{ "jobId": "123e4567...", "total": 2, "sent": 2, "failed": 0, "pending": 0 }

Créer un Template (Admin)

curl -X POST http://localhost:3000/api/privee/mail/templates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "templateName": "Promo",
    "templateSubject": "Promotion",
    "templateBody": "Bonjour {{prenom}}, code: {{code}}",
    "category": "Promotion"
  }'

Lister Templates (Admin - Tous)

curl http://localhost:3000/api/privee/mail/templates\?page\=1\&limit\=10 \
  -H "Authorization: Bearer TOKEN"

Modifier Template (Admin)

curl -X PATCH http://localhost:3000/api/privee/mail/templates/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"templateName": "Promo Updated"}'

Statistiques (Admin)

curl http://localhost:3000/api/privee/mail/monitoring/stats \
  -H "Authorization: Bearer TOKEN"

Réponse:

{
  "totalEmailsSent": 1250,
  "emailsSentToday": 45,
  "emailsPendingCount": 12,
  "emailsFailedToday": 3,
  "failureRate": 2.5
}

Historique (Admin)

curl "http://localhost:3000/api/privee/mail/monitoring/history?status=sent&limit=50" \
  -H "Authorization: Bearer TOKEN"

---

Query Parameters

Pagination

• page (défaut: 1)
• limit (défaut: 10)

Filtres History

• status: sent, pending, failed
• email: recherche partielle
• jobId: UUID campagne
• clientId: ID client
• dateFrom: ISO 8601
• dateTo: ISO 8601

Filtres Templates

• name: recherche
• category: catégorie

---

Types

Template

{
  id: number;
  templateName: string;
  templateSubject: string;
  templateBody: string;
  category: string | null;
  isActive: boolean;
  dynamicFields?: Record<string, string>;
  createdAt: string;
  updatedAt: string;
}

Campaign

{
  jobId: string; // UUID
  clientCount: number;
  status: 'pending' | 'completed';
}

Email Entry

{
  clientId: string;
  email: string;
  status: 'sent' | 'pending' | 'failed';
  sentAt: string | null;
  errorMessage: string | null;
}

---

Codes HTTP

Code	Signification
200	OK
201	Créé
202	Accepté (campagne)
400	Données invalides
401	Non authentifié
404	Non trouvé

---

Notes

1. Variables : Syntaxe {{variableName}}
2. Soft Delete : Suppression logique, réactivation possible
3. Cron : Emails traités automatiquement toutes les 30s
4. Auth : JWT token requis pour endpoints /api/privee/**
5. Public : Templates actifs uniquement
6. Admin : Tous les templates (actifs + inactifs)