OwlMail

OwlMail 0.15.0 supports standalone operation by default. Normal binaries retain the multiuser startup gate; test fixtures are not linked into release binaries or normal container images. Artifact availability and verification follow the release workflow.

🦉 Une passerelle de test d’e-mails auto-hébergée et AI-native pour le développement, la CI, l’automatisation et les agents de code.

🌍 Languages / 语言 / Sprachen / Langues / Lingue / 言語 / 언어

English | 简体中文 | Deutsch | Français | Italiano | 日本語 | 한국어

OwlMail capture les e-mails applicatifs avant leur arrivée dans une vraie boîte et les transforme en données de test déterministes et inspectables. Les développeurs utilisent l’interface Web, les tests l’API REST versionnée et OpenAPI, les automatisations des événements durables et les agents AI un MCP borné en lecture seule.

Utilisateur	Interface	Workflow typique
Développeurs	Interface Web et notifications navigateur	Inspecter HTML, texte, en-têtes, source, liens et pièces jointes
Tests et CI	API REST, OpenAPI 3.1 et WebSocket	Vérifier les e-mails d’inscription, de réinitialisation et de notification
Automatisation	Webhooks signés et Redis Streams optionnel	Transformer un e-mail validé en événement récupérable
Agents de code AI	MCP en lecture seule via Streamable HTTP ou stdio	Rechercher, récupérer et attendre un e-mail sans accès destructif
Exploitation SMTP	Relais manuel et automatique	Transférer un e-mail de test avec des politiques TLS explicites

📸 Aperçu

Aperçu OwlMail

🎥 Vidéo de démonstration

Vidéo de démonstration

✨ Pourquoi OwlMail

Capture déterministe — EML, métadonnées et pièces jointes sont préparés avant qu’un commit atomique ne rende le message visible.
Prêt pour les tests d’intégration — /api/v1, OpenAPI 3.1, WebSocket natif, sondes de santé, recherche, filtrage et export.
AI-native sans dépendre de l’AI — Le MCP désactivé par défaut expose sept outils fermés en lecture seule, des ressources bornées, des prompts et wait_for_email événementiel via HTTP ; stdio parcourt le dossier environ toutes les 500 ms. OwlMail ne requiert aucun LLM.
Automatisation durable — Outbox Webhook locale, Redis Streams optionnel, HMAC, identifiants stables, reprises bornées et arrêt progressif.
Exploitation explicite — Limites SMTP, persistance, pièces jointes S3 optionnelles, index SQLite, métriques Prometheus et logs JSON.
Livraison contrôlée — Les tâches Relay asynchrones natives sont persistantes si un répertoire mail est configuré (sinon en mémoire) et utilisent des instantanés immuables, DATA en streaming et des modes TLS explicites.
Migration claire — Façades REST MailDev et MailCatcher optionnelles, sans prétendre implémenter Socket.IO ni une équivalence exacte.
Outils locaux — Créez les règles dans l’éditeur /webhooks intégré et utilisez le guide sendmail pour les programmes existants. Les tests source et navigateur utilisent Bun ; le binaire déployé n’en dépend pas.

OwlMail 0.15.0

v0.15.0 prend en charge le fonctionnement autonome. Elle inclut les tests de livraison par curseur, les assertions de contenu et de pièces jointes, l’historique et les reprises confirmées, la palette de commandes, le diagnostic hors ligne et le mode SMTP-only avec des sondes adaptées à la configuration. Notes de version 0.15.0 · Version précédente 0.14.0.

[!IMPORTANT] OwlMail cible le développement, les tests, la CI et les réseaux internes de confiance ; ce n’est ni un MTA public de production ni un service multi-tenant.

🚀 Quick Start

Installation

Build from Source

# Clone repository
git clone --branch v0.15.0 --depth 1 https://github.com/soulteary/owlmail.git
cd owlmail

# Build
go build -o owlmail ./cmd/owlmail

# Run
./owlmail

Install with Go

go install github.com/soulteary/owlmail/cmd/[email protected]
owlmail

go install place owlmail dans GOBIN ou GOPATH/bin, qui doit être dans PATH. Utilisez alors owlmail au lieu de ./owlmail. ./owlmail désigne un fichier compilé ou téléchargé localement.

Basic Usage

# Start with default configuration (SMTP: 1025, Web: 1080)
./owlmail

# Custom ports
./owlmail -smtp 1025 -web 1080

# Use environment variables
export MAILDEV_SMTP_PORT=1025
export MAILDEV_WEB_PORT=1080
./owlmail

Utilisation Docker

