core/src/core/email/README.md

Email Framework

Ce répertoire fournit un wrapper autour de Resend pour l'envoi d'emails, ainsi qu'un composant de mise en page React Email réutilisable. Il ne connaît aucun template métier — les features créent leurs propres templates et utilisent ce module pour l'envoi.

---

Structure

src/core/email/
├── index.js              sendEmail, sendBatchEmails
└── templates/
    ├── index.js           re-export
    └── BaseLayout.js      composant de mise en page React Email

---

Import

import { sendEmail, sendBatchEmails } from '@zen/core/email';
import { BaseLayout } from '@zen/core/email/templates';

---

Variables d'environnement

Variable	Obligatoire	Description
ZEN_EMAIL_RESEND_APIKEY	Oui	Clé API Resend
ZEN_EMAIL_FROM_ADDRESS	Oui	Adresse expéditeur par défaut
ZEN_EMAIL_FROM_NAME	Non	Nom affiché de l'expéditeur
ZEN_EMAIL_LOGO	Non	URL du logo affiché dans BaseLayout
ZEN_EMAIL_LOGO_URL	Non	URL de destination du lien autour du logo
ZEN_SUPPORT_EMAIL	Non	Email affiché dans le footer si supportSection est activé
ZEN_NAME	Non	Nom de l'application (fallback du nom affiché dans BaseLayout)

---

API

sendEmail(email)

Envoie un email via Resend. Retourne { success, data, error }.

const result = await sendEmail({
  to: 'user@example.com',
  subject: 'Bienvenue',
  html: '<p>Bonjour !</p>',
});

if (!result.success) {
  console.error(result.error);
}

Paramètre	Type	Description
to	string | string[]	Destinataire(s)
subject	string	Objet de l'email
html	string	Corps HTML
text	string	Corps texte brut (optionnel)
from	string	Adresse expéditeur (défaut : ZEN_EMAIL_FROM_ADDRESS)
fromName	string	Nom expéditeur (défaut : ZEN_EMAIL_FROM_NAME)
replyTo	string	Adresse de réponse (optionnel)
attachments	object[]	Pièces jointes Resend (optionnel)
tags	object[]	Tags Resend (optionnel)

---

sendBatchEmails(emails)

Envoie plusieurs emails en une seule requête batch Resend. Retourne { success, data, error }.

await sendBatchEmails([
  { to: 'a@example.com', subject: 'Sujet A', html: '<p>A</p>' },
  { to: 'b@example.com', subject: 'Sujet B', html: '<p>B</p>' },
]);

Chaque objet du tableau accepte les mêmes paramètres que sendEmail.

---

BaseLayout

Composant React Email (@react-email/components) qui fournit une structure cohérente : logo ou nom de l'app, titre optionnel, contenu, footer avec copyright et lien support.

import { render } from '@react-email/render';
import { BaseLayout } from '@zen/core/email/templates';

const html = await render(
  <BaseLayout
    preview="Votre commande est confirmée"
    title="Commande confirmée"
    supportSection
  >
    <Text>Merci pour votre achat.</Text>
  </BaseLayout>
);

await sendEmail({ to: 'user@example.com', subject: 'Commande confirmée', html });

Prop	Type	Description
preview	string	Texte de prévisualisation (snippet email)
title	string	Titre affiché en haut du corps
children	ReactNode	Contenu de l'email
companyName	string	Nom affiché si pas de logo (défaut : ZEN_NAME ou ZEN)
logoURL	string	URL du logo (défaut : ZEN_EMAIL_LOGO)
supportSection	boolean	Afficher le lien support dans le footer (défaut : false)
supportEmail	string	Email support (défaut : ZEN_SUPPORT_EMAIL)

---

Créer un template depuis une feature

Les templates vivent avec leur feature, pas dans ce répertoire.

// src/features/auth/emails/WelcomeEmail.js
import { BaseLayout } from '@zen/core/email/templates';
import { Text, Button } from '@react-email/components';

export const WelcomeEmail = ({ name, loginUrl }) => (
  <BaseLayout preview={`Bienvenue, ${name}`} title="Bienvenue !">
    <Text>Bonjour {name}, votre compte est prêt.</Text>
    <Button href={loginUrl}>Se connecter</Button>
  </BaseLayout>
);

// src/features/auth/emails/sendWelcome.js
import { render } from '@react-email/render';
import { sendEmail } from '@zen/core/email';
import { WelcomeEmail } from './WelcomeEmail.js';

export async function sendWelcomeEmail({ to, name, loginUrl }) {
  const html = await render(<WelcomeEmail name={name} loginUrl={loginUrl} />);
  return sendEmail({ to, subject: 'Bienvenue !', html });
}

---

Gestion des erreurs

sendEmail et sendBatchEmails ne lèvent jamais d'exception — toute erreur est capturée, loguée via fail(), et retournée dans { success: false, error }. L'appelant vérifie result.success.