feat: add deliver to stdout feature for automated testing and CI/CD integration (#1909)

* Initial plan

* feat: add deliver to stdout feature with configurable mailboxes and exit after messages

Co-authored-by: rnwood <1327895+rnwood@users.noreply.github.com>

* docs: add documentation for deliver to stdout feature

Co-authored-by: rnwood <1327895+rnwood@users.noreply.github.com>

* Document

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: rnwood <1327895+rnwood@users.noreply.github.com>
Co-authored-by: smtp4dev-automation <noreply@github.com>

Author: 3 people

Rnwood.Smtp4dev/CommandLineParser.cs

@@ -70,7 +70,9 @@ public static MapOptions<CommandLineOptions> TryParseCommandLine(IEnumerable<str
                 { "sslprotocols=", "Specifies the SSL/TLS protocol version(s) that will be allowed. Separate with commas. See https://learn.microsoft.com/en-us/dotnet/api/system.security.authentication.sslprotocols?view=net-9.0", data => map.Add(data, x => x.ServerOptions.SslProtocols)  },
                 { "tlsciphersuites=", "Specifies the TLS cipher suites to be allowed. Not supported on Windows. Separate with commas. See https://learn.microsoft.com/en-us/dotnet/api/system.net.security.tlsciphersuite?view=net-9.0", data => map.Add(data, x => x.ServerOptions.TlsCipherSuites) },
                 { "HtmlValidateConfigfile=", "Defines path to a config file used for HTML validation. See https://html-validate.org/usage/index.html#configuration", data => map.Add(File.ReadAllText(data), x => x.ServerOptions.HtmlValidateConfig) },
-                { "maxmessagesize=", "Defines the maximum message size in bytes accepted by the SMTP server", data => map.Add(data, x => x.ServerOptions.MaxMessageSize) }
+                { "maxmessagesize=", "Defines the maximum message size in bytes accepted by the SMTP server", data => map.Add(data, x => x.ServerOptions.MaxMessageSize) },
+                { "delivertostdout=", "Specifies mailboxes (comma-separated) or '*' to output received raw message content to stdout", data => map.Add(data, x => x.ServerOptions.DeliverToStdout) },
+                { "exitafter=", "Specifies the number of messages to receive before exiting the application (used with delivertostdout)", data => map.Add(data, x => x.ServerOptions.ExitAfterMessages) }
             };
 
             if (!isDesktopApp)
@@ -112,9 +114,9 @@ public static MapOptions<CommandLineOptions> TryParseCommandLine(IEnumerable<str
             }
             else
             {
-                Console.WriteLine();
-                Console.WriteLine(" > For help use argument --help");
-                Console.WriteLine();
+                Console.Error.WriteLine();
+                Console.Error.WriteLine(" > For help use argument --help");
+                Console.Error.WriteLine();
             }
 
             return map;

Rnwood.Smtp4dev/Program.cs

@@ -184,7 +184,7 @@ private static IHost BuildWebHost(string[] args, CommandLineOptions cmdLineOptio
 
                         if (cmdLineOptions.DebugSettings)
                         {
-                            Console.WriteLine(JsonSerializer.Serialize(new SettingsDebugInfo
+                            Console.Error.WriteLine(JsonSerializer.Serialize(new SettingsDebugInfo
                             {
                                 CmdLineArgs = Environment.GetCommandLineArgs(),
                                 CmdLineOptions = cmdLineOptions,

Rnwood.Smtp4dev/Server/Settings/ServerOptions.cs

@@ -87,6 +87,10 @@ public record ServerOptions
         public bool ValidateBareLineFeed { get; set; } = false;
 
         public bool Pop3SecureConnectionRequired { get; set; } = false;
+
+        public string DeliverToStdout { get; set; } = "";
+
+        public int? ExitAfterMessages { get; set; }
     }
 
 }

Rnwood.Smtp4dev/Server/Settings/ServerOptionsSource.cs

@@ -77,5 +77,9 @@ public record ServerOptionsSource
         public bool? DisableHtmlCompatibilityCheck { get; set; }
 
         public long? MaxMessageSize { get; set; }
+
+        public string DeliverToStdout { get; set; }
+
+        public int? ExitAfterMessages { get; set; }
     }
 }

Rnwood.Smtp4dev/Server/Smtp4devServer.cs

@@ -565,6 +565,28 @@ private ILookup<MailboxOptions, string> GetTargetMailboxes(IEnumerable<string> r
             return targetMailboxesWithMatchedRecipient.ToLookup(t => t.Item1, t=> t.Item2);
         }
 
+        private bool ShouldDeliverToStdout(string mailboxName)
+        {
+            var deliverToStdout = serverOptions.CurrentValue.DeliverToStdout;
+            
+            if (string.IsNullOrWhiteSpace(deliverToStdout))
+            {
+                return false;
+            }
+
+            // If "*", deliver all mailboxes to stdout
+            if (deliverToStdout.Trim() == "*")
+            {
+                return true;
+            }
+
+            // Check if mailbox name is in the comma-separated list
+            var mailboxNames = deliverToStdout.Split(',', StringSplitOptions.RemoveEmptyEntries)
+                .Select(m => m.Trim());
+            
+            return mailboxNames.Contains(mailboxName, StringComparer.OrdinalIgnoreCase);
+        }
+
         void ProcessMessage(Message message, ISession session, IGrouping<MailboxOptions, string> targetMailboxWithRecipients)
         {
             log.Information("Processing received message for mailbox '{mailbox}' for recipients '{recipients}'", targetMailboxWithRecipients.Key.Name, targetMailboxWithRecipients.ToArray());
@@ -613,6 +635,44 @@ void ProcessMessage(Message message, ISession session, IGrouping<MailboxOptions,
             dbContext.SaveChanges();
             notificationsHub.OnMessagesChanged(targetMailboxWithRecipients.Key.Name).Wait();
             log.Information("Processing received message DONE");
+
+            // Deliver to stdout if configured for this mailbox
+            if (ShouldDeliverToStdout(targetMailboxWithRecipients.Key.Name))
+            {
+                lock (stdoutLock)
+                {
+                    // Output the raw message content to stdout
+                    // Use a delimiter that is very unlikely to appear in email messages
+                    Console.WriteLine("--- BEGIN SMTP4DEV MESSAGE ---");
+                    if (message.Data != null)
+                    {
+                        // Write raw message bytes to stdout
+                        using (var stdout = Console.OpenStandardOutput())
+                        {
+                            stdout.Write(message.Data, 0, message.Data.Length);
+                            stdout.Flush();
+                        }
+                        Console.WriteLine(); // Ensure delimiter is on new line
+                    }
+                    Console.WriteLine("--- END SMTP4DEV MESSAGE ---");
+                    Console.Out.Flush();
+
+                    messagesDeliveredToStdoutCount++;
+                    
+                    // Check if we should exit after delivering this message
+                    var exitAfter = serverOptions.CurrentValue.ExitAfterMessages;
+                    if (exitAfter.HasValue && messagesDeliveredToStdoutCount >= exitAfter.Value)
+                    {
+                        log.Information("Delivered {count} messages to stdout. Exiting as configured by ExitAfterMessages.", messagesDeliveredToStdoutCount);
+                        // Schedule application exit on a background thread to allow this method to complete
+                        Task.Run(async () =>
+                        {
+                            await Task.Delay(100); // Give time for logs to flush
+                            Environment.Exit(0);
+                        });
+                    }
+                }
+            }
         }
 
         public RelayResult TryRelayMessage(Message message, MailboxAddress[] overrideRecipients)
@@ -706,6 +766,8 @@ private void TrimSessions(Smtp4devDbContext dbContext)
         private readonly NotificationsHub notificationsHub;
         private readonly IServiceScopeFactory serviceScopeFactory;
         private Settings.ServerOptions lastStartOptions;
+        private int messagesDeliveredToStdoutCount = 0;
+        private readonly object stdoutLock = new object();
 
         public Exception Exception { get; private set; }
 

Rnwood.Smtp4dev/appsettings.json

@@ -354,7 +354,8 @@
         {
           "Name": "Console",
           "args": {
-            "outputTemplate": "{Message:lj}{NewLine}{Exception}"
+            "outputTemplate": "{Message:lj}{NewLine}{Exception}",
+            "standardErrorFromLevel": "Verbose"
           }
         }
       ],

docs/Configuration.md

@@ -161,4 +161,79 @@ If you want to customize the default mailbox behavior, you can explicitly config
 
 **Regex not working**: Ensure the pattern is surrounded by forward slashes (`/pattern/`) and test the regex with an online regex tester.
 
+## Deliver to Stdout Feature
+
+smtp4dev can output raw message content to stdout for automated processing or testing scenarios. This feature is useful for CI/CD pipelines, automated testing, or integrating with other tools.
+
+### Configuration Options
+
+#### DeliverToStdout
+
+Specifies which mailboxes should have their messages output to stdout:
+
+- **`*`** - Deliver all messages from all mailboxes to stdout
+- **`mailbox1,mailbox2`** - Deliver only messages from specified mailboxes (comma-separated)
+- **Empty string** (default) - Disable stdout delivery
+
+**Command Line**: `--delivertostdout="*"` or `--delivertostdout="Sales,Support"`
+
+**Configuration File**:
+```json
+{
+  "ServerOptions": {
+    "DeliverToStdout": "*"
+  }
+}
+```
+
+#### ExitAfterMessages
+
+Automatically exit the application after delivering a specified number of messages to stdout. Useful for automated testing scenarios.
+
+**Command Line**: `--exitafter=5`
+
+**Configuration File**:
+```json
+{
+  "ServerOptions": {
+    "ExitAfterMessages": 5
+  }
+}
+```
+
+### Message Format
+
+Messages delivered to stdout are wrapped with delimiters to separate multiple messages:
+
+```
+--- BEGIN SMTP4DEV MESSAGE ---
+<raw message content>
+--- END SMTP4DEV MESSAGE ---
+```
+
+### Logging Behavior
+
+When using deliver to stdout, all diagnostic and application logs are automatically redirected to stderr, ensuring stdout contains only message content.
+
+### Example Usage
+
+**Capture all messages and exit after 10:**
+```bash
+smtp4dev --delivertostdout="*" --exitafter=10 --smtpport=2525 > messages.txt 2> logs.txt
+```
+
+**Capture only Sales mailbox messages:**
+```bash
+smtp4dev --mailbox="Sales=*sales*@*" --delivertostdout="Sales" --smtpport=2525 > sales-messages.txt
+```
+
+**Use in CI/CD pipeline:**
+```bash
+# Start smtp4dev in background, send test emails, capture output
+smtp4dev --delivertostdout="*" --exitafter=3 --smtpport=2525 --imapport=0 --pop3port=0 > captured-emails.txt 2>&1 &
+# ... send test emails ...
+# Process captured-emails.txt
+```
+
+
 **Want messages in multiple mailboxes**: This is not supported due to "first match wins" logic. Consider using a single mailbox with multiple recipient patterns instead.

docs/Testing.md

@@ -406,6 +406,125 @@ public class SmtpTestcontainersTests : IAsyncLifetime
             await smtp4devContainer.DisposeAsync();
         }
     }
+
+## Capturing raw messages via stdout (--delivertostdout)
+
+For CI and automated tests you can have smtp4dev write the raw message bytes it receives to stdout so your test harness can capture and inspect them directly.
+
+How it works
+- Use `--delivertostdout` to specify either `*` (all mailboxes) or a comma-separated list of mailbox names (case-insensitive). The server checks the configured mailbox name for each delivered message and, when matched, writes the message's raw bytes to stdout.
+- Each message written to stdout is wrapped with clear ASCII delimiters to make parsing simple:
+
+```
+--- BEGIN SMTP4DEV MESSAGE ---
+<raw message content (bytes)>
+--- END SMTP4DEV MESSAGE ---
+```
+
+- The server writes the message bytes directly to the stdout stream (so attachments and binary content are preserved). The delimiters are written using normal Console.WriteLine calls.
+- When `--delivertostdout` is used the application logs and diagnostics should be captured from stderr (the default Serilog console configuration writes application logs to stderr), ensuring stdout contains only message content.
+
+Exit after N messages
+- Use `--exitafter=<n>` to make smtp4dev automatically exit once it has delivered `n` messages to stdout. This is intended for short-lived test runs where you start smtp4dev, send test emails, and wait for the process to exit.
+- The server tracks the number of messages written to stdout and, when the configured threshold is reached, schedules an orderly exit (Environment.Exit(0)) after a short delay to allow output to flush.
+
+Important notes and examples
+- `--delivertostdout` accepts `*` or a list of mailbox names: `--delivertostdout="*"` or `--delivertostdout="Sales,Support"`.
+- `--exitafter` only counts messages that were actually delivered to stdout (i.e. matched by `--delivertostdout`).
+- Because the raw bytes are written to stdout, redirect stdout to a file to capture messages and keep stderr for logs:
+
+```powershell
+# Capture all messages and logs separately (Windows PowerShell syntax)
+dotnet run --project Rnwood.Smtp4dev/Rnwood.Smtp4dev.csproj --delivertostdout="*" --exitafter=3 --smtpport=2525 --imapport=0 --pop3port=0 > captured-emails.txt 2> logs.txt
+```
+
+- Example for a single mailbox only:
+
+```powershell
+dotnet run --project Rnwood.Smtp4dev/Rnwood.Smtp4dev.csproj --mailbox="Sales=*sales*@*" --delivertostdout="Sales" --smtpport=2525 > sales-messages.txt 2> logs.txt
+```
+
+- When parsing the captured file, split on the delimiter lines (`--- BEGIN SMTP4DEV MESSAGE ---` / `--- END SMTP4DEV MESSAGE ---`) to extract each message's raw content.
+- The server uses a short delay before exiting to allow output buffers to flush; exit code will be `0` on normal shutdown triggered by `--exitafter`.
+
+Concurrency and reliability
+- Writing to stdout is synchronized internally to avoid interleaving when multiple messages arrive concurrently.
+- The count used by `--exitafter` is updated under the same lock that writes the message, so the exit threshold is reliable even under concurrent deliveries.
+
+Use cases
+- CI jobs that send a fixed number of test emails and then examine the captured files
+- Scripts that need to extract raw MIME messages for downstream processing or assertions
+
+Parsing captured output
+-----------------------
+
+Here are a few small examples that show how to remove the delimiters and split the captured output into individual raw messages. Each example writes each message to a separate `.eml` file.
+
+PowerShell (simple, text-oriented):
+
+```powershell
+# Reads the captured file as text and splits on the begin delimiter.
+$content = Get-Content -Raw -Encoding UTF8 'captured-emails.txt'
+$parts = $content -split '--- BEGIN SMTP4DEV MESSAGE ---' | Where-Object { $_.Trim() -ne '' }
+$i = 1
+foreach ($part in $parts) {
+    $msg = ($part -split '--- END SMTP4DEV MESSAGE ---')[0].TrimStart("`r`n")
+    [System.IO.File]::WriteAllText("message_$i.eml", $msg, [System.Text.Encoding]::UTF8)
+    $i++
+}
+
+# Note: this approach treats the captured file as UTF-8 text. For fully binary-safe handling use the Python or Node.js examples below.
+```
+
+Python (binary-safe):
+
+```python
+begin = b"--- BEGIN SMTP4DEV MESSAGE ---\n"
+end = b"--- END SMTP4DEV MESSAGE ---\n"
+
+with open('captured-emails.txt', 'rb') as f:
+    data = f.read()
+
+messages = []
+start = 0
+while True:
+    i = data.find(begin, start)
+    if i == -1:
+        break
+    j = data.find(end, i + len(begin))
+    if j == -1:
+        break
+    msg = data[i + len(begin):j]
+    messages.append(msg)
+    start = j + len(end)
+
+for idx, msg in enumerate(messages, start=1):
+    with open(f'message_{idx}.eml', 'wb') as out:
+        out.write(msg)
+```
+
+Node.js (binary-safe):
+
+```javascript
+const fs = require('fs');
+const begin = Buffer.from('--- BEGIN SMTP4DEV MESSAGE ---\n');
+const end = Buffer.from('--- END SMTP4DEV MESSAGE ---\n');
+const data = fs.readFileSync('captured-emails.txt');
+
+let start = 0;
+let idx = 1;
+while (true) {
+  const i = data.indexOf(begin, start);
+  if (i === -1) break;
+  const j = data.indexOf(end, i + begin.length);
+  if (j === -1) break;
+  const msg = data.slice(i + begin.length, j);
+  fs.writeFileSync(`message_${idx}.eml`, msg);
+  idx++;
+  start = j + end.length;
+}
+```
+
 }
 ```