{"id":48281738,"url":"https://github.com/ardimedia-com/win-smtp-relay","last_synced_at":"2026-06-27T07:01:02.240Z","repository":{"id":343204710,"uuid":"1175470502","full_name":"ardimedia-com/win-smtp-relay","owner":"ardimedia-com","description":"Open-source SMTP relay server for Windows, built with .NET 10 as a modern replacement for IIS SMTP. Relay only — no mailboxes, IMAP or POP3.","archived":false,"fork":false,"pushed_at":"2026-06-18T07:06:17.000Z","size":1164,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T09:09:07.282Z","etag":null,"topics":["csharp","dotnet","email","mail","smtp","smtp-relay","windows"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ardimedia-com.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["ardimedia-com"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-03-07T18:55:00.000Z","updated_at":"2026-06-18T07:06:22.000Z","dependencies_parsed_at":"2026-06-06T09:00:48.140Z","dependency_job_id":null,"html_url":"https://github.com/ardimedia-com/win-smtp-relay","commit_stats":null,"previous_names":["ardimedia/winsmtprelay","ardimedia-com/win-smtp-relay"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/ardimedia-com/win-smtp-relay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardimedia-com%2Fwin-smtp-relay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardimedia-com%2Fwin-smtp-relay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardimedia-com%2Fwin-smtp-relay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardimedia-com%2Fwin-smtp-relay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ardimedia-com","download_url":"https://codeload.github.com/ardimedia-com/win-smtp-relay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardimedia-com%2Fwin-smtp-relay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34844346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","dotnet","email","mail","smtp","smtp-relay","windows"],"created_at":"2026-04-04T22:48:42.240Z","updated_at":"2026-06-27T07:01:02.233Z","avatar_url":"https://github.com/ardimedia-com.png","language":"C#","funding_links":["https://github.com/sponsors/ardimedia-com"],"categories":[],"sub_categories":[],"readme":"# WIN-SMTP-RELAY\n\n\u003e **Work in progress** — This project is under active development and not yet ready for production use.\n\nOpen-source SMTP relay server for Windows. Built with .NET 10, designed as a modern replacement for IIS SMTP.\n\n**Relay only** — no mailboxes, no IMAP, no POP3. Accepts mail from internal apps/devices and forwards it via MX lookup or smart host.\n\n## Documentation\n\nFull component API reference and guides: **https://ardimedia-com.github.io/win-smtp-relay/** (generated from\nthe source with DocFX). See also [Using the components](#using-the-components-embedding-the-engine-in-your-own-host) below.\n\n## Features\n\n- Multiple receive connectors (different port/IP/TLS/auth per connector)\n- Send connectors with per-domain routing (MX or smart host)\n- Store-and-forward message queue (SQLite)\n- STARTTLS (port 587) and implicit TLS (port 465)\n- SMTP AUTH with per-user SendAs control and rate limits\n- DKIM signing (per tenant), inbound SPF/DKIM/DMARC verification (DMARC passes via SPF *or* DKIM alignment)\n- Setup page (`/setup`): live per-organization readiness checklist (can-send + deliverability) with the DNS records to publish, a test-message sender, and a local authentication self-test (\"Verify auth, no send\") that builds, signs and verifies a message against the relay's own key to confirm it will pass DMARC\n- Health page (`/health`): live deliverability checks per sender domain and sending IP — a synthesised **DMARC alignment outcome** per domain (passes via DKIM / conditional via SPF / will fail), plus SPF, DKIM, DMARC, MX, reverse DNS (PTR/FCrDNS), public-hostname A/AAAA, SPF coverage and 10-lookup-limit warnings, and DNSBL (Spamhaus ZEN / SpamCop), with copy-ready records\n- Daily self-check (`/diagnostics`): a once-a-day diagnostic of setup correctness, deliverability and the message journal — SPF/DKIM/DMARC alignment, reverse DNS, DNSBL and outbound-IP drift, outbound port 25 and smart-host reachability/credentials, TLS and admin-certificate expiry, required sending identity, every listener port actually accepting, queue health (oldest-pending age, stuck/retrying messages, 24h bounce rate, suppression spikes, disk space), relay-security posture, pending migrations, Event Log errors and clock skew. Surfaced in the daily report, on a Self-check page (with run history and an on-demand \"Run now\"), and as an immediate alert email when a new blocking problem appears\n- Optional envelope-from (Return-Path) realignment on delivery (`Delivery:AlignReturnPath`) so SPF aligns for DMARC; off by default, with a warning logged when an unaligned envelope-from is detected\n- Domain ownership verification (DNS TXT) for accepted sender and recipient domains, with optional enforcement on the SMTP path\n- IP-based relay restrictions, with optional strict IP-to-tenant binding for unauthenticated submission (blocks cross-tenant sender-domain spoofing)\n- Pickup folder for .eml files\n- Blazor admin UI (HTTPS, loopback by default), sign-in required\n- Authenticated admin access: cookie login + API keys, **membership-based authorization** (host admins + per-tenant admin/viewer roles, consent-based — a host admin gets access inside a tenant only by an explicit grant or an audited break-glass), **two-factor authentication (TOTP authenticator + recovery codes), passwordless passkeys (WebAuthn)**, an admin/security audit trail; optional passwordless sign-in link and email password-reset (both disableable per deployment for high-security installs)\n- Multi-tenant: isolated per-tenant configuration and data, **a single admin can be delegated to several tenants**, a tenant switcher, per-tenant egress (source) IP, and optional self-service tenant signup\n- REST API for management and monitoring\n- Windows Service with Event Log integration\n- Unattended self-update (`/update` → \"Install on this server\"): downloads the signed MSI from the official GitHub release, verifies its Authenticode signature (publisher ARDIMEDIA), and installs it via an elevated SYSTEM scheduled task that re-verifies the signature before installing — the relay service stays least-privilege (NetworkService) and never installs the MSI itself; settings and database are preserved\n- MSI installer (WiX v5)\n\n## Architecture\n\n```\nInternal App/Device\n    |  SMTP (port 25/587/465)\n    v\n[WinSmtpRelay SMTP Listener]\n    |\n    v\n[Message Queue (SQLite)]\n    |\n    v\n[Delivery Engine (MailKit)]\n    |\n    v\nExternal Mail Servers\n```\n\n## Technology Stack\n\n| Component | Library |\n|-----------|---------|\n| SMTP Listener | SmtpServer (cosullivan/SmtpServer) |\n| Outbound Delivery | MailKit + MimeKit |\n| Queue Storage | SQLite + EF Core |\n| DNS Resolver | DnsClient.NET |\n| DKIM Signing | MimeKit DkimSigner |\n| SPF/DMARC | Nager.EmailAuthentication |\n| Admin UI | Blazor Server + Blazor Blueprint UI |\n| Windows Service | Microsoft.Extensions.Hosting.WindowsServices |\n| Installer | WiX v5 (MSI) |\n\n## Solution Structure\n\n```\nsrc/\n  WinSmtpRelay.Core          — Domain models, interfaces, configuration\n  WinSmtpRelay.SmtpListener  — Inbound SMTP (wraps SmtpServer NuGet)\n  WinSmtpRelay.Delivery      — Outbound queue, retry, MailKit sending\n  WinSmtpRelay.Security      — TLS, DKIM, SPF, DMARC\n  WinSmtpRelay.Storage       — SQLite persistence (EF Core)\n  WinSmtpRelay.AdminApi      — REST API (Minimal API, class library)\n  WinSmtpRelay.AdminUi       — Blazor Server admin interface (Razor Class Library)\n  WinSmtpRelay.Service       — Windows Service host (Kestrel hosts API + UI)\ntests/\n  WinSmtpRelay.Core.Tests\n  WinSmtpRelay.SmtpListener.Tests\n  WinSmtpRelay.Delivery.Tests\n  WinSmtpRelay.Security.Tests\n  WinSmtpRelay.Integration.Tests\n```\n\n## Using the components (embedding the engine in your own host)\n\nThe relay is layered so the engine can be reused outside the bundled Windows Service — for a CLI, a\nworker, or an alternate UI. The **domain contracts live in `WinSmtpRelay.Core`** (interfaces/ports,\nmodels, configuration) and each layer exposes a single `AddRelayX()` registration. You program against the\nCore interfaces and resolve the implementations from DI.\n\n\u003e These projects are **not published to NuGet** — consume them by project reference (work in the solution\n\u003e or a fork). The bundled `WinSmtpRelay.Service` is just one host that composes the same building blocks.\n\n### Compose the engine\n\n```csharp\nusing WinSmtpRelay.Core.Configuration;   // the *Options classes\nusing WinSmtpRelay.Delivery;             // AddDeliveryEngine\nusing WinSmtpRelay.Security;             // AddRelaySecurity\nusing WinSmtpRelay.SmtpListener;         // AddSmtpListener\nusing WinSmtpRelay.Storage;              // AddRelayStorage, RelayDbContext\n\nvar builder = Host.CreateApplicationBuilder(args);\n\n// 1) Bind the options the engine reads (see the Service project's appsettings.json for the full set).\nbuilder.Services.Configure\u003cDeliveryOptions\u003e(builder.Configuration.GetSection(DeliveryOptions.SectionName));\nbuilder.Services.Configure\u003cSmtpListenerOptions\u003e(builder.Configuration.GetSection(SmtpListenerOptions.SectionName));\n// … bind the other *Options you use (Dkim, Dns, EmailAuthentication, RateLimit, …) …\n\n// 2) Compose only the layers you need.\nbuilder.Services\n    .AddRelayStorage(builder.Configuration.GetConnectionString(\"RelayDb\") ?? \"Data Source=relay.db\")\n    .AddRelaySecurity()     // SPF/DKIM/DMARC, DNS checks, signing, public-suffix (idempotent)\n    .AddDeliveryEngine()    // outbound queue + worker (pulls in AddRelaySecurity)\n    .AddSmtpListener();     // inbound SMTP (pulls in AddRelaySecurity)\n\nvar app = builder.Build();\n\n// 3) The engine does NOT migrate the database for you — do it at startup.\nusing (var scope = app.Services.CreateScope())\n    await scope.ServiceProvider.GetRequiredService\u003cRelayDbContext\u003e().Database.MigrateAsync();\n\nawait app.RunAsync();\n```\n\nPick only what you need: a **send-only** host drops `AddSmtpListener()`; a **read-only deliverability\ndashboard** needs just `AddRelayStorage()` + `AddRelaySecurity()`.\n\n### What each registration provides\n\n| Call | Registers |\n|------|-----------|\n| `AddRelayStorage(connectionString)` | EF Core (SQLite) `RelayDbContext`, the runtime config cache, tenant scoping (`ICurrentTenant` / `ITenantScopeFactory`), and every persistence-backed Core service (queue, users, connectors, domains, DKIM keys, settings, readiness …). |\n| `AddRelaySecurity()` | SPF/DKIM/DMARC validation, DKIM signing, inbound DKIM verification, deliverability DNS checks (`IDnsSetupService`), the local auth self-test (`IOutboundAuthCheckService`), the Public Suffix List, and the DNS resolvers. Idempotent — also pulled in by the delivery and listener engines. |\n| `AddDeliveryEngine()` | Outbound queue worker, MX resolution, MailKit-based `IDeliveryService`, and the message-filter chain. |\n| `AddSmtpListener()` | Inbound SMTP server, the open-relay guard, rate limiting, webhooks, and the pickup folder. |\n| `AddRelayAdminAuth()` | REST API authentication (cookie + API key) and tenant-aware authorization policies. |\n| `AddRelayAdminUiAuth()` + `AddBlazorBlueprintComponents()` | Blazor admin-UI authentication + the UI component library. |\n\n### Key ports to program against (in `WinSmtpRelay.Core.Interfaces`)\n\n- `IMessageQueue` — enqueue and inspect queued messages\n- `IDeliveryService` — deliver a queued message (MX or smart host)\n- `IDnsSetupService` — per-domain deliverability/DNS checks, including the synthesised DMARC-alignment outcome\n- `IOutboundAuthCheckService` — the local \"will this pass DMARC\" self-test (build + sign + verify, no send)\n- `ITenantReadinessService` — the setup-readiness checklist\n- `IDkimDomainService`, `IAcceptedSenderDomainService`, `ISendConnectorService`, … — configuration CRUD\n- `ICurrentTenant` / `ITenantScopeFactory` — multi-tenant scoping; **set the ambient tenant per request/operation** (everything else respects it)\n\n### Host responsibilities (what the engine leaves to you)\n\nBind the `*Options` from configuration, apply EF migrations at startup, run any seeders you need, and — if\nyou expose the admin UI over HTTPS — provide an `IAdminCertificateProvider` (the certificate applier is a\nhost concern, not part of the engine).\n\n### Out-of-process\n\nFor a UI in a separate process or language, consume the REST API (`WinSmtpRelay.AdminApi`) over HTTP with an\n`X-Api-Key` (or `Authorization: Bearer`) header — see [Admin access](#admin-access). The running host serves a\nmachine-readable OpenAPI document at `/openapi/v1.json` (point Scalar/Swagger or a client generator at it).\n\n## Configuration\n\nConfiguration is split between file-based and database-stored settings:\n\n### appsettings.json (requires restart)\n\nInfrastructure settings the application needs before it can start:\n\n- Kestrel ports and TLS certificate paths\n- SQLite database connection string\n- Log levels\n- Admin UI enabled/disabled, port, bind address, and HTTPS (default: HTTPS on `127.0.0.1:8025`, loopback-only)\n- Windows Service settings\n\n### SQLite database (runtime-editable via Admin UI)\n\nEverything the admin edits during normal operation:\n\n- Receive connectors (port/IP/TLS/auth)\n- Send connectors and domain routing\n- Accepted sender and recipient domains (with ownership verification)\n- IP allow/deny lists\n- SMTP users and credentials\n- DKIM keys and per-domain config\n- Rate limits and auto-ban rules\n- Message filter rules\n- Tenants, web-admin accounts, and API keys\n- Inbound email authentication (SPF/DMARC + enforcement mode) and verification/tenant-binding policy\n- DNS recommendation, backup-MX, statistics, and self-service signup settings\n\nThe Admin UI reads `appsettings.json` for display but does not write to it.\n\n## Building\n\n```bash\ndotnet build winsmtprelay.slnx\ndotnet test winsmtprelay.slnx\n```\n\n## Running\n\nAs a console app (development):\n\n```bash\ndotnet run --project src/WinSmtpRelay.Service\n```\n\nAs a Windows Service:\n\n```bash\nsc.exe create WinSmtpRelay binPath=\"C:\\path\\to\\WinSmtpRelay.Service.exe\"\nsc.exe start WinSmtpRelay\n```\n\n## Admin access\n\nThe admin UI and REST API require authentication and bind to `127.0.0.1` over HTTPS by default.\n\nNo administrator is created automatically. On first start, open the admin UI at `https://localhost:8025/account/login` — with no account yet, you are taken to **first-run setup** (`/account/initial-setup`) to define the first administrator (email + password). That account becomes the host administrator with full access. Once it exists, the setup page is closed and `/account/login` is shown normally.\n\nIf an older install still carries the legacy seeded `admin@local` account *and it is the only account*, the service removes it on start so a new administrator must be defined through first-run setup. If you ever lose admin access, re-run the installer (Repair) and tick **Reset administrator access**: on the next start all administrator accounts are removed and first-run setup runs again. To expose the admin UI beyond loopback, use the installer's network-access option (also available later via Repair), or change `AdminUi:BindAddress` deliberately / put it behind a reverse proxy. For HTTPS, the admin UI starts with a self-signed certificate; replace it on the **HTTPS Certificate** page by uploading a PFX or picking a certificate from the Windows certificate store (applied immediately, no restart). Alternatively, `AdminUi:CertificatePath` / `AdminUi:CertificatePassword` can point to a PFX on disk.\n\nFor automation, create an API key and pass it as `X-Api-Key: \u003ckey\u003e` (or `Authorization: Bearer \u003ckey\u003e`). Keys are scoped to a tenant and a role.\n\n## Responsible operation\n\nA mail relay can be abused if misconfigured. WIN-SMTP-RELAY is **closed by default**: relaying to an\nexternal (non-hosted) recipient always requires SMTP authentication or an explicit allow-IP rule, and\nthis cannot be disabled by configuration — an empty config, or an overly-broad allow rule (`0.0.0.0/0`\nor a near-\"any\" combination), will not relay to the outside world.\n\nWhen operating it, also:\n\n- **Send only solicited mail.** Stop sending to addresses that hard-bounce or complain — the per-tenant\n  suppression list does this automatically; don't work around it.\n- **Protect deliverability:** publish SPF/DKIM/DMARC and valid reverse DNS (PTR), use a stable (not\n  dynamic) IP, and prefer a reputable **smart host** for production sending. Watch the **Health** page\n  (Spamhaus / SpamCop checks) and act on any listing.\n- **Protect the admin plane:** HTTPS with a real certificate, strong passwords, least-privilege API keys.\n\nSee [SECURITY.md](SECURITY.md) for the full guidance and how to report a vulnerability.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardimedia-com%2Fwin-smtp-relay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fardimedia-com%2Fwin-smtp-relay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardimedia-com%2Fwin-smtp-relay/lists"}