DEV Community

Serge Eric KALAGA
Serge Eric KALAGA

Posted on

📧 Mail Service - Service d'envoi d'emails prêt à l'emploi via API REST. Intégrez facilement l'envoi d'emails dans vos projets

#api #docker #devops #backend

📧 Mail Service - Guide d'utilisation

Service d'envoi d'emails prêt à l'emploi via API REST. Intégrez facilement l'envoi d'emails dans vos projets sans réécrire le code SMTP.

🚀 Démarrage rapide

Utilisation avec Docker Hub 

# Récupérer l'image depuis Docker Hub
docker pull kalagaserge/mail_service

# Lancer le conteneur avec les variables d'environnement
docker run -d \
  --name mail_service \
  -p 9876:9876 \
  -e EMAIL_DOMAIN=votre-domaine.com \
  -e EMAIL_HOST=smtp.votre-fournisseur.com \
  -e EMAIL_PORT=587 \
  -e EMAIL_USERNAME=votre-email@domaine.com \
  -e EMAIL_PASSWORD=votre-mot-de-passe \
  -e FROM_EMAIL=noreply@votre-domaine.com \
  kalagaserge/mail_service
Enter fullscreen mode Exit fullscreen mode

Utilisation avec Docker Compose

Créez un fichier docker-compose.yml :

version: '3.8'

services:
  mail_service:
    image: kalagaserge/mail_service
    container_name: mail_service
    ports:
      - "9876:9876"
    environment:
      - EMAIL_DOMAIN=votre-domaine.com
      - EMAIL_HOST=smtp.votre-fournisseur.com
      - EMAIL_PORT=587
      - EMAIL_USERNAME=votre-email@domaine.com
      - EMAIL_PASSWORD=votre-mot-de-passe
      - FROM_EMAIL=noreply@votre-domaine.com
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

Puis lancez le service :

docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

⚙️ Configuration

Variables d'environnement obligatoires

Variable Description Exemple
EMAIL_DOMAIN Domaine de votre organisation monentreprise.com
EMAIL_HOST Serveur SMTP smtp.gmail.com
EMAIL_PORT Port SMTP (généralement 587) 587
EMAIL_USERNAME Nom d'utilisateur SMTP admin@monentreprise.com
EMAIL_PASSWORD Mot de passe SMTP motdepasse123

Variables d'environnement optionnelles

Variable Description Défaut
FROM_EMAIL Adresse email d'expéditeur noreply@{EMAIL_DOMAIN}

Configuration par fournisseur

Gmail 

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USERNAME=votre-email@gmail.com
EMAIL_PASSWORD=mot-de-passe-application
Enter fullscreen mode Exit fullscreen mode

Outlook/Hotmail 

EMAIL_HOST=smtp-mail.outlook.com
EMAIL_PORT=587
EMAIL_USERNAME=votre-email@outlook.com
EMAIL_PASSWORD=votre-mot-de-passe
Enter fullscreen mode Exit fullscreen mode

Mailgun 

EMAIL_HOST=smtp.mailgun.org
EMAIL_PORT=587
EMAIL_USERNAME=postmaster@votre-domaine.mailgun.org
EMAIL_PASSWORD=votre-clé-api
Enter fullscreen mode Exit fullscreen mode

📝 API Documentation

Une fois le service démarré, l'API est accessible sur http://localhost:9876

Documentation interactive

  • Swagger UI : http://localhost:9876/docs
  • ReDoc : http://localhost:9876/redoc

Endpoints disponibles

GET /

Endpoint de vérification du service

Réponse :

{
  "message": "Welcome to the Mail Service API"
}
Enter fullscreen mode Exit fullscreen mode

POST /api/send-email

Envoi d'un email

Corps de la requête :

{
  "receiver_email": "destinataire@exemple.com",
  "email_object": "Sujet de l'email",
  "message_text": "Contenu de l'email"
}
Enter fullscreen mode Exit fullscreen mode

Paramètres :

  • receiver_email (obligatoire) : Adresse email du destinataire ou liste d'adresses
  • email_object (optionnel) : Sujet de l'email (défaut : "No Subject")
  • message_text (obligatoire) : Contenu de l'email (supporte HTML)

