Troubleshooting and error codes.

The typical picture: the device sends fine without TLS, but with STARTTLS or implicit TLS it aborts with a message that explains nothing. Swyx for instance reports SMTP Error Code: -2147467259, other systems simply say "connection failed".

The cause is almost always the self-signed certificate. SMTPly creates it during setup. It is technically sound, but nobody knows its issuer: a device that validates the trust chain finds no known root and gives up. The error occurs on the device side, which is why SMTPly's system log often shows nothing at all.

Remedy: mark the certificate as trusted on the sending system. Under Settings → Certificate → Show current certificate the Windows dialog opens with the Install certificate button. Two details are where this usually goes wrong:

• Choose the store location Local Machine, not "Current User". Services run under their own account and cannot see your user store.
• Choose Trusted Root Certification Authorities, not "Personal" and not the automatic selection.

Then restart the service of the sending system. Windows keeps trust decisions inside a running process; a service that found no chain at start will not see the new root certificate otherwise.

Equally important: the device has to address SMTPly by exactly the name in the certificate. An IP address in the mail server field is not enough, even when the certificate is trusted.

If you would rather not maintain a certificate, there are two alternatives: use a certificate from your own internal CA through the Windows certificate store, or, for a relay whose traffic never leaves the machine, skip TLS and rely on the IP allow list. If SMTP authentication is to be used in that case, Allow plaintext AUTH without STARTTLS is required as well, because SMTPly otherwise refuses logins on unencrypted connections.

By default exactly one inbound and one outbound:

Everything else only if you switch it on: monitoring endpoint 8025, REST interface 8026, MCP server 8027 (all inbound, bound to 127.0.0.1 by default — reachable from the network only after changing the bind address plus a firewall rule), and outbound syslog 514 and your webhook targets. All ports are freely configurable.

For the SMTP listener the assistant helps: step 5 creates the Windows firewall rule for you if you want.

Yes — this is one of the most common use cases. Microsoft has officially marked the IIS 6.0 SMTP service as deprecated. It is still bundled with Windows Server 2025, but slated for removal in future releases. On top of that, it can't do OAuth2: forwarding mail through Exchange Online requires Basic Auth, which Microsoft disables by default at the end of December 2026.

SMTPly is the modern answer for that exact scenario: same role (local SMTP relay for printers, ERP systems, scanners and line-of-business software), but with OAuth2 translation to Microsoft Graph, a GUI, a mail tracker, retry logic, and an actively maintained codebase. Migration is straightforward: stop the IIS SMTP service, install SMTPly, keep the bind port at 25 (or 587), and your devices keep their existing target IP — done.

On the first start as administrator the setup assistant opens and walks you through seven steps up to a verified test mail: welcome, pick a path, connect Microsoft 365, define the sender, configure devices and network, check, done. The full illustrated guide is further up this page. You can reopen it any time via Settings → General → Open setup assistant.

It can create the Azure app registration for you. In the step "Connect Microsoft 365" you sign in with Microsoft once; SMTPly then creates the app registration, the client secret, the service principal and the Mail.Send permission in your tenant and fills in the values itself, including the secret's expiry date.

• Objects are created in your tenant only. No data is sent to us, and the client secret never leaves your server.
• Nothing is installed. On Server Core without a browser, SMTPly offers device code sign-in automatically.
• Prefer clicking yourself? Choose "Enter manually" — the illustrated guide is further up this page.
• For environments where no sign-in window can open, the signed PowerShell script is still available as Path C.

A log of the run is included in the diagnostics package so a failure can be traced. The client secret is not part of it.

No — it has to be a real mailbox. SMTPly hands every mail to POST /v1.0/users/{sender}/sendMail. That address is therefore the sending mailbox, and the Mail.Send application permission only allows sending as exactly that mailbox.

• User mailbox — works.
• Shared mailbox — works and is the usual choice because it needs no licence (e.g. relay@yourcompany.com).
• Distribution lists and mail-enabled security groups — do not work. They have no mailbox and cannot be the sending identity.
• Alias (additional SMTP address) — please enter the mailbox's primary address. Other addresses of the mailbox are not documented for this call.

This also applies in normal operation without "always override sender": there every device keeps its own sender address — and each of them must be a mailbox in the tenant, otherwise Microsoft 365 rejects the delivery.

If you want to send as a group address, set up a shared mailbox carrying that address. Exchange does allow sending on behalf of a distribution list via Send As permissions, but that would require rebuilding the message — SMTPly deliberately passes mail through unchanged so that signatures and attachments survive byte for byte.