Publiez chaque port du conteneur uniquement sur la boucle locale : écrivez -p 127.0.0.1:1080:1080, et non -p 1080:1080. L'image définit OWLMAIL_WEB_HOST=0.0.0.0 et OWLMAIL_SMTP_HOST=0.0.0.0, ce qui est correct à l'intérieur d'un conteneur — le processus doit accepter les connexions venant de l'extérieur de son espace de noms réseau — mais cela signifie que l'option -p est la seule à décider qui peut atteindre OwlMail. La forme courte publie sur toutes les interfaces de l'hôte, et la règle de pare-feu que la plupart des gens ont écrite ne l'arrête pas : un port publié est atteint par forwarding, donc une règle de la chaîne INPUT comme ufw deny 1080 ne s'y applique pas. Le filtrer demande une règle dans la chaîne DOCKER-USER de Docker, ou son équivalent dans nftables ou firewalld. Cela expose une boîte aux lettres contenant des liens de réinitialisation de mot de passe, des codes de vérification et des jetons, ainsi qu'un port SMTP qui accepte le courrier sans authentification par défaut. Tous les exemples ci-dessous utilisent la forme boucle locale.

Récupérer depuis GitHub Container Registry (Recommandé)

La façon la plus simple d'utiliser OwlMail est de récupérer l'image pré-construite depuis GitHub Container Registry :

# Récupérer la version 0.15.0
docker pull ghcr.io/soulteary/owlmail:0.15.0

# Récupérer l'image d'un commit exact (exemple)
docker pull ghcr.io/soulteary/owlmail:sha-8d3445d

# Exécuter le conteneur
docker run -d \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:1080:1080 \
  -v owlmail-data:/app/mail \
  --name owlmail \
  ghcr.io/soulteary/owlmail:0.15.0

Tags disponibles :

0.15.0 — exact release version. The successful stable release workflow also maintains eligible 0.15, 0, and latest aliases.
sha-<commit> - Image d'un SHA court précis (par exemple sha-8d3445d)
main - Image mobile issue du dernier build de main
latest - Alias mobile de la dernière version stable, jamais modifié par les builds main

Support multi-architecture : L'image prend en charge les architectures linux/amd64 et linux/arm64. Docker récupérera automatiquement la bonne image pour votre plateforme.

Voir toutes les images disponibles : GitHub Packages

Construire depuis les sources

Build de base (Architecture unique)

# Construire l'image pour l'architecture actuelle
docker build -t owlmail .

# Exécuter le conteneur
docker run -d \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:1080:1080 \
  -v owlmail-data:/app/mail \
  --name owlmail \
  owlmail

Build multi-architecture

Pour aarch64 (ARM64) ou d'autres architectures, utilisez Docker Buildx :

# Activer buildx (si ce n'est pas déjà fait)
docker buildx create --use --name multiarch-builder
# Créer une image multiarchitecture et la pousser vers le registre
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t your-registry/owlmail:latest \
  --push .

# Construire pour une architecture spécifique (ex. aarch64/arm64)
docker buildx build \
  --platform linux/arm64 \
  -t owlmail:latest \
  --load .

Note : Le Dockerfile prend maintenant en charge les builds multi-architecture en utilisant les arguments de build TARGETOS et TARGETARCH, qui sont automatiquement définis par Docker Buildx.

📖 Configuration Options

Ce tableau décrit OwlMail 0.15.0, y compris -disable-web. Voir le choix de version et la référence de configuration.

Command Line Arguments

OwlMail 0.15.0: -smtp 0 and -web 0 select OS-assigned ports; -smtps-port 0 still disables SMTPS. See the operations guide for discovery and probes.

