DEV Community

kalagaserge
kalagaserge

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)