Yes. Ctrl+1 to Ctrl+8 jump straight to Dashboard, Maillog, System Log, Mailflow, Settings, License, About and Mailflow with the rule tester; Ctrl+, opens the settings. F6 moves focus between the navigation pane and the content area. Within a page, Tab moves focus, Space/Enter activates, and the main buttons (Save, start/stop service, activate license) have Alt access keys. The keyboard focus is clearly highlighted so you always see where you are without a mouse. (from version 1.7.26)

As an SMTP relay to Microsoft 365: yes. Many installations run hMailServer purely as a local smart host — devices submit over SMTP, hMailServer forwards to Exchange Online. SMTPly takes over exactly that role, with the difference that forwarding runs over OAuth2 and Microsoft Graph instead of a username and password.

The trigger is usually the same: hMailServer has not been developed for years, the last release has no OAuth2 support and ships an outdated OpenSSL. Once Microsoft turns off SMTP Basic Auth, forwarding stops — and it cannot be retrofitted.

What SMTPly is not: a full mail server. There are no mailboxes, no POP3/IMAP retrieval, no local delivery and no distribution lists — those live in Microsoft 365. If you run hMailServer as a standalone mail server with local mailboxes, you still need a different solution for that part.

Migration: stop the hMailServer service, install SMTPly, bind the same port (usually 25) — your devices keep their target IP and never have to be touched. Sender allowlists and IP restrictions are recreated in the SMTPly settings.

Yes, and it cuts both ways. SMTPly hands every message to Microsoft Graph via sendMail, and Microsoft automatically files a copy in the sender address's mailbox under Sent Items, attachments included. The behaviour comes from Microsoft and cannot be switched off when sending in MIME format.

The upside: a classic SMTP relay delivers the message and then forgets it. Through Microsoft Graph it stays traceable, and anyone with access to the mailbox can see what a line-of-business application has sent out.

The risk: that same behaviour becomes a privacy problem when the sender address is a shared mailbox such as info@ or mail@. If SMTPly sends confidential documents through it, such as scanned papers, invoices or payslips, everyone with access to that mailbox can read them.

Recommendation:

• Use a dedicated mailbox just for SMTPly, for example smtp@company.com, ideally a shared mailbox that only a few chosen people can open.
• Set a retention policy on that mailbox's Sent Items so the copies are deleted after a few days.
• Restrict the app to exactly that mailbox with an application access policy, so it cannot send as another mailbox by mistake.

With Always replace sender you can route all devices, including those with made-up sender addresses, through this one mailbox.

No. Whatever your device hands over via SMTP is passed on to Microsoft Graph byte for byte — headers, encodings, multipart boundaries, embedded images and attachments all stay untouched. SMTPly only reads along to show sender, recipients, subject and size in the mail tracker; the original bytes are never altered. No extra Received header is added either.

There are exactly two narrowly scoped exceptions, each touching a single header line:

Sender override: if all mail goes out under one fixed address, the From: line is replaced — Microsoft Graph rejects any message whose sender differs from the sending mailbox. Without the override this never applies.

Journal BCC Business: if an archive mailbox is configured, SMTPly adds a Bcc: line with that address so the blind copy gets delivered. As with any BCC, Microsoft strips the line before delivery to the recipients — nothing of it is visible. Without a configured journal mailbox this never applies either.

In both cases only the affected line is swapped or inserted; body, attachments and all remaining headers stay byte-identical.

Yes — you can simply start Smtply.exe as a desktop application. The relay then runs as long as the GUI is open. For production 24/7 operation, the service variant is better: no logged-in user needed, auto-start with Windows.

Yes, starting with the Business edition. Business (€249) relays through up to 5 Microsoft 365 tenants in parallel on one Windows server, Enterprise (€499) up to 25. Routing is selectable per tenant: by sender domain (mail from alice@firma1.de goes via the "Firma 1" tenant) or by AUTH-user binding (an authenticated SMTP user is pinned to one specific tenant).

Tenants are counted, not mailboxes. A Microsoft 365 tenant with any number of sender mailboxes counts as one tenant: one app registration and one tenant configuration in SMTPly serve every mailbox the app is allowed to send from. To restrict the app to specific mailboxes, use Exchange Online (Application Access Policy or RBAC for Applications). The sender address of each mail is preserved as long as "Always override sender" is off. An AUTH user bound to the tenant sends its mail through that tenant regardless of the From domain.

Several tenants are meant for your own and affiliated companies, or for third-party tenants you look after free of charge. For IT service providers and software vendors see May I use SMTPly as an IT service provider for my customers?

The Starter edition (€149) supports exactly one tenant. For a move to a larger edition see I need a larger edition: the existing configuration is preserved as "Primary tenant".

Yes, if each customer buys their own license and runs SMTPly on their own server. You set up the installation for them, and the license belongs to the customer.

Not permitted is running SMTPly on your own server as a hosted relay for several customers for a fee, or building it into a paid product or service. Several tenants can only be connected for your own and affiliated companies, or for third-party tenants you look after free of charge. This is stated in Section 5 of the terms.