Argument	Environment Variable	Default	Description
`-smtp`	`MAILDEV_SMTP_PORT` / `OWLMAIL_SMTP_PORT`	1025	SMTP port
`-ip`	`MAILDEV_IP` / `OWLMAIL_SMTP_HOST`	localhost	SMTP host
`-smtp-max-message-mb`	`OWLMAIL_SMTP_MAX_MESSAGE_MB`	100	Taille maximale des messages entrants en MiB
`-smtp-max-concurrency`	`OWLMAIL_SMTP_MAX_CONCURRENCY`	8	Transactions DATA simultanées par processus pour SMTP, STARTTLS et SMTPS ; `0` signifie illimité ; la saturation renvoie l’erreur temporaire `451 4.3.2`
`-smtp-read-timeout`	`OWLMAIL_SMTP_READ_TIMEOUT`	10s	Délai de lecture des commandes SMTP et de DATA
`-smtp-write-timeout`	`OWLMAIL_SMTP_WRITE_TIMEOUT`	10s	Délai d’écriture des réponses SMTP
`-smtp-max-recipients`	`OWLMAIL_SMTP_MAX_RECIPIENTS`	50	Nombre maximal de destinataires par message
`-disable-web`	`OWLMAIL_DISABLE_WEB`	false	Exécuter SMTP sans écouteur HTTP
`-web`	`MAILDEV_WEB_PORT` / `OWLMAIL_WEB_PORT`	1080	Web API port
`-web-ip`	`MAILDEV_WEB_IP` / `OWLMAIL_WEB_HOST`	localhost	Web API host
`-web-external-url`	`OWLMAIL_WEB_EXTERNAL_URL`	-	Origine HTTP(S) visible par le navigateur pour les liens profonds ; configurez séparément le sous-chemin avec `-base-pathname`
`-web-allowed-origins`	`OWLMAIL_WEB_ALLOWED_ORIGINS`	-	Origines de navigateur supplémentaires acceptées sur l'UI Web et l'API REST, en plus de celles d'OwlMail ; `*` désactive la validation d'origine
`-base-pathname`	`MAILDEV_BASE_PATHNAME` / `OWLMAIL_BASE_PATHNAME`	-	Préfixe de chemin URL tel que `/owlmail`; la racine reste la valeur par défaut
`-maildev-rest-compat`	`OWLMAIL_MAILDEV_REST_COMPAT`	false	Active explicitement la façade REST MailDev sous `/api` ; Socket.IO reste incompatible
`-metrics-enabled`	`OWLMAIL_METRICS_ENABLED`	false	Expose les métriques Prometheus sur `/metrics` sous le chemin de base ; l’authentification Basic Web existante s’applique
`-mcp-enabled`	`OWLMAIL_MCP_ENABLED`	false	Active le point d'accès MCP Streamable HTTP en lecture seule sous `/mcp`
`-mcp-session-timeout`	`OWLMAIL_MCP_SESSION_TIMEOUT`	30m	Ferme les sessions MCP inactives
`-mcp-shutdown-timeout`	`OWLMAIL_MCP_SHUTDOWN_TIMEOUT`	5s	Délai de fermeture des sessions MCP à l'arrêt
`-mcp-allowed-origins`	`OWLMAIL_MCP_ALLOWED_ORIGINS`	-	Origines de navigateur supplémentaires acceptées sur `/mcp`, en plus de celles d'OwlMail ; `*` désactive la validation d'origine
`-mail-directory`	`MAILDEV_MAIL_DIRECTORY` / `OWLMAIL_MAIL_DIR`	-	Mail storage directory
`-mail-retention-days`	`OWLMAIL_MAIL_RETENTION_DAYS`	0	Mail retention days; `0` is unlimited Multiuser rejects nonzero values; use pending-retention-days.
`-mail-max-messages`	`OWLMAIL_MAIL_MAX_MESSAGES`	0	Maximum stored messages; `0` is unlimited Multiuser: hard admission only; 0 selects 100000 messages, without personal eviction.
`-mail-max-disk-mb`	`OWLMAIL_MAIL_MAX_DISK_MB`	0	Maximum mailbox MiB; `0` is unlimited Multiuser: hard admission only; 0 selects 10240 MiB, without personal eviction.
`-mail-cleanup-interval`	`OWLMAIL_MAIL_CLEANUP_INTERVAL`	1h	Background cleanup interval
`-mail-index-path`	`OWLMAIL_MAIL_INDEX_PATH`	-	Chemin facultatif d’un index SQLite reconstructible ; les fichiers EML restent la source de vérité
`-s3-enabled`	`OWLMAIL_S3_ENABLED`	false	Stocker les pièces jointes décodées dans un stockage compatible S3
`-s3-endpoint`	`OWLMAIL_S3_ENDPOINT`	-	Point d’accès S3 personnalisé ; vide utilise AWS S3
`-s3-region`	`OWLMAIL_S3_REGION`	us-east-1	Région S3
`-s3-bucket`	`OWLMAIL_S3_BUCKET`	-	Bucket existant pour les pièces jointes
`-s3-prefix`	`OWLMAIL_S3_PREFIX`	owlmail/attachments	Préfixe des clés d’objet
`-s3-access-key`	`OWLMAIL_S3_ACCESS_KEY`	-	Clé d’accès statique facultative
`-s3-secret-key`	`OWLMAIL_S3_SECRET_KEY`	-	Clé secrète statique facultative
`-s3-session-token`	`OWLMAIL_S3_SESSION_TOKEN`	-	Jeton de session facultatif
`-s3-use-path-style`	`OWLMAIL_S3_USE_PATH_STYLE`	false	Utiliser l’adressage de bucket par chemin
`-s3-startup-check`	`OWLMAIL_S3_STARTUP_CHECK`	false	Arrêter le démarrage si la première vérification S3 en lecture seule échoue
`-s3-health-check-interval`	`OWLMAIL_S3_HEALTH_CHECK_INTERVAL`	30s	Intervalle de rafraîchissement de la disponibilité S3
`-s3-health-check-timeout`	`OWLMAIL_S3_HEALTH_CHECK_TIMEOUT`	5s	Délai maximal de chaque vérification S3
`-web-user`	`MAILDEV_WEB_USER` / `OWLMAIL_WEB_USER`	-	HTTP Basic Auth username
`-web-password`	`MAILDEV_WEB_PASS` / `OWLMAIL_WEB_PASSWORD`	-	HTTP Basic Auth password
`-https`	`MAILDEV_HTTPS` / `OWLMAIL_HTTPS_ENABLED`	false	Enable HTTPS
`-https-cert`	`MAILDEV_HTTPS_CERT` / `OWLMAIL_HTTPS_CERT`	-	HTTPS certificate file
`-https-key`	`MAILDEV_HTTPS_KEY` / `OWLMAIL_HTTPS_KEY`	-	HTTPS private key file
`-outgoing-host`	`MAILDEV_OUTGOING_HOST` / `OWLMAIL_OUTGOING_HOST`	-	Outgoing SMTP host
`-outgoing-port`	`MAILDEV_OUTGOING_PORT` / `OWLMAIL_OUTGOING_PORT`	587	Outgoing SMTP port
`-outgoing-user`	`MAILDEV_OUTGOING_USER` / `OWLMAIL_OUTGOING_USER`	-	Outgoing SMTP username
`-outgoing-pass`	`MAILDEV_OUTGOING_PASS` / `OWLMAIL_OUTGOING_PASSWORD`	-	Outgoing SMTP password
`-outgoing-secure`	`MAILDEV_OUTGOING_SECURE` / `OWLMAIL_OUTGOING_SECURE`	false	Alias MailDev pour TLS implicite/SMTPS
`-outgoing-tls-mode`	`OWLMAIL_OUTGOING_TLS_MODE`	-	Sans valeur : `plain`; sinon `starttls` obligatoire ou `smtps` implicite
`-outgoing-insecure-skip-verify`	`OWLMAIL_OUTGOING_INSECURE_SKIP_VERIFY`	false	Désactive la vérification certificat/hôte (dangereux)
`-outgoing-connect-timeout`	`OWLMAIL_OUTGOING_CONNECT_TIMEOUT`	10s	Délai connexion/accueil
`-outgoing-tls-handshake-timeout`	`OWLMAIL_OUTGOING_TLS_HANDSHAKE_TIMEOUT`	10s	Délai négociation TLS
`-outgoing-auth-timeout`	`OWLMAIL_OUTGOING_AUTH_TIMEOUT`	10s	Délai AUTH
`-outgoing-envelope-timeout`	`OWLMAIL_OUTGOING_ENVELOPE_TIMEOUT`	10s	Délai MAIL/RCPT
`-outgoing-data-timeout`	`OWLMAIL_OUTGOING_DATA_TIMEOUT`	30s	Délai DATA
`-outgoing-quit-timeout`	`OWLMAIL_OUTGOING_QUIT_TIMEOUT`	5s	Délai QUIT
`-auto-relay`	`MAILDEV_AUTO_RELAY` / `OWLMAIL_AUTO_RELAY`	false	Enable auto relay
`-auto-relay-addr`	`MAILDEV_AUTO_RELAY_ADDR` / `OWLMAIL_AUTO_RELAY_ADDR`	-	Auto relay address
`-auto-relay-rules`	`MAILDEV_AUTO_RELAY_RULES` / `OWLMAIL_AUTO_RELAY_RULES`	-	Auto relay rules file
`-webhook-config`	`OWLMAIL_WEBHOOK_CONFIG`	-	JSON webhook forwarding configuration file
`-webhook-max-concurrency`	`OWLMAIL_WEBHOOK_MAX_CONCURRENCY`	8	Livraisons Webhook simultanées ; `0` désactive la limite
`-webhook-redis-url`	`OWLMAIL_WEBHOOK_REDIS_URL`	-	Redis URL for durable webhook delivery
`-webhook-redis-prefix`	`OWLMAIL_WEBHOOK_REDIS_PREFIX`	owlmail:webhooks	Redis Streams key prefix
`-webhook-shutdown-timeout`	`OWLMAIL_WEBHOOK_SHUTDOWN_TIMEOUT`	15s	Graceful webhook drain deadline
`-smtp-user`	`MAILDEV_INCOMING_USER` / `OWLMAIL_SMTP_USER`	-	Nom d’utilisateur SMTP entrant ; avec le mot de passe, rend AUTH obligatoire
`-smtp-password`	`MAILDEV_INCOMING_PASS` / `OWLMAIL_SMTP_PASSWORD`	-	Mot de passe SMTP entrant ; avec le nom d’utilisateur, rend AUTH obligatoire
`-smtp-auth-require-tls`	`OWLMAIL_SMTP_AUTH_REQUIRE_TLS`	false	Refuser PLAIN/LOGIN avant TLS ; nécessite l’activation de SMTP TLS
`-tls`	`MAILDEV_INCOMING_SECURE` / `OWLMAIL_TLS_ENABLED`	false	Enable SMTP TLS
`-tls-cert`	`MAILDEV_INCOMING_CERT` / `OWLMAIL_TLS_CERT`	-	SMTP TLS certificate file
`-tls-key`	`MAILDEV_INCOMING_KEY` / `OWLMAIL_TLS_KEY`	-	SMTP TLS private key file
`-smtps-port`	`OWLMAIL_SMTPS_PORT`	465	Port du listener TLS implicite (SMTPS) lorsque TLS est activé ; `0` ne démarre aucun listener SMTPS
`-log-level`	`MAILDEV_VERBOSE` / `MAILDEV_SILENT` / `OWLMAIL_LOG_LEVEL`	normal	Log level
`-mailcatcher-rest-compat`	`OWLMAIL_MAILCATCHER_REST_COMPAT`	false	Activer la compatibilité REST MailCatcher facultative
`-multiuser-max-pending`	`OWLMAIL_MULTIUSER_MAX_PENDING`	1000	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-multiuser-rcpt-per-minute`	`OWLMAIL_MULTIUSER_RCPT_PER_MINUTE`	60	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-multiuser-auth-per-minute`	`OWLMAIL_MULTIUSER_AUTH_PER_MINUTE`	120	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-multiuser-max-messages`	`OWLMAIL_MULTIUSER_MAX_MESSAGES`	10000	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-multiuser-max-disk-mb`	`OWLMAIL_MULTIUSER_MAX_DISK_MB`	1024	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-pending-retention-days`	`OWLMAIL_PENDING_RETENTION_DAYS`	7	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-pending-empty-retention-hours`	`OWLMAIL_PENDING_EMPTY_RETENTION_HOURS`	24	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-pending-cleanup-interval`	`OWLMAIL_PENDING_CLEANUP_INTERVAL`	1h	Experimental multiuser quota or retention policy; standalone behavior is unchanged
`-mode`	`OWLMAIL_MODE`	standalone	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-identity-namespace`	`OWLMAIL_IDENTITY_NAMESPACE`	main	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-identity-trusted-proxies`	`OWLMAIL_IDENTITY_TRUSTED_PROXIES`	-	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-identity-subject-header`	`OWLMAIL_IDENTITY_SUBJECT_HEADER`	X-Auth-User	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-identity-email-header`	`OWLMAIL_IDENTITY_EMAIL_HEADER`	X-Auth-Email	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-identity-verified-header`	`OWLMAIL_IDENTITY_VERIFIED_HEADER`	X-Auth-Email-Verified	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-claim-policy`	`OWLMAIL_CLAIM_POLICY`	-	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-control-database`	`OWLMAIL_CONTROL_DATABASE`	-	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-system-smtp-accounts-file`	`OWLMAIL_SYSTEM_SMTP_ACCOUNTS_FILE`	-	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-recipient-allowed-domains`	`OWLMAIL_RECIPIENT_ALLOWED_DOMAINS`	-	Experimental multiuser foundation; runtime remains disabled until isolation and recovery are complete
`-config`	`OWLMAIL_CONFIG_FILE`	-	Charger un fichier YAML ou JSON au démarrage ; la CLI et l’environnement sont prioritaires
`-listen-info-file`	`OWLMAIL_LISTEN_INFO_FILE`	-	Development branch: atomically publish actual listener addresses to private JSON; unique path per instance
`-log-format`	`OWLMAIL_LOG_FORMAT`	console	Format des journaux : `console` ou `json`
`-use-uuid-for-email-id`	`OWLMAIL_USE_UUID_FOR_EMAIL_ID`	false	Use UUID for email IDs (default: 8-character random string)