Réponse en cas de succès :

{
  "message": "Email sent successfully"
}
Enter fullscreen mode Exit fullscreen mode

GET /api/smtp-status

Vérification du statut du serveur SMTP

Réponse :

{
  "status": true,
  "message": "SMTP server is reachable."
}
Enter fullscreen mode Exit fullscreen mode

États possibles :

  • status: true : Le serveur SMTP est accessible et les identifiants sont valides
  • status: false : Le serveur SMTP n'est pas accessible ou les identifiants sont incorrects

💡 Exemples d'utilisation

Envoi d'un email simple 

curl -X POST "http://localhost:9876/api/send-email" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_email": "user@example.com",
    "email_object": "Test Email",
    "message_text": "Bonjour, ceci est un email de test."
  }'
Enter fullscreen mode Exit fullscreen mode

Envoi à plusieurs destinataires 

curl -X POST "http://localhost:9876/api/send-email" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_email": [
      "user1@example.com", 
      "user2@example.com", 
      "user3@example.com"
    ],
    "email_object": "Newsletter hebdomadaire",
    "message_text": "<h1>Newsletter</h1><p>Contenu de la newsletter...</p>"
  }'
Enter fullscreen mode Exit fullscreen mode

Envoi d'email HTML 

curl -X POST "http://localhost:9876/api/send-email" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_email": "client@example.com",
    "email_object": "Bienvenue !",
    "message_text": "<html><body><h2>Bienvenue dans notre service !</h2><p>Merci de vous être inscrit.</p><a href=\"https://monsite.com\">Visitez notre site</a></body></html>"
  }'
Enter fullscreen mode Exit fullscreen mode

Vérification du statut SMTP 

# Vérifier si le serveur SMTP est accessible
curl http://localhost:9876/api/smtp-status
Enter fullscreen mode Exit fullscreen mode

Réponse en cas de succès :

{
  "status": true,
  "message": "SMTP server is reachable."
}
Enter fullscreen mode Exit fullscreen mode

Réponse en cas d'erreur :

{
  "status": false,
  "message": "SMTP server is not reachable."
}
Enter fullscreen mode Exit fullscreen mode

🔧 Gestion des erreurs

Codes de statut HTTP

  • 200 : Email envoyé avec succès
  • 400 : Données invalides (adresse email incorrecte, configuration manquante)
  • 500 : Erreur serveur (problème SMTP, configuration incorrecte)

Messages d'erreur courants 

{
  "detail": "Invalid email address"
}
Enter fullscreen mode Exit fullscreen mode 
{
  "detail": "Email configurations are not properly set."
}
Enter fullscreen mode Exit fullscreen mode 
{
  "detail": "Error sending email: [détails de l'erreur SMTP]"
}
Enter fullscreen mode Exit fullscreen mode

📊 Diagnostic et monitoring

Vérification de l'état du service 

# Vérifier que le service répond
curl http://localhost:9876/

# Vérifier la documentation API
curl http://localhost:9876/docs

# Tester la connectivité SMTP
curl http://localhost:9876/api/smtp-status
Enter fullscreen mode Exit fullscreen mode 
# Test d'envoi d'email (optionnel)
echo "3. Test d'envoi d'email de diagnostic..."
curl -X POST "http://localhost:9876/api/send-email" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_email": "admin@votre-domaine.com",
    "email_object": "Test de diagnostic - Mail Service",
    "message_text": "Ce message confirme que le service fonctionne correctement."
  }'

echo "=== Fin du diagnostic ==="
Enter fullscreen mode Exit fullscreen mode

🔁 Intégration Kafka

Le service peut consommer des messages Kafka pour envoyer automatiquement des emails si l'intégration Kafka est activée via les variables d'environnement (USE_KAFKA, KAFKA_BOOTSTRAP_SERVERS, KAFKA_CONSUMER_TOPIC, KAFKA_MESSAGE_KEY).

Format JSON attendu pour le message (payload) avec la clé Kafka email_topic (vous pouvez modifier la clé via KAFKA_MESSAGE_KEY) :