For use by IT service providers, hosting providers and software vendors there are partner licenses. Write to us through the contact form and we will find a suitable solution.

Use the contact form and tell me which edition you are running and which one you need. What you already paid is credited, you only pay the difference, and you receive a new licence key.

The switch happens on the Licence settings page: deactivate the old key, enter the new one and activate it. Your configuration is kept in full — the additional features are available right away, with no reinstall and no need to set the service up again.

The same applies to Enterprise: that edition is not sold through the shop but issued after a short conversation. The contact form is the way there as well.

Yes, from the Business edition. SMTPly supports AUTH LOGIN and AUTH PLAIN on the listener. Since version 1.8.0 SMTP authentication belongs entirely to Business and Enterprise — Starter stays with the IP and sender allow-lists, which is enough for a single server with printers on its own network. If you set up SMTP AUTH during the trial and then activate Starter, authentication is switched off, even if it was set as required, and only the allowed source IPs apply. It is different when a paid license cannot be confirmed at the moment (not validated online for more than 30 days, hardware not recognised after a migration): during the 14-day grace period the purchased edition keeps running unchanged, including authentication. The self-test and the system log point this out in both cases. User management, per-user tenant binding and the bulk import from CSV belong to multi-tenant operation.

Passwords are stored as PBKDF2-SHA256 hash with per-user salt — not recoverable, not even by the admin. Three sub-modes:

• AUTH off (default): senders are gated by the IP allow-list only.
• AUTH offered: AUTH is advertised in EHLO. Authenticated senders get priority routing; senders without AUTH fall back to the IP/domain allow-list.
• AUTH required: unauthenticated MAIL FROM is rejected with SMTP 530.

STARTTLS is required by default for plaintext passwords; an explicit "Allow plaintext AUTH without TLS" toggle exists for legacy devices that cannot do STARTTLS — opt-in only, with a clear warning.

Older devices (e.g. industrial controllers, smoking-chamber or cooling-system controllers) often speak an encryption variant their interface simply calls "SSL": implicit TLS. The connection is encrypted from the very first byte, without the plaintext phase that STARTTLS requires. If that doesn't match, the device typically fails with an error like SSL23_GET_SERVER_HELLO:unknown protocol.

Since version 1.7.5, SMTPly supports exactly this case: in the settings under SMTP listener → TLS/SSL, "Implicit TLS/SSL" is available as a mode alongside STARTTLS. Both modes share the same certificate selection (self-signed, PEM, or PFX) and are mutually exclusive — a listener port only ever serves one of the two modes.

If you have both old "SSL" devices and newer STARTTLS devices in use at the same time, that's not a contradiction: from the Business edition onward, you can run several SMTP listener ports in parallel, each with its own TLS mode. The old devices simply point at one port (implicit TLS), the newer ones at another (STARTTLS) — no per-device configuration required.

Currently no — SMTPly is Windows-native (DPAPI, Windows service, WPF). A Linux variant is not on the roadmap. For mixed environments, a Windows server as dedicated relay host is the simple solution.

No, that is a warning about the file's reputation, not a malware detection. Microsoft Defender SmartScreen warns about any file that has not yet been downloaded often enough. It fades on its own once enough people have downloaded and run the same file.

As of version 1.7.18 the installer is digitally signed, issued to IT-Beratung - Andreas Hähnel. Two things change immediately: User Account Control names the publisher in plain text instead of "Unknown publisher", and the origin of the file can be verified independently of where you downloaded it. The warning itself does not disappear right away. Microsoft weighs two signals: the reputation of the individual file and the reputation of the signing certificate. The first starts at zero with every version; the second keeps growing across versions as long as the same signing identity is used. So the signature is what allows anything to accumulate at all, not a switch that turns the warning off.

How to run the installer anyway:

• Browser download: click "Keep" → "Keep anyway".
• On launch: "Windows protected your PC" → "Run anyway". If that button is not shown straight away, "More info" reveals it.

Check the signature: right-click the EXE → Properties → Digital Signatures → select the entry → Details. The signer must read IT-Beratung - Andreas Hähnel, and the chain runs through Microsoft ID Verified CS EOC CA up to the Microsoft Identity Verification Root Certificate Authority 2020. From PowerShell:

Get-AuthenticodeSignature SMTPly-Setup-latest.exe | Format-List Status, SignerCertificate

Compare the SHA-256: the checksum still applies and remains the sharpest check. It is published on the Download page and in every GitHub release:

Get-FileHash SMTPly-Setup-latest.exe -Algorithm SHA256

If the hashes match, your file is bit-identical to what we built and published. SmartScreen reputation is a heuristic signal — SHA-256 is cryptographically unambiguous.