When TLS terminates at a reverse proxy, set OWLMAIL_WEB_EXTERNAL_SCHEME to https.

Une configuration incomplète de l’authentification Web n’est pas désactivée silencieusement :

Valeurs configurées	Identifiants effectifs
Aucune	Authentification désactivée
Nom d’utilisateur uniquement	Le nom d’utilisateur et un mot de passe temporaire aléatoire cryptographiquement sûr de 32 caractères, affiché une fois sur stderr au démarrage
Mot de passe uniquement	Nom d’utilisateur `admin` et mot de passe configuré
Les deux valeurs	Nom d’utilisateur et mot de passe configurés

Un mot de passe généré change à chaque redémarrage. Consultez la sortie du processus (docker logs owlmail pour l’exemple avec conteneur), ou configurez les deux valeurs pour conserver des identifiants stables. OwlMail ne démarre pas si le mot de passe généré ne peut pas être écrit sur stderr. Utilisez Basic Auth uniquement via localhost ou HTTPS.

Environment Variable Compatibility

OwlMail prend en charge les alias MailDev listés dans le tableau et les préfère aux variables OWLMAIL_* correspondantes. Les options MailDev absentes du tableau ne sont pas automatiquement disponibles.

# Use MailDev environment variables directly (recommended)
export MAILDEV_SMTP_PORT=1025
export MAILDEV_WEB_PORT=1080
export MAILDEV_OUTGOING_HOST=smtp.gmail.com
./owlmail

