Troubleshooting
Mail not leaving? Start with status and logs.
Run smtpready doctor for passive local evidence. Use smtpready doctor --live only when you explicitly want Microsoft authorization probes.
PowerShell operator guide: setup, message lookup and safe recovery
smtpready status
smtpready doctor
smtpready logs --since 30mThis default sequence is passive; it sends no network requests or mail.What failed?
Find which part failed.
Change one thing at a time. Start with the failed doctor check.
Did SMTPReady accept this email?Evidence
The sender's 250 2.0.0 queued as UUID is proof of durable local acceptance, not Microsoft submission or recipient delivery. Use that UUID with smtpready queue show MESSAGE_ID and smtpready logs --message MESSAGE_ID. A missing queue row or empty retained-log search proves neither delivery nor loss.
Status separates the Windows service, observed listener, intake limitations and Microsoft dispatch pause. A running process or bound listener does not prove end-to-end acceptance; passive status deliberately leaves that unknown.
One message is retryingRecovery
A scheduled retry is automatic recovery, not proof that all delivery is blocked. Inspect the message's error code, attempt count and NextAttemptAt. For DNS failures, restore name resolution; do not rotate credentials. For HTTP 429, wait for the scheduled retry honoring Microsoft's Retry-After. A timeout or network reset can leave the request outcome unknown; at-least-once retry can duplicate submission.
smtpready queue list --state retryMicrosoft accepted it, but it is missing downstreamMail flow
Graph HTTP 202 means Microsoft accepted submission, not that the recipient received it. Investigate in Exchange Online message trace using sender, recipient, time and Internet Message-ID where known. A Graph request-id is HTTP evidence, not Internet Message-ID; SMTPReady's queue UUID is a separate local identifier.
Logs are empty or unavailableHistory
No retained events matched means only that the bounded retained history has no match. Message-filtered searches never substitute unrelated Windows startup events. Evidence unavailable means the source could not be read: use elevated PowerShell and inspect protected log storage access and free space. Logging degradation does not undo an already committed SMTP acceptance. Do not delete queues to repair logs.
smtpready logs --since 30mDevice 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 25STARTTLS 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_IDMicrosoft authorization is pendingTenant scope
Exchange Application RBAC can take roughly 30 minutes to two hours to propagate. Observe with smtpready doctor --live; it can send a labelled diagnostic message, so use it deliberately. Do not recreate the Entra application. Once both scope checks pass, rerun Microsoft setup to persist readiness.
smtpready doctor --liveMicrosoft 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 smtpreadyMail 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 listUse smtpready queue show MESSAGE_ID with the UUID from the sender's SMTP reply to inspect retry state. A missing queue entry does not prove recipient delivery. Deleting a queued message is permanent; retrying all eligible messages can cause a burst of mail. Both queue delete MESSAGE_ID and queue retry-all require terminal confirmation, or explicit --yes in scripts. JSON output does not grant consent.
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 listLicense problemEntitlement
Check cached entitlement separately from Microsoft mail authorization. License state does not widen or replace the Microsoft security boundary.
smtpready license statusNeed help?
Send enough evidence to diagnose the problem.
Do not send mailbox passwords, certificate private keys, message bodies, or license keys.
- SMTPReady version
- what you expected vs what happened
- the failing
doctorcheck - a redacted support bundle when useful
smtpready diagnostics enable
smtpready support-bundle create
smtpready diagnostics disableEmail support