Merge pull request #377 from ChangemakerStudios/feature/smtp-rate-limit

Add configurable SMTP message rate limiting

Author: Jaben

DOCKERHUB.md

@@ -1,4 +1,4 @@
-![Papercut Logo](https://raw.githubusercontent.com/ChangemakerStudios/Papercut/develop/graphics/PapercutLogo.png)<br>
+![Papercut Logo](https://raw.githubusercontent.com/ChangemakerStudios/Papercut/develop/graphics/PapercutLogo.png)<br>
 *The Simple Desktop Email Helper*
 
 ## The problem
@@ -90,6 +90,8 @@ docker run -d \
 - `SmtpServer__MessagePath` - Path where emails are stored (default: /app/Incoming)
 - `SmtpServer__LoggingPath` - Path for log files (default: /app/logs)
 - `SmtpServer__AllowedIps` - IP allowlist for SMTP connections (default: "*" = all IPs allowed)
+- `SmtpServer__RateLimit` - Message reception rate limit as `<count>/<window>`, e.g. `500/1h` (default: "*" = no limit)
+- `SmtpServer__RateLimitReplyCode` - SMTP reply code returned once the rate limit is hit (default: 451)
 - `Urls` - HTTP server URLs (default: http://0.0.0.0:8080)
 - `HttpPathPrefix` - Serve the web UI and API under a path prefix, e.g. `/webmail` (default: empty = serve at root)
 

docs/service.md

@@ -1,4 +1,4 @@
-# Service & Web UI
+# Service & Web UI
 
 The **Papercut SMTP Service** is an optional background component that receives email even when the desktop app isn't running — as a Windows Service or a [Docker container](docker.md) — and includes a browser-based UI for viewing messages.
 
@@ -65,6 +65,36 @@ Use `http://0.0.0.0:8080` to listen on all interfaces — but read the warning b
 !!! warning "Network exposure"
     When binding to `0.0.0.0`, `+`, `*`, or a LAN IP, the web UI is reachable from other machines — and Papercut has **no built-in authentication**. Use firewall rules or a reverse proxy with auth in front of it.
 
+**Rate limiting** — reject mail once a quota is hit, so you can test how your application
+handles a mail server that is throttling it (`appsettings.json`):
+
+```json
+{
+  "SmtpServer": {
+    "RateLimit": "500/1h",
+    "RateLimitReplyCode": 451
+  }
+}
+```
+
+`RateLimit` is `<count>/<window>`, where the window is a number followed by `s`, `m`, or `h` —
+for example `500/1h`, `5/10m`, or `100/30s`. Use `*` (the default) for no limit.
+
+Once the limit is reached, Papercut rejects at `MAIL FROM` until the window resets:
+
+```text
+451 4.7.1 Message rate limit exceeded (500 per hour)
+```
+
+`RateLimitReplyCode` accepts any 4xx or 5xx reply code — 421, 451 (the default), 452 and 550
+are the usual choices. A 4xx code tells the sending client the failure is temporary and worth
+retrying; a 5xx code tells it the message was permanently refused.
+
+The count is global to the server rather than per-sender or per-IP, and the window is fixed:
+it starts when the first message arrives and resets in full once it expires.
+
+Environment variable form (Docker): `SmtpServer__RateLimit` and `SmtpServer__RateLimitReplyCode`.
+
 ## API
 
 The web UI is backed by a small HTTP API (`/api/messages`, etc.) you can script against — handy for asserting "an email was sent" in end-to-end tests. Explore the endpoints via your browser's dev tools on the web UI.

src/Papercut.Infrastructure.Smtp/ChainedMailboxFilter.cs

@@ -0,0 +1,66 @@
+// Papercut
+//
+// Copyright © 2008 - 2012 Ken Robertson
+// Copyright © 2013 - 2025 Jaben Cargman
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+using SmtpServer;
+using SmtpServer.Mail;
+using SmtpServer.Storage;
+
+namespace Papercut.Infrastructure.Smtp;
+
+/// <summary>
+/// Runs several mailbox filters in order, stopping at the first rejection.
+///
+/// SmtpServer ships an equivalent internally but does not expose it, and the
+/// DelegatingMailboxFilterFactory hook Papercut uses supplies exactly one filter.
+/// </summary>
+internal sealed class ChainedMailboxFilter(IReadOnlyList<IMailboxFilter> filters) : IMailboxFilter
+{
+    public async Task<bool> CanAcceptFromAsync(
+        ISessionContext context,
+        IMailbox from,
+        int size,
+        CancellationToken cancellationToken)
+    {
+        foreach (var filter in filters)
+        {
+            if (!await filter.CanAcceptFromAsync(context, from, size, cancellationToken).ConfigureAwait(false))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    public async Task<bool> CanDeliverToAsync(
+        ISessionContext context,
+        IMailbox to,
+        IMailbox from,
+        CancellationToken cancellationToken)
+    {
+        foreach (var filter in filters)
+        {
+            if (!await filter.CanDeliverToAsync(context, to, from, cancellationToken).ConfigureAwait(false))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

src/Papercut.Infrastructure.Smtp/PapercutSmtpModule.cs

@@ -18,6 +18,8 @@
 
 using Autofac;
 
+using Papercut.Infrastructure.Smtp.RateLimiting;
+
 using SmtpServer;
 using SmtpServer.Authentication;
 using SmtpServer.Net;
@@ -58,9 +60,29 @@ protected override void Load(ContainerBuilder builder)
             ctx =>
             {
                 var ipAllowedList = ctx.ResolveOptional<IPAllowedList>() ?? IPAllowedList.AllowAll;
-                var logger = ctx.Resolve<ILogger>().ForContext<IpAllowlistMailboxFilter>();
+                var logger = ctx.Resolve<ILogger>();
+                var ipLogger = logger.ForContext<IpAllowlistMailboxFilter>();
+
+                // Rate limiting is opt-in and only registered by the service host, so
+                // hosts that never configure it (the UI) resolve nothing and pay nothing.
+                var rateLimiter = ctx.ResolveOptional<SmtpRateLimiter>();
+                var rateLimitLogger = logger.ForContext<RateLimitMailboxFilter>();
+
                 return new DelegatingMailboxFilterFactory(
-                    _ => new IpAllowlistMailboxFilter(ipAllowedList, logger));
+                    _ =>
+                    {
+                        var ipFilter = new IpAllowlistMailboxFilter(ipAllowedList, ipLogger);
+
+                        if (rateLimiter is null || rateLimiter.Limit.IsUnlimited)
+                        {
+                            return ipFilter;
+                        }
+
+                        // Allowlist first: connections Papercut was never going to
+                        // accept should not consume the caller's quota.
+                        return new ChainedMailboxFilter(
+                            [ipFilter, new RateLimitMailboxFilter(rateLimiter, rateLimitLogger)]);
+                    });
             }).As<IMailboxFilterFactory>();
 
         builder.Register<SmtpServer.SmtpServer>(

src/Papercut.Infrastructure.Smtp/RateLimiting/RateLimitDecision.cs

@@ -0,0 +1,27 @@
+// Papercut
+//
+// Copyright © 2008 - 2012 Ken Robertson
+// Copyright © 2013 - 2025 Jaben Cargman
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+namespace Papercut.Infrastructure.Smtp.RateLimiting;
+
+/// <summary>
+/// The outcome of a single <see cref="SmtpRateLimiter.TryAcquire" /> attempt.
+/// </summary>
+/// <param name="IsAllowed">Whether the message may be accepted.</param>
+/// <param name="Count">Messages accepted in the current window, including this one when allowed.</param>
+/// <param name="RetryAfter">Time remaining until the window resets. Zero when allowed.</param>
+public readonly record struct RateLimitDecision(bool IsAllowed, int Count, TimeSpan RetryAfter);

src/Papercut.Infrastructure.Smtp/RateLimiting/RateLimitMailboxFilter.cs

@@ -0,0 +1,81 @@
+// Papercut
+//
+// Copyright © 2008 - 2012 Ken Robertson
+// Copyright © 2013 - 2025 Jaben Cargman
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+using SmtpServer;
+using SmtpServer.Mail;
+using SmtpServer.Protocol;
+using SmtpServer.Storage;
+
+namespace Papercut.Infrastructure.Smtp.RateLimiting;
+
+using ILogger = Serilog.ILogger;
+
+/// <summary>
+/// Mailbox filter that enforces a message reception rate limit, letting developers
+/// test how their application behaves against a mail server that is throttling them.
+///
+/// Returning false from CanAcceptFromAsync would reject with a hardcoded 550, so this
+/// throws SmtpResponseException instead -- the SmtpServer session loop writes the
+/// carried response back to the client verbatim, which is what allows a configurable
+/// reply code (421/451/452/550).
+/// </summary>
+internal sealed class RateLimitMailboxFilter(SmtpRateLimiter rateLimiter, ILogger logger) : IMailboxFilter
+{
+    public Task<bool> CanAcceptFromAsync(
+        ISessionContext context,
+        IMailbox from,
+        int size,
+        CancellationToken cancellationToken)
+    {
+        var decision = rateLimiter.TryAcquire();
+
+        if (decision.IsAllowed)
+        {
+            logger.Verbose(
+                "SMTP message accepted against rate limit {RateLimit} ({Count} so far this window)",
+                rateLimiter.Limit,
+                decision.Count);
+
+            return Task.FromResult(true);
+        }
+
+        logger.Warning(
+            "Rejected SMTP MAIL FROM command from {RemoteIp} with {ReplyCode} - rate limit {RateLimit} reached, resets in {RetryAfter}",
+            context.GetRemoteIpAddress(),
+            (int)rateLimiter.Limit.ReplyCode,
+            rateLimiter.Limit,
+            decision.RetryAfter);
+
+        // quit: true closes the session after the reply. Without it the session loop
+        // appends ", N retry(ies) remaining." to the message, which is noise in a
+        // response the client is meant to parse.
+        throw new SmtpResponseException(
+            new SmtpResponse(rateLimiter.Limit.ReplyCode, rateLimiter.Limit.ReplyMessage),
+            quit: true);
+    }
+
+    public Task<bool> CanDeliverToAsync(
+        ISessionContext context,
+        IMailbox to,
+        IMailbox from,
+        CancellationToken cancellationToken)
+    {
+        // The limit counts messages, not recipients -- it is applied once at MAIL FROM.
+        return Task.FromResult(true);
+    }
+}