# Or use OwlMail environment variables
export OWLMAIL_SMTP_PORT=1025
export OWLMAIL_WEB_PORT=1080
./owlmail

📡 API Documentation

API Response Format

Les mutations utilisent généralement le format ci-dessous. Les listes et détails renvoient directement les ressources ; HTML, texte, EML, pièces jointes et ZIP ont des formats propres. Voir la référence API.

Success Response:

{
  "code": "EMAIL_DELETED",
  "message": "Email deleted",
  "data": { ... }
}

Error Response:

{
  "code": "EMAIL_NOT_FOUND",
  "error": "EMAIL_NOT_FOUND",
  "message": "Email not found"
}

The code field contains standardized error/success codes that can be used for internationalization. The message field provides English text for backward compatibility. Les échecs de Basic Auth et du garde d'origine navigateur sont des réponses texte 401 ou 403, car ils précèdent les handlers API.

Email ID Format

OwlMail supports two email ID formats, and all API endpoints are compatible with both:

8-character random string: Default format, e.g., aB3dEfGh
UUID format: 36-character standard UUID, e.g., 550e8400-e29b-41d4-a716-446655440000

When using the :id parameter in API requests, you can use either format. For example:

GET /email/aB3dEfGh - Using random string ID
GET /email/550e8400-e29b-41d4-a716-446655440000 - Using UUID ID

