soulteary/owlmail has 76 GitHub stars and 13 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 15:58 UTC. Last push 2026-11-13.
計測したスター増加
- 24時間
- 0
- 7日間
- 更新が遅れています
- 15日間
- 更新が遅れています
- 1か月
- 更新が遅れています
期間ごとの純増数です。期間は重複しており、日別の値ではありません。未計測の値は空欄です。スター数は注目度の指標であり、品質の保証ではありません。
概要
Self-hosted email testing gateway for developers, CI, and coding agents: capture, inspect, wait for, validate, and route SMTP mail via Web UI, REST, Webhooks, WebSocket, and read-only MCP.
セルフホストREADME.ja.md
オリジナル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.
🦉 開発、CI、自動化、コーディング Agent のためのセルフホスト型 AI ネイティブ・メールテストゲートウェイ。
🌍 Languages / 语言 / Sprachen / Langues / Lingue / 言語 / 언어
OwlMail はアプリケーションメールを実際の受信箱へ届く前に捕捉し、決定論的で 検証可能なテストデータに変換します。開発者は Web UI、テストはバージョン化 REST API と OpenAPI、自動化は永続イベント、AI Agent は境界が明確な読み取り 専用 MCP を利用できます。
| 利用者 | インターフェース | 代表的なワークフロー |
|---|---|---|
| 開発者 | Web UI とブラウザ通知 | HTML、テキスト、Header、ソース、リンク、添付を確認 |
| テストと CI | REST API、OpenAPI 3.1、WebSocket | 登録、パスワードリセット、通知メールを検証 |
| 自動化 | 署名付き Webhook、任意の Redis Streams | コミット済みメールを復旧可能なイベントへ変換 |
| AI コーディング Agent | Streamable HTTP / stdio の読み取り専用 MCP | 破壊的権限なしでメールを検索、取得、待機 |
| SMTP 運用 | 手動・自動 Relay | 明示的な TLS と再試行ポリシーでテストメールを転送 |

📸 プレビュー

🎥 デモ動画

