@djez/smtp-mailer
v1.1.1
Published
Mailer SMTP personnalisé basé sur Nodemailer (TLS, DKIM, pool, retry, templates Handlebars).
Maintainers
djezouReadme
@djez/smtp-mailer
Mailer SMTP personnalisé basé sur Nodemailer avec support TLS, DKIM, pool de connexions, retry automatique et templates Handlebars.
📦 Installation
npm install @djez/smtp-mailer🚀 Utilisation
Configuration de base
import { SMTPMailer } from '@djez/smtp-mailer';
const mailer = new SMTPMailer({
host: 'smtp.example.com',
port: 587,
secure: false, // true pour le port 465
auth: {
user: '[email protected]',
pass: 'votre-mot-de-passe',
},
fromDefault: 'Votre Nom <[email protected]>',
});Envoi d'email simple
const info = await mailer.send({
to: '[email protected]',
subject: 'Test d\'email',
html: '<h1>Bonjour</h1><p>Ceci est un test.</p>',
text: 'Bonjour, ceci est un test.',
});Envoi avec pièces jointes
const info = await mailer.send({
to: '[email protected]',
subject: 'Email avec pièce jointe',
html: '<p>Veuillez trouver ci-joint le document.</p>',
attachments: [
{
filename: 'document.pdf',
path: '/chemin/vers/document.pdf',
},
],
});Utilisation de templates Handlebars
Créez un fichier template dans le dossier templates :
templates/welcome.hbs
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="utf-8">
<title>{{title}}</title>
</head>
<body style="font-family:Arial,Helvetica,sans-serif">
<h1>{{title}}</h1>
<p>Bonjour {{name}},</p>
<p>Bienvenue sur notre plateforme 🎉</p>
<p>— L'équipe</p>
</body>
</html>Puis utilisez-le :
const mailer = new SMTPMailer({
// ... configuration
templateDir: './templates',
});
const info = await mailer.sendTemplate({
template: 'welcome',
to: '[email protected]',
subject: 'Bienvenue !',
data: {
title: 'Bienvenue sur notre site',
name: 'Jean Dupont',
},
});Configuration avancée avec pool
const mailer = new SMTPMailer({
host: 'smtp.example.com',
port: 587,
auth: {
user: '[email protected]',
pass: 'votre-mot-de-passe',
},
fromDefault: 'Votre Nom <[email protected]>',
// Pool de connexions (recommandé en production)
pool: {
pool: true,
maxConnections: 5,
maxMessages: 100,
rateLimit: 50,
rateDelta: 1000,
},
// Configuration TLS
tls: {
minVersion: 'TLSv1.2',
rejectUnauthorized: true,
},
// Retry automatique
retries: 3,
retryDelayMs: 2000,
// Mode debug
debug: true,
});Health check
const isHealthy = await mailer.healthCheck();
if (isHealthy) {
console.log('SMTP server is ready');
}Mode dry run (test sans envoi)
const mailer = new SMTPMailer({
// ... configuration
dryRun: true,
debug: true,
});
// Les emails seront loggés mais pas envoyés
await mailer.send({
to: '[email protected]',
subject: 'Test',
html: '<p>Test</p>',
});Fermeture du pool
// Toujours fermer le pool en production
await mailer.close();⚙️ Configuration
SMTPConfig
| Option | Type | Description |
|--------|------|-------------|
| host | string | Requis. Serveur SMTP |
| port | number | Requis. Port SMTP (587, 465, etc.) |
| secure | boolean | true pour le port 465 |
| auth | SMTPAuth | Identifiants d'authentification |
| fromDefault | string \| Address | Adresse expéditeur par défaut |
| tls | TLSOptions | Options TLS |
| pool | PoolOptions | Configuration du pool |
| templateDir | string | Dossier contenant les templates .hbs |
| dryRun | boolean | Mode test sans envoi |
| retries | number | Nombre de tentatives (défaut: 2) |
| retryDelayMs | number | Délai entre tentatives en ms (défaut: 1000) |
| debug | boolean | Active les logs de debug |
TLSOptions
| Option | Type | Description |
|--------|------|-------------|
| minVersion | string | Version TLS minimale (ex: "TLSv1.2") |
| cert | string \| Buffer | Certificat client |
| key | string \| Buffer | Clé privée client |
| rejectUnauthorized | boolean | Rejeter certificats non autorisés (défaut: true) |
PoolOptions
| Option | Type | Description |
|--------|------|-------------|
| pool | boolean | Active le pooling (recommandé) |
| maxConnections | number | Nombre max de connexions simultanées (défaut: 5) |
| maxMessages | number | Max messages par connexion (défaut: 100) |
| rateDelta | number | Période de rate limiting en ms (défaut: 1000) |
| rateLimit | number | Limite de messages par période |
📝 Exemples
Email transactionnel
await mailer.send({
to: '[email protected]',
subject: 'Confirmation de commande',
html: `
<h2>Merci pour votre commande !</h2>
<p>Votre commande #${orderId} a été confirmée.</p>
<p>Montant: ${amount} €</p>
`,
});Email à plusieurs destinataires
await mailer.send({
to: ['[email protected]', '[email protected]'],
cc: '[email protected]',
bcc: '[email protected]',
subject: 'Newsletter',
html: '<p>Contenu de la newsletter</p>',
});Email avec reply-to personnalisé
await mailer.send({
to: '[email protected]',
subject: 'Support technique',
html: '<p>Comment pouvons-nous vous aider ?</p>',
replyTo: '[email protected]',
});🔧 Développement
# Installation des dépendances
npm install
# Compilation TypeScript
npm run build
# Nettoyage du dossier dist
npm run clean📚 API
Classes
SMTPMailer
Classe principale pour l'envoi d'emails SMTP.
Méthodes :
constructor(config: SMTPConfig)- Crée une instance de mailersend(opts: SendOptions)- Envoie un emailsendTemplate<T>(opts: TemplateOptions<T>)- Envoie un email basé sur un templatehealthCheck()- Vérifie la connexion SMTPclose()- Ferme le pool de connexions
⚠️ Notes importantes
- Le pool de connexions est recommandé en production pour de meilleures performances
- Le mode
dryRunest utile pour les tests en développement - Le retry automatique est configuré par défaut (2 tentatives, 1 seconde de délai)
- Les templates Handlebars sont compilés à chaque envoi
📄 Licence
MIT
👤 Auteur
Djezou Eric Martial [email protected]