Routes de compatibilité de style MailDev

OwlMail conserve des routes non versionnées pour les workflows courants, sans garantir une équivalence exacte avec l'API MailDev actuelle. Consultez la référence API.

Email Operations

GET /email - Get all emails (supports pagination and filtering)
- Query parameters:
  - limit (default: 50, max: 1000) - Number of emails to return
  - offset (default: 0) - Number of emails to skip
  - q - Full-text search query
  - from - Filter by sender email address
  - to - Filter by recipient email address
  - dateFrom - Filter by date from (YYYY-MM-DD format)
  - dateTo - Filter by date to (YYYY-MM-DD format)
  - read - Filter by read status (true/false)
  - sortBy - Sort by field (time, subject, from, size)
  - sortOrder - Sort order (asc, desc, default: desc)
- Example: GET /email?limit=20&offset=0&q=test&sortBy=time&sortOrder=desc
GET /email/:id - Get single email
DELETE /email/:id - Delete single email
DELETE /email/all - Delete all emails
PATCH /email/read-all - Mark all emails as read
PATCH /email/:id/read - Mark single email as read

Email Content

GET /email/:id/html - Get email HTML content
GET /email/:id/attachment/:filename - Download attachment
GET /email/:id/download - Download raw .eml file
GET /email/:id/source - Get email raw source

Email Relay

POST /email/:id/relay - Relay email to configured SMTP server
POST /email/:id/relay/:relayTo - Relay email to specific address

Configuration and System

GET /config - Get configuration information
GET /healthz - Health check
GET /reloadMailsFromDirectory - Reload emails from directory
GET /socket.io - WebSocket connection (standard WebSocket, not Socket.IO)

OwlMail Enhanced API

Email Statistics and Preview

GET /email/stats - Get email statistics
GET /email/preview - Get email preview (lightweight)

Batch Operations

POST /email/batch/delete - Batch delete emails
POST /email/batch/read - Batch mark as read

Email Export

GET /email/export - Export emails as ZIP file

Configuration Management

GET /config/outgoing - Get outgoing configuration
PUT /config/outgoing - Update outgoing configuration
PATCH /config/outgoing - Partially update outgoing configuration

Improved RESTful API (`/api/v1/*`)

OwlMail provides a more standardized RESTful API design:

