Skip to content
プロジェクト

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 ネイティブ・メールテストゲートウェイ。

Go Test Coverage Go Report Card Go Version Latest Release License MailDev Workflows

🌍 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 プレビュー

🎥 デモ動画

デモ動画

✨ 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 や完全互換を主張しません。

  • ローカルツール — 組み込み /webhooks editor でルールを作成し、従来 プログラムは 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 eligible 0.15, 0, and latest aliases.
  • 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 ID
  • GET /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 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 - キャッシュ済み依存関係 readiness
  • GET /api/v1/version - バージョン情報
  • GET /api/v1/ws - WebSocket connection
  • GET /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:

  1. Default format: 8-character random string (e.g., aB3dEfGh)
  2. 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:

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

📄 License

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

🙏 Acknowledgments

📚 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 — 開発、CI、自動化、AI Agent のためのセルフホスト型メールテストゲートウェイ。🦉

Previous release: OwlMail 0.14.0.