How signing works here: through Azure Artifact Signing. The private key never sits on our build machine — it never leaves Microsoft's hardware security module, and the build only submits a hash to be signed. The issued certificates are deliberately very short-lived, so every signature carries a timestamp and stays valid after the certificate itself expires.

Just run the new installer. It detects the existing install, replaces the binaries and keeps configuration, license and logs under %ProgramData%\Smtply\ unchanged. From version 1.3.0 on, SMTPly proactively notifies you about available updates — the public release API is checked once per day and release notes are shown directly on the „About" page.

The folder %ProgramData%\Smtply\ is kept on purpose so that a reinstall finds your settings again. It holds the configuration including the encrypted client secret, the mail history with senders, recipients and subjects, and the license file.

If the server is being decommissioned or handed on, please delete the folder by hand. From version 1.8.1 the uninstaller points this out at the end.

Yes, if you enter a recipient address under Settings → Microsoft 365 → E-mail notifications. SMTPly then sends a warning mail to that address as the expiry date approaches. The warning is sent from the same e-mail address that is configured for the mail relay.

By default the first warning is triggered 14 days before expiry (configurable). Additional warnings follow automatically at 7, 3, 1 and 0 days remaining — each threshold fires exactly once. Once the secret has expired, no more e-mails are sent because Microsoft 365 authentication stops working at that point; the colour-coded warning in the Microsoft 365 settings of the GUI remains visible.

Yes. Under Settings → Microsoft 365 → E-mail notifications, in addition to the secret-expiry warning, you can pick a report cadence: daily, weekly or monthly. The report is sent to the same notification address and contains totals (sent / failed / rejected), average delivery time, top senders, top recipient domains and the most common error reasons for the period.

The report respects your privacy settings — with masking enabled it shows masked addresses, with "Log addresses" disabled the top-lists are omitted entirely. You can switch the report off at any time with the "No reports" option.

No. SMTPly stores only metadata (timestamp, addresses, subject, size, status) in the mail tracker — body and attachments are discarded immediately after successful relay or final failure (GDPR data-minimisation).

Under Help / FAQ → Create diagnostics package, SMTPly builds a ZIP archive you can send to support, e.g. by email. It contains the most recent system log files, a masked overview of recently sent emails (sender, recipient, and subject are redacted — regardless of your usual masking level, because this package leaves your machine), the public certificate data (validity, issuer, thumbprint — never the private key), and a summary of the non-secret configuration (listeners, TLS modes, license edition). The sender IP address is deliberately kept in plain text, since it's needed for network and firewall diagnostics.

Passwords, client secrets, license keys, and private certificate keys are never included. A clear warning appears before the package is created — it's only generated locally, and it's only ever sent if you actively share it with a trusted party.

Yes. Under Help / FAQ → Run self-test, SMTPly checks its own state in one click: Windows service running, write permissions in the configuration directory, port availability, a real connection to its own listener (including a TLS handshake for implicit TLS), certificate validity, client secret decryption, and Microsoft Graph reachability. Each check shows up as a green/yellow/red result with a plain-language explanation.

Since version 1.8.7 the self-test also checks that the license server api.polar.sh is reachable, without sending a license key. The diagnostics bundle runs the self-test fresh before it is created and includes the result as selbsttest.txt, so you do not have to run it yourself first.

Important: these checks connect over 127.0.0.1 (localhost) — Windows Firewall does not filter loopback traffic at all. A green result proves the listener works correctly locally, but not that an external device (e.g. the printer or ERP system) can actually get through the firewall. For that, the page offers a ready-made Test-NetConnection command to copy and run from the sending device, to verify real reachability.

Incoming mails land in a local, persistent queue (queue.db) before they reach the in-memory send queue. If Graph has a hiccup, exponential backoff handles it; if the Windows service restarts (or the whole server), SMTPly reloads the pending entries on startup and delivers them automatically. Only after a successful send — or a final failure — is the raw payload deleted.

During a Graph outage the GUI dashboard shows a warning banner; a circuit breaker prevents pointless retries from burning tokens.

Yes — SMTPly was deliberately designed so that no data flows to third parties. Processing stays within your existing Microsoft 365 contractual relationship. Still, verify your internal compliance (e.g. whether legacy devices may send personal data at all).

NIS2 applies to organisations, not to software. There is therefore no such thing as NIS2 conformity that a product could have or lack. If your own company falls under NIS2, what concerns you is the duty to secure your supply chain. We have compiled the usual answers for that: Information for supplier questionnaires.

The CRA applies to SMTPly as a product with digital elements. Since September 2026 there is a contact point for vulnerability reports (security.txt) and a written reporting process; a bill of materials of the third-party libraries is produced with every release. The remaining obligations, among them the declaration of conformity and CE marking, apply from 11 December 2027 and will be implemented by then.