GET /api/v1/emails - Get all emails (plural resource)
- Query parameters: Same as GET /email (limit, offset, q, from, to, dateFrom, dateTo, read, sortBy, sortOrder)
- Example: GET /api/v1/emails?limit=20&offset=0&q=test&sortBy=time&sortOrder=desc
GET /api/v1/emails/:id - Get single email
DELETE /api/v1/emails/:id - Delete single email
DELETE /api/v1/emails - Delete all emails
DELETE /api/v1/emails/batch - Batch delete
PATCH /api/v1/emails/read - Mark all emails as read
PATCH /api/v1/emails/:id/read - Mark single email as read
PATCH /api/v1/emails/batch/read - Batch mark as read
GET /api/v1/emails/stats - Email statistics
GET /api/v1/emails/preview - Email preview
GET /api/v1/emails/export - Export emails
POST /api/v1/emails/reload - Reload emails
GET /api/v1/settings - Get all settings
GET /api/v1/settings/outgoing - Get outgoing configuration
PUT /api/v1/settings/outgoing - Update outgoing configuration
PATCH /api/v1/settings/outgoing - Partially update outgoing configuration
GET /api/v1/health - Health check
GET /api/v1/ready - Cached dependency readiness check
GET /api/v1/version - Version information
GET /api/v1/ws - WebSocket connection
GET /api/v1/openapi.json - Contrat OpenAPI 3.1 (JSON)
GET /api/v1/openapi.yaml - Contrat OpenAPI 3.1 (YAML)

Le contrat actuel, avec sous-ressources, authentification, réponses et événements WebSocket, se trouve dans la référence API ou dans le contrat OpenAPI. Le contrat servi inclut automatiquement le chemin de base configuré.

🔧 Usage Examples

Basic Usage

# Start OwlMail
./owlmail -smtp 1025 -web 1080

# Configure SMTP in your application
SMTP_HOST=localhost
SMTP_PORT=1025

Configure Email Relay

# Relay to Gmail SMTP
./owlmail \
  -outgoing-host smtp.gmail.com \
  -outgoing-port 587 \
  -outgoing-user [email protected] \
  -outgoing-pass your-password \
  -outgoing-tls-mode starttls

starttls échoue si STARTTLS n’est pas annoncé ou si TLS/certificat échoue, sans repli en clair. smtps active TLS dès la connexion ; AUTH est interdit en mode plain.

Auto Relay Mode

# Create auto relay rules file (relay-rules.json)
cat > relay-rules.json <<EOF
[
  { "allow": "*" },
  { "deny": "*@test.com" },
  { "allow": "[email protected]" }
]
EOF

# Start auto relay
./owlmail \
  -outgoing-host smtp.gmail.com \
  -outgoing-port 587 \
  -outgoing-user [email protected] \
  -outgoing-pass your-password \
  -auto-relay \
  -auto-relay-rules relay-rules.json

Using HTTPS

./owlmail \
  -https \
  -https-cert /path/to/cert.pem \
  -https-key /path/to/key.pem \
  -web 1080

Modes d’authentification SMTP entrante

Sans -smtp-user ni -smtp-password, OwlMail utilise le mode NO AUTH : la remise sans authentification est autorisée et PLAIN/LOGIN acceptent aussi des identifiants arbitraires pour les applications qui imposent des paramètres SMTP. Avec les deux valeurs, SMTP AUTH devient obligatoire. Une seule valeur empêche le démarrage au lieu de revenir silencieusement à NO AUTH.

Activez -smtp-auth-require-tls (ou OWLMAIL_SMTP_AUTH_REQUIRE_TLS=true) avec SMTP TLS pour éviter de transmettre les identifiants en clair. SMTP non chiffré n’annonce ni n’accepte alors PLAIN/LOGIN ; AUTH reste disponible après STARTTLS et via SMTPS. La remise anonyme du mode NO AUTH reste inchangée. Sans configuration SMTP TLS activée et utilisable, cette option empêche le démarrage.

[!WARNING] NO AUTH ne fournit volontairement aucun contrôle d’accès. PLAIN/LOGIN restent utilisables sans TLS pour le développement ; activez TLS avant d’utiliser de vrais identifiants et isolez l’écoute SMTP.

Using TLS

./owlmail \
  -tls \
  -tls-cert /path/to/cert.pem \
  -tls-key /path/to/key.pem \
  -smtp 1025

Note: When TLS is enabled, OwlMail also starts an SMTPS server that uses a direct TLS connection (no STARTTLS required) in addition to the regular SMTP server. Its port comes from -smtps-port or OWLMAIL_SMTPS_PORT and defaults to the privileged port 465, which a process that does not run as root cannot bind; the published container image runs as a non-root user. Set -smtps-port to an unprivileged port, or to 0 to start no SMTPS listener and keep STARTTLS on the SMTP port. A failed SMTPS bind stops startup instead of leaving the port silently unserved.

Using UUID for Email IDs

OwlMail supports two email ID formats:

Default format: 8-character random string (e.g., aB3dEfGh)
UUID format: 36-character standard UUID (e.g., 550e8400-e29b-41d4-a716-446655440000)

Using UUID format provides better uniqueness and traceability, especially useful for integration with external systems.

# Enable UUID using command line flag
./owlmail -use-uuid-for-email-id

# Enable UUID using environment variable
export OWLMAIL_USE_UUID_FOR_EMAIL_ID=true
./owlmail

# Use with other configurations
./owlmail \
  -use-uuid-for-email-id \
  -smtp 1025 \
  -web 1080