✨ OwlMail を選ぶ理由
決定論的な捕捉 — EML、メタデータ、添付を staging し、原子的な commit が完了してから API とイベントへ公開します。
統合テスト対応 —
/api/v1、OpenAPI 3.1、ネイティブ WebSocket、 health/readiness、検索、フィルター、エクスポートを提供します。AI ネイティブで AI 非依存 — 既定で無効の MCP は、7 個の閉じた読み取り 専用 Tool、上限付き Resource、Prompt、HTTP のイベント駆動
wait_for_emailを提供します。 stdio は約 500 ms ごとにディレクトリをスキャンします。OwlMail 自体は LLM を必要としません。永続的な自動化 — ローカル Webhook outbox、任意の Redis Streams、HMAC、 安定した配信 ID、有限再試行、graceful drain。
明示的な運用境界 — SMTP 容量制限、永続化、任意の S3 添付、SQLite index、Prometheus metrics、JSON log。
制御された配信 — ネイティブ非同期 Relay job は mail directory 設定時のみ 永続化され(未設定時はメモリ内)、不変 snapshot、ストリーミング DATA、 明示的 TLS mode、状態照会を利用します。
移行パス — MailDev / MailCatcher REST facade は既定で無効であり、 Socket.IO や完全互換を主張しません。
ローカルツール — 組み込み
/webhookseditor でルールを作成し、従来 プログラムは sendmail ガイドを参照できます。ソースと ブラウザテストは Bun を使用しますが、配布バイナリの実行には不要です。
OwlMail 0.15.0
v0.15.0 は単独実行をサポートします。カーソルによる配信テスト、本文と添付の検証、配信履歴と確認付き再試行、コマンドパレット、オフライン診断、設定に対応したヘルスチェックと SMTP-only を提供します。0.15.0 リリースノート · 前のバージョン 0.14.0。
[!IMPORTANT] OwlMail は開発、テスト、CI、信頼できる内部ネットワーク向けです。公開本番 MTA、exactly-once queue、マルチテナントメールサービスではありません。
🚀 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 は GOBIN または GOPATH/bin に owlmail を配置します。このディレクトリを PATH に追加し、./owlmail ではなく owlmail を使ってください。./owlmail はローカルでビルドまたはダウンロードしたファイルを指します。
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
Docker の使用
コンテナーのポートは必ずループバックにのみ公開してください。-p 1080:1080 では
なく -p 127.0.0.1:1080:1080 と書きます。 イメージは
OWLMAIL_WEB_HOST=0.0.0.0 と OWLMAIL_SMTP_HOST=0.0.0.0 を設定しており、これは
コンテナー内部では正しい設定です(プロセスはネットワーク名前空間の外から届く接続を
受け付ける必要があります)。そのため、誰が OwlMail に到達できるかを決めるのは -p
だけになります。短い書き方はホストのすべてのインターフェースで公開し、ホストの
ファイアウォールで多くの人が書いているルールでは止められません。公開されたポートは
フォワーディング経由で到達するため、ufw deny 1080 のような INPUT チェーンの
ルールは適用されないからです。フィルターするには Docker の DOCKER-USER チェーンに
ルールを追加するか、nftables や firewalld で同等の設定が必要です。これは、
パスワードリセットリンク・確認コード・トークンを含むメールボックスと、既定で認証
なしにメールを受け取る SMTP ポートを公開することになります。以下の例はすべて
ループバック形式を使用しています。
GitHub Container Registry から取得(推奨)
OwlMail を使用する最も簡単な方法は、GitHub Container Registry から事前に構築されたイメージを取得することです:
# リリース 0.15.0 を取得
docker pull ghcr.io/soulteary/owlmail:0.15.0
# 特定コミットのイメージを取得(例)
docker pull ghcr.io/soulteary/owlmail:sha-8d3445d
# コンテナを実行
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
利用可能なタグ:
0.15.0— exact release version. The successful stable release workflow also maintains eligible0.15,0, andlatestaliases.sha-<commit>- 特定の短いコミット SHA のイメージ(例:sha-8d3445d)main- 最新のmainビルドに追随する可変イメージlatest- 最新の安定版に追随する可変エイリアス。mainのビルドでは更新されません
マルチアーキテクチャサポート:
イメージは linux/amd64 と linux/arm64 の両方のアーキテクチャをサポートしています。Docker は自動的にプラットフォームに適したイメージを取得します。
利用可能なすべてのイメージを表示: GitHub Packages
ソースからビルド
基本ビルド(単一アーキテクチャ)
# 現在のアーキテクチャ用のイメージをビルド
docker build -t owlmail .
# コンテナを実行
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
マルチアーキテクチャビルド
aarch64 (ARM64) またはその他のアーキテクチャの場合、Docker Buildx を使用してください:
# buildx を有効化(まだ有効でない場合)
docker buildx create --use --name multiarch-builder
# マルチアーキテクチャのイメージをビルドしてレジストリへプッシュ
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t your-registry/owlmail:latest \
--push .
# 特定のアーキテクチャ用にビルド(例:aarch64/arm64)
docker buildx build \
--platform linux/arm64 \
-t owlmail:latest \
--load .
注意:Dockerfile は、Docker Buildx によって自動的に設定される TARGETOS と TARGETARCH ビルド引数を使用して、マルチアーキテクチャビルドをサポートするようになりました。
📖 Configuration Options
この表は -disable-web を含む OwlMail 0.15.0 の設定です。バージョン選択と設定リファレンスを参照してください。
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 | 受信メッセージの最大サイズ(MiB) |
-smtp-max-concurrency |
OWLMAIL_SMTP_MAX_CONCURRENCY |
8 | SMTP・STARTTLS・SMTPS 全体でのプロセス単位の同時 DATA トランザクション数。0 は無制限。上限時は再試行可能な 451 4.3.2 を返す |
-smtp-read-timeout |
OWLMAIL_SMTP_READ_TIMEOUT |
10s | SMTP コマンドおよび DATA の読み取りタイムアウト |
-smtp-write-timeout |
OWLMAIL_SMTP_WRITE_TIMEOUT |
10s | SMTP 応答の書き込みタイムアウト |
-smtp-max-recipients |
OWLMAIL_SMTP_MAX_RECIPIENTS |
50 | 1 メッセージあたりの最大受信者数 |
-disable-web |
OWLMAIL_DISABLE_WEB |
false | HTTP リスナーを起動せず SMTP のみ実行 |
-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 |
- | 生成するメール深層リンク用のブラウザー公開 HTTP(S) origin。プロキシのサブパスは -base-pathname で別途設定 |
-web-allowed-origins |
OWLMAIL_WEB_ALLOWED_ORIGINS |
- | OwlMail 自身のオリジンに加えて Web UI と REST API で受け入れるブラウザーオリジン。* はオリジン検証を無効化 |
-base-pathname |
MAILDEV_BASE_PATHNAME / OWLMAIL_BASE_PATHNAME |
- | /owlmail などの URL パス接頭辞。既定はルートパス |
-maildev-rest-compat |
OWLMAIL_MAILDEV_REST_COMPAT |
false | MailDev /api REST facade を明示的に有効化。Socket.IO は引き続き非互換 |
-metrics-enabled |
OWLMAIL_METRICS_ENABLED |
false | ベースパス配下の /metrics で Prometheus メトリクスを公開。Web Basic Auth 設定時は同じ認証で保護 |
-mcp-enabled |
OWLMAIL_MCP_ENABLED |
false | /mcp で読み取り専用 MCP Streamable HTTP エンドポイントを有効化 |
-mcp-session-timeout |
OWLMAIL_MCP_SESSION_TIMEOUT |
30m | アイドル状態の MCP セッションを終了 |
-mcp-shutdown-timeout |
OWLMAIL_MCP_SHUTDOWN_TIMEOUT |
5s | シャットダウン時に MCP セッションを終了する期限 |
-mcp-allowed-origins |
OWLMAIL_MCP_ALLOWED_ORIGINS |
- | OwlMail 自身のオリジンに加えて /mcp で受け入れるブラウザーオリジン。* はオリジン検証を無効化 |
-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 |
- | 再構築可能な SQLite メールボックス索引の任意パス。EML ファイルが引き続き正本 |
-s3-enabled |
OWLMAIL_S3_ENABLED |
false | デコード済み添付ファイルを S3 互換ストレージに保存 |
-s3-endpoint |
OWLMAIL_S3_ENDPOINT |
- | カスタム S3 エンドポイント。空の場合は AWS S3 |
-s3-region |
OWLMAIL_S3_REGION |
us-east-1 | S3 リージョン |
-s3-bucket |
OWLMAIL_S3_BUCKET |
- | 添付ファイル用の既存バケット |
-s3-prefix |
OWLMAIL_S3_PREFIX |
owlmail/attachments | オブジェクトキープレフィックス |
-s3-access-key |
OWLMAIL_S3_ACCESS_KEY |
- | 任意の静的アクセスキー |
-s3-secret-key |
OWLMAIL_S3_SECRET_KEY |
- | 任意の静的シークレットキー |
-s3-session-token |
OWLMAIL_S3_SESSION_TOKEN |
- | 任意のセッショントークン |
-s3-use-path-style |
OWLMAIL_S3_USE_PATH_STYLE |
false | パス形式のバケットアドレスを使用 |
-s3-startup-check |
OWLMAIL_S3_STARTUP_CHECK |
false | 最初の読み取り専用 S3 バケット確認に失敗した場合は起動を中止 |
-s3-health-check-interval |
OWLMAIL_S3_HEALTH_CHECK_INTERVAL |
30s | バックグラウンド S3 readiness 確認間隔 |
-s3-health-check-timeout |
OWLMAIL_S3_HEALTH_CHECK_TIMEOUT |
5s | 各 S3 readiness 確認のタイムアウト |
-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 | MailDev 互換の暗黙 TLS/SMTPS エイリアス |
-outgoing-tls-mode |
OWLMAIL_OUTGOING_TLS_MODE |
- | 未設定は plain、または必須 starttls/暗黙 smtps |
-outgoing-insecure-skip-verify |
OWLMAIL_OUTGOING_INSECURE_SKIP_VERIFY |
false | 証明書・ホスト名検証を無効化(危険) |
-outgoing-connect-timeout |
OWLMAIL_OUTGOING_CONNECT_TIMEOUT |
10s | 接続/グリーティング期限 |
-outgoing-tls-handshake-timeout |
OWLMAIL_OUTGOING_TLS_HANDSHAKE_TIMEOUT |
10s | TLS ハンドシェイク期限 |
-outgoing-auth-timeout |
OWLMAIL_OUTGOING_AUTH_TIMEOUT |
10s | AUTH 期限 |
-outgoing-envelope-timeout |
OWLMAIL_OUTGOING_ENVELOPE_TIMEOUT |
10s | MAIL/RCPT 期限 |
-outgoing-data-timeout |
OWLMAIL_OUTGOING_DATA_TIMEOUT |
30s | DATA 期限 |
-outgoing-quit-timeout |
OWLMAIL_OUTGOING_QUIT_TIMEOUT |
5s | 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 | 同時 Webhook 配信数。0 は上限なし |
-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 |
- | 受信 SMTP ユーザー名。パスワードと同時設定すると AUTH を必須化 |
-smtp-password |
MAILDEV_INCOMING_PASS / OWLMAIL_SMTP_PASSWORD |
- | 受信 SMTP パスワード。ユーザー名と同時設定すると AUTH を必須化 |
-smtp-auth-require-tls |
OWLMAIL_SMTP_AUTH_REQUIRE_TLS |
false | TLS 確立前の PLAIN/LOGIN を拒否。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 | TLS 有効時の暗黙 TLS(SMTPS)リスナーのポート。0 を指定すると SMTPS リスナーを起動しない |
-log-level |
MAILDEV_VERBOSE / MAILDEV_SILENT / OWLMAIL_LOG_LEVEL |
normal | Log level |
-mailcatcher-rest-compat |
OWLMAIL_MAILCATCHER_REST_COMPAT |
false | オプションの MailCatcher REST 互換 API を有効化 |
-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 |
- | 起動時に YAML または JSON を読み込む。CLI と環境変数を優先 |
-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 | ログ出力形式:console または 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.
Web 認証の設定値が片方だけの場合でも、認証が暗黙に無効になることはありません。
| 設定値 | 実際の認証情報 |
|---|---|
| どちらも未設定 | 認証は無効 |
| ユーザー名のみ | 指定したユーザー名と、暗号学的に安全な 32 文字の一時パスワード。起動時に一度だけ stderr に出力されます |
| パスワードのみ | ユーザー名 admin と指定したパスワード |
| 両方 | 指定したユーザー名とパスワード |
生成されたパスワードは再起動ごとに変わります。プロセス出力
(コンテナ例では docker logs owlmail)で確認するか、固定した認証情報が
必要な場合は両方を設定してください。生成したパスワードを stderr に出力
できない場合、OwlMail は起動に失敗します。Basic Auth は localhost または
HTTPS 経由でのみ使用してください。
Environment Variable Compatibility
OwlMail は表に記載された MailDev 環境変数エイリアスをサポートし、対応する
OWLMAIL_* より優先します。記載のない MailDev オプションは自動的には使えません。
# 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
変更操作は通常、以下の形式です。一覧と詳細はリソースを直接返し、HTML、テキスト、EML、添付、ZIP は個別の形式です。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.
Basic Auth とブラウザー Origin ガードによる拒否は API ハンドラー
より前に発生するため、プレーンテキストの 401 または 403 になります。
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 IDGET /email/550e8400-e29b-41d4-a716-446655440000- Using UUID ID
MailDev 風互換ルート
OwlMail は一般的なワークフロー用に非バージョンルートを残していますが、現在の MailDev API と完全に同じではありません。 API リファレンスを参照してください。
Email Operations
GET /email- Get all emails (supports pagination and filtering)- Query parameters:
limit(default: 50, max: 1000) - Number of emails to returnoffset(default: 0) - Number of emails to skipq- Full-text search queryfrom- Filter by sender email addressto- Filter by recipient email addressdateFrom- 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
- Query parameters:
GET /email/:id- Get single emailDELETE /email/:id- Delete single emailDELETE /email/all- Delete all emailsPATCH /email/read-all- Mark all emails as readPATCH /email/:id/read- Mark single email as read
Email Content
GET /email/:id/html- Get email HTML contentGET /email/:id/attachment/:filename- Download attachmentGET /email/:id/download- Download raw .eml fileGET /email/:id/source- Get email raw source
Email Relay
POST /email/:id/relay- Relay email to configured SMTP serverPOST /email/:id/relay/:relayTo- Relay email to specific address
Configuration and System
GET /config- Get configuration informationGET /healthz- Health checkGET /reloadMailsFromDirectory- Reload emails from directoryGET /socket.io- WebSocket connection (standard WebSocket, not Socket.IO)
OwlMail Enhanced API
Email Statistics and Preview
GET /email/stats- Get email statisticsGET /email/preview- Get email preview (lightweight)
Batch Operations
POST /email/batch/delete- Batch delete emailsPOST /email/batch/read- Batch mark as read
Email Export
GET /email/export- Export emails as ZIP file
Configuration Management
GET /config/outgoing- Get outgoing configurationPUT /config/outgoing- Update outgoing configurationPATCH /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
- Query parameters: Same as
GET /api/v1/emails/:id- Get single emailDELETE /api/v1/emails/:id- Delete single emailDELETE /api/v1/emails- Delete all emailsDELETE /api/v1/emails/batch- Batch deletePATCH /api/v1/emails/read- Mark all emails as readPATCH /api/v1/emails/:id/read- Mark single email as readPATCH /api/v1/emails/batch/read- Batch mark as readGET /api/v1/emails/stats- Email statisticsGET /api/v1/emails/preview- Email previewGET /api/v1/emails/export- Export emailsPOST /api/v1/emails/reload- Reload emailsGET /api/v1/settings- Get all settingsGET /api/v1/settings/outgoing- Get outgoing configurationPUT /api/v1/settings/outgoing- Update outgoing configurationPATCH /api/v1/settings/outgoing- Partially update outgoing configurationGET /api/v1/health- Health checkGET /api/v1/ready- キャッシュ済み依存関係 readinessGET /api/v1/version- バージョン情報GET /api/v1/ws- WebSocket connectionGET /api/v1/openapi.json- OpenAPI 3.1 コントラクト (JSON)GET /api/v1/openapi.yaml- OpenAPI 3.1 コントラクト (YAML)
サブリソース、認証、レスポンス、WebSocket イベントを含む現在の仕様は API リファレンスまたは OpenAPI コントラクトを参照してください。配信される コントラクトには設定済みのベースパスが自動的に含まれます。
🔧 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 は STARTTLS が通知されない場合や TLS/証明書検証の失敗時に
終了し、平文へ降格しません。smtps は接続開始時から TLS を使用し、
plain モードでは AUTH を許可しません。
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
受信 SMTP 認証モード
-smtp-user と -smtp-password をどちらも設定しない場合、既定の NO
AUTH モードになります。未認証の配送に加え、SMTP 設定を必須とするアプリの
ために任意の PLAIN/LOGIN 認証情報も受け入れます。両方を設定すると SMTP AUTH
が必須になります。片方だけの設定は NO AUTH に戻らず、起動エラーになります。
認証情報を平文接続で送信させない場合は、SMTP TLS とともに
-smtp-auth-require-tls(または OWLMAIL_SMTP_AUTH_REQUIRE_TLS=true)を
有効にします。平文 SMTP では PLAIN/LOGIN を通知せず、受け付けませんが、
STARTTLS 後および SMTPS では AUTH を利用できます。NO AUTH モードの匿名配送は
変わりません。有効かつ利用可能な SMTP TLS 設定がない場合、このオプションを
有効にすると起動に失敗します。
[!WARNING] NO AUTH は意図的にアクセス制御を提供しません。開発互換性のため PLAIN/LOGIN は TLS なしでも使用できるため、実際の認証情報を使う前に TLS を 有効化し、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 は一般的な MailDev ワークフローを扱いますが、現在のクライアントには 明示的な修正が必要な場合があります。 移行ガイドに従ってください。
1. Environment Variable Compatibility
OwlMail は設定表に記載された MailDev 変数を受け付けます。実際に使用する変数を すべて確認してください:
# MailDev configuration
export MAILDEV_SMTP_PORT=1025
export MAILDEV_WEB_PORT=1080
export MAILDEV_OUTGOING_HOST=smtp.gmail.com
# OwlMail もこれらの記載済み変数を読み取れる
./owlmail
2. API Compatibility
既存の REST クライアントは、デフォルトで無効な MailDev facade を明示的に 有効化できます。新規連携ではバージョン付き OwlMail API を使用してください。 facade に Socket.IO 互換性は含まれません:
# 既存の MailDev REST クライアント
OWLMAIL_MAILDEV_REST_COMPAT=true ./owlmail
curl http://localhost:1080/api/email
# 新規 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: 機能・API・移行ガイド
🧪 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
- OwlMail 0.15.0 リリースノート (中文)
- 統合テスト、CI、AI Agent (中文)
- MCP リファレンス、アーキテクチャ、セキュリティモデル
- 実行可能なテスト例
- OwlMail 0.9.0 リリースノート (中文)
- 変更履歴
- OwlMail × MailDev × MailCatcher × Mailpit: 機能・API・移行ガイド
- API リファレンス (English)
- 運用・トラブルシューティング (English)
- Webhook 転送 (English)
- リリース手順 (English)
- API リファクタリング記録(履歴)
🐛 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 — 開発、CI、自動化、AI Agent のためのセルフホスト型メールテストゲートウェイ。🦉
Previous release: OwlMail 0.14.0.