Mail Service Documentation

📧 Mail Service

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.

Commencer GitHub

🚀 Démarrage rapide

Avec Docker Hub

bash

docker pull kalagaserge/mail_service

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

Avec Docker Compose

yaml

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

Puis lancez :

bash

docker-compose up -d

⚙️ 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}`

Exemples de configuration de quelques fournisseurs

Gmail

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

Outlook/Hotmail

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

Mailgun

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

📝 API Documentation

API disponible sur : http://localhost:9876

🎨 Swagger UI

Interface interactive pour tester les endpoints

http://localhost:9876/docs

📖 ReDoc

Documentation API complète et détaillée

http://localhost:9876/redoc

GET/

Endpoint de vérification du service

json

{
  "message": "Welcome to the Mail Service API"
}

POST/api/send-email

Envoi d'un email

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)

Corps de la requête :

json

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

Réponse en cas de succès :

json

{
  "message": "Email sent successfully"
}

GET/api/smtp-status

Vérification du statut du serveur SMTP

Réponse :

json

{
  "status": true,
  "message": "SMTP server is reachable."
}

É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

bash

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."
  }'

Envoi à plusieurs destinataires

bash

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>"
  }'

Envoi d'email HTML

bash

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>"
  }'

Vérification du statut SMTP

bash

curl http://localhost:9876/api/smtp-status

Réponse en cas de succès :

json

{
  "status": true,
  "message": "SMTP server is reachable."
}

Réponse en cas d'erreur :

json

{
  "status": false,
  "message": "SMTP server is not reachable."
}

🔧 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

Email invalide

json

{
  "detail": "Invalid email address"
}

Configuration incomplète

json

{
  "detail": "Email configurations are not properly set."
}

Erreur SMTP

json

{
  "detail": "Error sending email: [détails de l'erreur SMTP]"
}

Diagnostic et monitoring

bash

# 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

# Test d'envoi d'email (optionnel)
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."
  }'

🔁 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.

Format JSON attendu

Clé Kafka : email_topic (modifiable via KAFKA_MESSAGE_KEY)

json

{
  "receiver_email": ["user@example.com"], // string or list of strings
  "email_object": "Sujet",
  "message_text": "Contenu du message"
}

Variables d'environnement Kafka

Variable	Description	Exemple
`USE_KAFKA`	`Activer l'intégration Kafka`	`True`
`KAFKA_BOOTSTRAP_SERVERS`	`Serveurs bootstrap Kafka`	`broker:9093`
`KAFKA_CONSUMER_TOPIC`	`Topic Kafka à consommer`	`email_topic`
`KAFKA_MESSAGE_KEY`	`Clé du message Kafka`	`email_topic`

⚠️ Points importants

• Le conteneur doit être sur le même réseau Docker que le broker Kafka
• Utilisez l'adresse interne du broker (ex. broker:9093) sur le même réseau
• Pour les clients externes, utilisez l'endpoint exposé (ex. localhost:9092)
• Assurez-vous que le topic configuré correspond au topic utilisé

Exemple minimal

yaml

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

🐰 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.

Format JSON attendu

json

{
  "receiver_email": ["user@example.com"], // string or list of strings
  "email_object": "Sujet",
  "message_text": "Contenu du message"
}

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

• Le conteneur doit être sur le même réseau Docker que RabbitMQ
• Utilisez l'adresse interne (ex. rabbitmq:5672) sur le même réseau
• Pour les clients externes, utilisez l'endpoint exposé (ex. localhost:5672)
• Vérifiez que l'exchange et la routing key correspondent aux producteurs
• Le service déclare automatiquement l'exchange de type TOPIC et la queue durable

🚨 Sécurité et bonnes pratiques

🔐

Mots de passe d'application

Utilisez des mots de passe d'application pour Gmail (pas votre mot de passe principal)

🛡️

Limitez l'accès

Limitez l'accès au port 9876 dans votre pare-feu

🔒

HTTPS en production

Utilisez HTTPS en production avec un reverse proxy (nginx, traefik)

🗝️

Stockage des secrets

Stockez les secrets de manière sécurisée (Docker secrets, variables d'environnement chiffrées)

📊

Surveillance

Surveillez régulièrement le statut SMTP avec l'endpoint /api/smtp-status

Nous Contacter

Vous avez des questions ou besoin d'assistance ? Remplissez le formulaire ci-dessous et nous vous répondrons rapidement.