{
  "receiver_email": "user@example.com",
  "email_object": "Sujet",
  "message_text": "Contenu du message"
}
Enter fullscreen mode Exit fullscreen mode

Points importants pour une intégration en production ou en environnement conteneurisé :

  • Le conteneur qui exécute le service doit être sur le même réseau Docker que le broker Kafka afin d'utiliser l'adresse interne du broker (ex. broker:9093). Sans réseau partagé, la résolution de nom et la connexion échoueront.
  • Pour les clients externes (depuis la machine hôte), utilisez l'endpoint exposé du broker (ex. localhost:9092) si les ports sont mappés.
  • Assurez-vous que KAFKA_BOOTSTRAP_SERVERS pointe vers l'endpoint correct selon le contexte (interne au réseau Docker vs externe).
  • Vérifiez que le topic configuré (KAFKA_CONSUMER_TOPIC) correspond au topic sur lequel sont publiés les messages.

Exemple minimal (attacher le service au réseau Docker interne du broker) :

version: '3.8'

networks:
  local-kafka:
    external: true

services:
  mail_service:
    image: kalagaserge/mail_service
    container_name: mail_service
    ports:
      - "9876:9876"
    environment:
      - USE_KAFKA=True
      - KAFKA_BOOTSTRAP_SERVERS=broker:9093
      - KAFKA_CONSUMER_TOPIC=email_topic
      - KAFKA_MESSAGE_KEY=email_topic
    networks:
      - local-kafka
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

🐰 Intégration RabbitMQ

Le service peut consommer des messages RabbitMQ pour envoyer automatiquement des emails si l'intégration RabbitMQ est activée via les variables d'environnement (USE_RABBITMQ, RABBITMQ_URL, RABBITMQ_EXCHANGE, RABBITMQ_ROUTING_KEY, RABBITMQ_QUEUE).

Format JSON attendu pour le message publié sur RabbitMQ :

{
  "receiver_email": "user@example.com",
  "email_object": "Sujet",
  "message_text": "Contenu du message"
}
Enter fullscreen mode Exit fullscreen mode

Variables d'environnement RabbitMQ

Variable Description Exemple
USE_RABBITMQ Activer l'intégration RabbitMQ True
RABBITMQ_URL URL de connexion RabbitMQ amqp://admin:admin@rabbitmq:5672
RABBITMQ_EXCHANGE Nom de l'exchange email_exchange
RABBITMQ_ROUTING_KEY Routing key pour lier la queue email_routing_key
RABBITMQ_QUEUE Nom de la queue email_queue
RABBITMQ_DEFAULT_USER Utilisateur RabbitMQ admin
RABBITMQ_DEFAULT_PASS Mot de passe RabbitMQ admin

Points importants pour l'intégration RabbitMQ

  • Le conteneur qui exécute le service doit être sur le même réseau Docker que RabbitMQ afin d'utiliser l'adresse interne (ex. rabbitmq:5672). Sans réseau partagé, la résolution de nom et la connexion échoueront.
  • Pour les clients externes (depuis la machine hôte), utilisez l'endpoint exposé de RabbitMQ (ex. localhost:5672) si les ports sont mappés.
  • Assurez-vous que RABBITMQ_URL pointe vers l'endpoint correct selon le contexte (interne au réseau Docker vs externe).
  • Vérifiez que l'exchange et la routing key configurés correspondent à ceux utilisés par vos producteurs de messages.
  • Le service déclare automatiquement l'exchange de type TOPIC et la queue durable, puis les lie avec la routing key spécifiée.

🚨 Sécurité et bonnes pratiques

Recommandations de sécurité

  1. Utilisez des mots de passe d'application pour Gmail (pas votre mot de passe principal)
  2. Limitez l'accès au port 9876 dans votre pare-feu
  3. Utilisez HTTPS en production avec un reverse proxy (nginx, traefik)
  4. Stockez les secrets de manière sécurisée (Docker secrets, variables d'environnement chiffrées)
  5. Surveillez régulièrement le statut SMTP avec l'endpoint /api/smtp-status

Développé avec ❤️ par Kalaga Serge

Top comments (0)