Notes:

Default uses 8-character random string, compatible with MailDev behavior
When UUID is enabled, all newly received emails will use UUID format IDs
The API supports both ID formats, allowing normal query, delete, and operation of emails
Existing email ID formats will not change; only new emails will use the new ID format

🔄 Migrating from MailDev

OwlMail couvre des workflows courants de MailDev, mais les clients actuels peuvent nécessiter des adaptations explicites. Suivez le guide de migration.

1. Environment Variable Compatibility

OwlMail accepte les variables MailDev listées dans le tableau. Vérifiez chacune de celles utilisées par votre déploiement :

# MailDev configuration
export MAILDEV_SMTP_PORT=1025
export MAILDEV_WEB_PORT=1080
export MAILDEV_OUTGOING_HOST=smtp.gmail.com

# OwlMail peut aussi lire ces variables listées
./owlmail

2. API Compatibility

Les clients REST existants peuvent activer explicitement la façade MailDev, désactivée par défaut. Les nouvelles intégrations doivent utiliser l'API OwlMail versionnée. La façade n'ajoute pas de compatibilité Socket.IO :

# Client REST MailDev existant
OWLMAIL_MAILDEV_REST_COMPAT=true ./owlmail
curl http://localhost:1080/api/email

# Nouvelle intégration OwlMail
curl http://localhost:1080/api/v1/emails

3. WebSocket Adaptation

If using WebSocket, you need to change from Socket.IO to standard WebSocket:

// MailDev (Socket.IO)
const socket = io('/socket.io');
socket.on('newMail', (email) => { /* ... */ });

// OwlMail (Standard WebSocket)
const ws = new WebSocket('ws://localhost:1080/socket.io');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'new') { /* ... */ }
};

For detailed migration guide, see: OwlMail × MailDev × MailCatcher × Mailpit : guide des fonctionnalités, de l'API et de la migration

🧪 Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for specific packages
go test ./internal/api/...
go test ./internal/mailserver/...

📦 Project Structure

OwlMail/
├── cmd/
│   └── owlmail/          # Main program entry
├── internal/
│   ├── api/              # Web API implementation
│   ├── common/           # Common utilities (logging, error handling)
│   ├── maildev/          # MailDev compatibility layer
│   ├── mailserver/       # SMTP server implementation
│   ├── outgoing/         # Email relay implementation
│   ├── types/            # Type definitions
│   └── webhook/          # Webhook filtering, templates, signing, and delivery
├── docs/                 # API, operations, webhook, and migration documentation
├── examples/             # Runnable integration examples
├── tests/                # Browser and documentation contract tests
├── web/                  # Web frontend files
├── go.mod                # Go module definition
└── README.md             # This document

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

MailDev - Original project inspiration
emersion/go-smtp - SMTP server library
emersion/go-message - Email parsing library
Fiber - Web framework
gorilla/websocket - WebSocket library

📚 Related Documentation

🐛 Issue Reporting

If you encounter any issues or have suggestions, please submit them in GitHub Issues.

⭐ Star History

If this project helps you, please give it a Star ⭐!

OwlMail — une passerelle de test d’e-mails auto-hébergée pour le développement, la CI, l’automatisation et les agents AI. 🦉

Previous release: OwlMail 0.14.0.

Progression mesurée des étoiles

À propos

README.fr.md

OwlMail

🌍 Languages / 语言 / Sprachen / Langues / Lingue / 言語 / 언어

📸 Aperçu

🎥 Vidéo de démonstration

✨ Pourquoi OwlMail

OwlMail 0.15.0

🚀 Quick Start

Installation

Build from Source

Install with Go

Basic Usage

Utilisation Docker

Récupérer depuis GitHub Container Registry (Recommandé)

Construire depuis les sources

Build de base (Architecture unique)

Build multi-architecture

📖 Configuration Options

Command Line Arguments

Environment Variable Compatibility

📡 API Documentation

API Response Format

Email ID Format

Routes de compatibilité de style MailDev

Email Operations

Email Content

Email Relay

Configuration and System

OwlMail Enhanced API

Email Statistics and Preview

Batch Operations

Email Export

Configuration Management

Improved RESTful API (/api/v1/*)

🔧 Usage Examples

Basic Usage

Configure Email Relay

Auto Relay Mode

Using HTTPS

Modes d’authentification SMTP entrante

Using TLS

Using UUID for Email IDs

🔄 Migrating from MailDev

1. Environment Variable Compatibility

2. API Compatibility

3. WebSocket Adaptation

🧪 Testing

📦 Project Structure

🤝 Contributing

📄 License

🙏 Acknowledgments

📚 Related Documentation

🐛 Issue Reporting

⭐ Star History

Improved RESTful API (`/api/v1/*`)