📬 Wontan Mail

Librairie TypeScript/JavaScript moderne et scalable pour l'envoi d'emails via API externe

Wontan Mail est une solution élégante et performante pour intégrer l'envoi d'emails dans vos applications Node.js. Conçue avec TypeScript, elle offre une API simple, une architecture évolutive et un typage strict pour une expérience développeur optimale.

✨ Fonctionnalités

• 🚀 API simple et intuitive - Envoyez des emails en quelques lignes de code
• 🔐 Authentification sécurisée - Protection par clé API (X-API-KEY)
• 📝 Templates dynamiques - Support des paramètres personnalisables
• 🎯 TypeScript natif - Typage strict et autocomplétion IDE
• 🔧 Gestion d'erreurs robuste - Messages d'erreur détaillés
• 📦 Zéro dépendance - Utilise l'API Fetch native de Node.js
• 🌐 Multi-serveurs - Gestion de plusieurs serveurs d'envoi

📦 Installation

npm install wontan-mail

yarn add wontan-mail

🚀 Démarrage rapide

javascript (composant de mail)

import { MailClient } from 'wontan-mail';
import { renderToStaticMarkup } from 'react-dom/server';

const client = new MailClient('your-api-key');

const templateContent = renderToStaticMarkup(
  CredentialsMail({ email: user.email, password: newPassword })
);

client.sendMail({
  recipients: ['[email protected]'],
  subject: "My mail",
  template_content: templateContent,
})
.then(response => {
  console.log('✅ Email envoyé avec succès !', response);
})
.catch(error => {
  console.error('❌ Erreur lors de l\'envoi :', error.message);
});

Composant credentials

export default function CredentialsMail({ email, password }: { email: string, password: string }) {
  return (
    <div>
      <div>
        <h2>
          Bonjour,
        </h2>
        
        <p>
          Vos identifiants de connexion sont :
        </p>
        
        <div>
          <p>
            <strong>📧 Email :</strong> {email}
          </p>
          <p>
            <strong>🔑 Mot de passe :</strong> {password}
          </p>
        </div>
        
        <p>
          Merci et à bientôt !
        </p>
      </div>
    </div>
  );
}

TypeScript

import { MailClient } from 'wontan-mail';

const client = new MailClient('your-api-key');

try {
  const response = await client.sendMail({
    recipients: ['[email protected]'],
    template_name: 'welcome',
    server_name: 'default',
    params: {
      name: 'John Doe',
      company: 'Acme Corp'
    }
  });
  
  console.log('✅ Email envoyé avec succès !', response);
} catch (error) {
  console.error('❌ Erreur lors de l\'envoi :', error.message);
}

JavaScript (ES6+)

import { MailClient } from 'wontan-mail';

const client = new MailClient('your-api-key');

client.sendMail({
  recipients: ['[email protected]'],
  template_name: 'welcome',
  server_name: 'default',
  params: { name: 'John Doe' }
})
.then(response => {
  console.log('✅ Email envoyé avec succès !', response);
})
.catch(error => {
  console.error('❌ Erreur lors de l\'envoi :', error.message);
});

JavaScript (CommonJS)

const { MailClient } = require('wontan-mail');

const client = new MailClient('your-api-key');
// ... reste du code identique

📚 Documentation API

Constructeur

new MailClient(apiKey: string, baseUrl?: string)

| Paramètre | Type | Obligatoire | Description | |-----------|------|-------------|-------------| | apiKey | string | ✅ | Votre clé API Wontan Mail | | baseUrl | string | ❌ | URL de base de l'API (optionnel) |

Méthode sendMail

sendMail(options: MailOptions): Promise<MailResponse>

MailOptions

| Propriété | Type | Obligatoire | Description | |-----------|------|-------------|-------------| | recipients | string[] | ✅ | Liste des adresses email destinataires | | template_name | string | ✅ | Nom du template à utiliser | | server_name | string | ✅ | Nom du serveur d'envoi configuré | | params | object | ❌ | Paramètres dynamiques pour le template |

MailResponse

