Installation
Download SMTPly-Setup-latest.exe from the download area. Run the installer as administrator. The wizard guides you through four steps — in 99% of scenarios the default values are the right choice. Click any screenshot to view it full-size.
Step 1 — Choose destination folder
Keep the default path C:\Program Files\SMTPly unless you have a specific reason to change it. Setup needs around 370 MB for the service, GUI and the embedded .NET 10 runtime.
Step 2 — Additional tasks
The wizard offers two options, both enabled by default:
- Create a desktop icon — places a shortcut to the GUI on your desktop.
- Install and start Windows service „Smtply" — registers and launches the background service so the relay keeps running regardless of who is logged in. Leave this enabled — without the service you would need to keep the GUI open at all times.
Step 3 — Ready to install
Review the summary and click Install. The actual installation usually takes under a minute.
Step 4 — Finish
After a successful install you can launch SMTPly straight away. The Launch SMTPly checkbox is pre-selected — after clicking Finish, the GUI opens automatically and, on first start, jumps directly into the settings so you can enter your Azure app details.
All components are placed under C:\Program Files\SMTPly\, configuration and logs under C:\ProgramData\Smtply\. The service runs as Smtply under the LocalSystem account and starts automatically with Windows.
Verify integrity
The SHA-256 checksum of each released version is listed in the release entry and on the download page. Verify your download before installing with:
Get-FileHash -Algorithm SHA256 .\SMTPly-Setup-latest.exeRegister the Azure app
SMTPly authenticates with Microsoft Graph via an Azure app registration using the client credentials flow. That means: no user login, the app sends on behalf of a configured sender address.
There are two ways to get there. SMTPly signs you in with Microsoft and creates the registration for you — that takes about a minute. If you prefer clicking yourself, follow the manual guide below; it takes about ten minutes. The result is identical either way. For special cases there is also Path C with a PowerShell script.
Jump straight to: Path A — assistant · Path B — manually in the Entra admin center · Path C — PowerShell script
Path A — let SMTPly create it (recommended)
On the first start as administrator the setup assistant opens by itself. Later you can reach it via Settings → General → Open setup assistant.
The assistant walks you through seven steps, from the welcome screen to a verified test mail. This is what it looks like:
Step 1 — Welcome
Step 2 — Pick a path
Step 3 — Connect Microsoft 365
What this creates in your tenant. An app registration named SMTPly Relay, a client secret valid for 24 months, the matching service principal and the Mail.Send permission — exactly what Path B creates by hand. Nothing is installed on your server, and the secret never leaves it: it goes straight into the configuration and is stored DPAPI-encrypted.
On a server without a browser (Server Core) SMTPly automatically offers device code sign-in: you get a code, sign in on another machine, and the assistant waits meanwhile.
Microsoft's consent dialog
After the click, Microsoft's sign-in window opens. Sign in with an administrator account of your tenant. Microsoft then asks whether SMTPly.app should be granted the permissions it needs:
Clicking the arrows expands each permission. That is worth doing — you should know what you are agreeing to:
| Permission | What SMTPly needs it for |
|---|---|
Application.ReadWrite.All"Read and write applications" | Create the app registration SMTPly Relay in your tenant and give it a client secret. Without this permission the registration cannot be created. |
AppRoleAssignment.ReadWrite.All"Manage app permission grants and app role assignments" | Assign the Mail.Send permission to the new registration and grant admin consent for it. Microsoft offers no narrower version of this permission. |
User.Read"Sign you in and read your profile" | Standard for any sign-in. SMTPly uses it to show which account you are signed in with. |
offline_access"Maintain access to data you have given it access to" | Requested automatically by Microsoft. SMTPly stores no token — the sign-in applies to this one setup run only. |
The box "Consent on behalf of your organization" has to be ticked. Both of the first two permissions require admin consent; without the tick, setup stops with a message about missing rights.
What remains afterwards — and what does not. SMTPly.app holds these rights for as long as the consent stands. They are tied to the signed-in account: the application always acts on its behalf, never on its own, and nothing happens without a sign-in. No access token is stored.
You can revoke the consent at any time in the Entra admin center under Enterprise applications → SMTPly.app → Permissions. The SMTPly Relay registration is independent of that and keeps its single permanent permission: Mail.Send. That registration is what your server sends mail with — not SMTPly.app. If you would rather avoid the consent from the start, use Path B.
An error page in the browser at the end is normal. For the sign-in, SMTPly briefly opens a listener on a localhost address; Microsoft posts the sign-in code back to it. Once it has arrived, that listener closes. If the browser requests the address again, for instance when going back or restoring the tab, it finds nothing there and shows ERR_CONNECTION_REFUSED or ERR_CONNECTION_RESET.
This is not a failure. Whether setup worked is shown in SMTPly itself: either the new tenant appears or a red message states the reason. You can close the browser tab.
Step 4 — Define the sender
Step 5 — Devices and network
Step 6 — Check
Step 7 — Done
Path B — manually in the Entra admin center
This guide walks you through the same registration by hand in eight steps. It takes about ten minutes and runs up to and including Permissions & admin consent. Click any screenshot to view it full-size.
Step 1 — Create a new app registration
- Open the Entra admin center as global administrator.
- Navigate to Identity → Applications → App registrations.
- Click + New registration.
- Name: e.g.
SMTPly Relay. - Supported account types: Accounts in this organizational directory only.
- Redirect URI: leave blank.
- Click Register.
Step 2 — Note tenant ID and client ID
After registration you land on the app overview page. Write down two values that SMTPly needs later:
- Application (client) ID — the GUID of your app registration
- Directory (tenant) ID — the GUID of your tenant
Step 3 — Create a client secret
- In the left navigation: Certificates & secrets.
- Tab Client secrets → + New client secret.
- Description:
SMTPly Production(or any name you like). - Expiry: 24 months recommended (longer lifetimes avoid maintenance interruptions).
- Click Add.
Step 4 — Copy the secret value immediately
After creation the value is displayed once in plain text. Copy it now — after navigating away it is no longer visible, only the first/last characters remain.
Important: Note the expiry date of the secret. SMTPly warns in the GUI 14 days before expiry by default and can additionally send an email notification — you can update the value later in settings.
Path C — PowerShell script
For special cases: a signed script that creates the same registration as Path A. It is meant for environments where the sign-in window cannot open and device code sign-in is not an option either, or when a colleague with tenant rights is to do the setup on a different machine.
The application no longer offers this path. Up to version 1.7.32 the setup assistant started the script itself. That required three things that could go wrong: starting PowerShell, installing two Graph modules, and then reading a file that held the client secret in plain text on disk. Since version 1.8.0 SMTPly does it directly — the script remains here for the cases where that is not possible.
If you have already set up via Path A or B, you do not need it.
Run it as an administrator of your tenant:
powershell -ExecutionPolicy Bypass -File .\azure-setup.ps1 -OutFile .\result.jsonThe script first shows an overview of every step before it changes anything. It then signs you in via the browser, creates the app registration, client secret, service principal and the Mail.Send permission, and writes the result to the file you named. Enter the values from it — directory ID, application ID, secret and expiry date — into SMTPly under Settings → Microsoft 365.
The result file contains the client secret in plain text. Delete it as soon as the values are in SMTPly.
What the script installs on the machine running it: Microsoft.Graph.Authentication and Microsoft.Graph.Applications from the PowerShell Gallery — for the signed-in user only (-Scope CurrentUser), no admin rights, no system-wide install. If the NuGet package provider is missing (a component of PowerShell itself, not part of SMTPly), the script adds it automatically. What happens during sign-in: the script signs you in through Microsoft's own application "Microsoft Graph Command Line Tools". Microsoft requires consent on behalf of the organisation for this — which grants that Microsoft application the permanent rights Application.ReadWrite.All and AppRoleAssignment.ReadWrite.All in your tenant. They can be removed again under Enterprise applications → Microsoft Graph Command Line Tools → Permissions.
The script is signed with the same certificate as the installer (IT-Beratung - Andreas Hähnel), so it can be verified and read before running. A log of the run is written next to the result file; the client secret is not in it.
Permissions & admin consent
Step 5 — Add an API permission
- In the left navigation: API permissions.
- At the top click + Add a permission.
- In the right panel select Microsoft Graph.
Step 6 — Choose „Application permissions"
SMTPly runs as a background service without a signed-in user, so it needs application permissions (not „Delegated permissions"). This choice is critical — with delegated permissions the relay would not work.
Step 7 — Enable Mail.Send
In the search field type mail.send. Under Mail the permission Mail.Send appears — tick the checkbox and click Add permissions at the bottom.
Step 8 — Grant admin consent
Back on the API permissions page: the status of Mail.Send initially shows „Admin consent required". Click Grant admin consent for <your tenant> at the top and confirm. The status switches to Granted (green check mark).
Optional: restrict send-as. By default, the app can send from any mailbox in the tenant. For least-privilege, use an application access policy to narrow it down to exactly the desired mailbox — recommended for production setups.
Do not use the general mailbox. Microsoft files a copy of every sent message under Sent Items of the sender address. If you use a shared mailbox such as info@, every document sent through it is visible to everyone with access, confidential scans included. Create a dedicated mailbox just for SMTPly, ideally a shared mailbox that only a few chosen people can open, and have the copies deleted after a few days with a retention policy. More in Troubleshooting.
Values needed for SMTPly
| Field in SMTPly | Location in Azure |
|---|---|
| Tenant ID | App overview → Directory (tenant) ID |
| Client ID | App overview → Application (client) ID |
| Client secret | Certificates & secrets → Value (visible only once) |
| Sender address | A dedicated Microsoft 365 mailbox just for SMTPly in the tenant, e.g. smtp@company.com, not a shared general mailbox |
First start & setup wizard
On first launch the wizard guides you through these sections:
- Microsoft 365 — enter Azure details, send a test connection.
- SMTP listener — set port, bind address, max size.
- STARTTLS / implicit TLS (optional) — choose or generate a certificate.
- IP whitelist — which devices are allowed to relay. Since 1.8.8, “Only applications on this server” listens on all addresses and allows exactly the addresses of this server (
127.0.0.1,::1and the addresses of its network adapters); every other computer is rejected. This way an application that addresses the server by its host name reaches the relay too. - Privacy — logging behavior for subject, addresses, rejected mails.
- Start service — the Windows service goes live.
All settings can be changed later via the "Settings" navigation item.