Troubleshooting

Start with evidence, not a reinstall.

Run smtpready doctor before changing configuration. It checks the Windows service, SMTP listener, certificates, Microsoft authorization and reachability, and licensing separately.

POWERSHELL

smtpready status
smtpready doctor
smtpready doctor --json

Every failed check includes observed evidence and a corrective action.

What failed?

Fix the failed boundary.

Change one thing at a time. Start with the failed doctor check.

Device cannot connectLocal ingress

Confirm the configured host address, port 25 listener and the Domain/Private firewall rule. Unknown source addresses are rejected even when the firewall permits the connection.

Get-NetTCPConnection -State Listen | Where-Object LocalPort -eq 25

STARTTLS or device authentication failsDevice policy

Inspect the device record and SMTP certificate. Authenticated devices require STARTTLS by default. A lost generated device password cannot be recovered; recreate the device credential.

smtpready device show DEVICE_ID

Microsoft authorization is pendingTenant scope

Exchange Application RBAC can take roughly 30 minutes to two hours to propagate. Observe with doctor; do not recreate the Entra application. Once both scope checks pass, rerun Microsoft setup to persist readiness.

smtpready doctor

Microsoft authorization was revokedSecurity stop

A relay-mailbox 403 after readiness, or any successful out-of-scope send, is not an ordinary delivery error. Stop the service, repair the RBAC scope, then rerun Microsoft setup before resuming.

Stop-Service smtpready

Mail is queued but not deliveringDispatch

Expired certificates, authorization loss or mailbox errors can pause dispatch. Correct the failed doctor check; accepted queue entries remain intact. License validity controls new submissions, not delivery of already accepted mail.

smtpready queue list

Queue or disk pressureCapacity

SMTPReady warns below 2 GiB free. Below 500 MiB, or at configured queue limits, new SMTP submissions receive temporary failure while existing entries keep their state.

smtpready queue list

License problemEntitlement

Check cached entitlement separately from Microsoft mail authorization. License state does not widen or replace the Microsoft security boundary.

smtpready license status

Need help?

Send enough evidence to diagnose the problem.

Do not send mailbox passwords, certificate private keys, message bodies, or license keys.

Include

SMTPReady version
what you expected vs what happened
the failing doctor check
a redacted support bundle when useful

smtpready diagnostics enable
smtpready support-bundle create
smtpready diagnostics disable

Email support