interface MailResponse {
  status: string;
  message: string;
  // autres propriétés selon la réponse API
}

🛠️ Configuration

1. Création d'un compte

Rendez-vous sur wontan-mail.com pour créer votre compte et accéder à votre tableau de bord.

2. Configuration des serveurs

1. Connectez-vous et accédez aux serveurs
2. Configurez votre serveur SMTP pour l'envoi d'emails
3. Notez le nom de votre serveur configuré

3. Création de templates

1. Accédez à la section templates
2. Créez vos templates d'emails avec design personnalisé
3. Utilisez les variables dynamiques avec la syntaxe {{variable}}

4. Récupération de la clé API

1. Dans votre tableau de bord, générez votre clé API
2. Copiez la clé qui commence par wm_
3. Gardez cette clé secrète et sécurisée

5. Autoriser les domaines d'utilisation de l'API

Pour des raisons de sécurité, vous devez autoriser les domaines qui peuvent utiliser votre clé API :

1. Accédez aux paramètres de sécurité : Rendez-vous sur wontan-mail.com/profile/#authorized-hosts
2. Ajoutez vos domaines : Listez tous les domaines autorisés à utiliser votre API
   • Pour le développement local : localhost, 127.0.0.1
   • Pour la production : yourdomain.com, api.yourdomain.com
3. Sauvegardez : N'oubliez pas de sauvegarder vos modifications

⚠️ Important : Sans cette configuration, vos requêtes API seront rejetées pour des raisons de sécurité.

💡 Exemples d'utilisation

Email de bienvenue

const welcomeEmail = await client.sendMail({
  recipients: ['[email protected]'],
  template_name: 'welcome',
  server_name: 'marketing',
  params: {
    firstName: 'Alice',
    companyName: 'TechCorp',
    activationLink: 'https://app.example.com/activate/xyz123'
  }
});

Email de notification

const notificationEmail = await client.sendMail({
  recipients: ['[email protected]', '[email protected]'],
  template_name: 'alert',
  server_name: 'system',
  params: {
    alertType: 'ERROR',
    timestamp: new Date().toISOString(),
    details: 'Service temporairement indisponible'
  }
});

Envoi groupé

const recipients = [
  '[email protected]',
  '[email protected]',
  '[email protected]'
];

const bulkEmail = await client.sendMail({
  recipients,
  template_name: 'newsletter',
  server_name: 'newsletter',
  params: {
    month: 'Janvier 2024',
    featuredArticle: 'Les nouveautés de notre plateforme'
  }
});

🚨 Gestion d'erreurs

try {
  await client.sendMail({
    recipients: [], // ❌ Tableau vide - génère une erreur
    template_name: 'welcome',
    server_name: 'default'
  });
} catch (error) {
  if (error.message.includes('recipients must be a non-empty array')) {
    console.error('❌ Aucun destinataire spécifié');
  } else if (error.message.includes('API Error: 401')) {
    console.error('❌ Clé API invalide');
  } else if (error.message.includes('API Error: 404')) {
    console.error('❌ Template ou serveur non trouvé');
  } else {
    console.error('❌ Erreur inconnue :', error.message);
  }
}

🔧 Développement

# Cloner le repository
git clone https://github.com/koulibalyamadou10/wontan-mail.git

# Installer les dépendances
npm install

# Compiler TypeScript
npm run build

# Lancer les tests
npm test

# Mode développement avec rechargement automatique
npm run dev

🤝 Contribution

Les contributions sont les bienvenues ! Voici comment contribuer :

1. Fork le projet
2. Créez une branche pour votre fonctionnalité (git checkout -b feature/AmazingFeature)
3. Commitez vos changements (git commit -m 'Add some AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrez une Pull Request

Directives de contribution :

• Respectez les conventions de code existantes
• Ajoutez des tests pour les nouvelles fonctionnalités
• Mettez à jour la documentation si nécessaire
• Assurez-vous que tous les tests passent

📄 License

MIT © Koulibaly Amadou

📞 Support

• 📧 Email: [email protected]
• 🌐 Site web: wontan-mail.com