SMTP Hopper logo
Log out Request a Demo

Customer Portal

Signed in as customer — welcome back!

Getting started

SMTP Hopper is a lightweight internal SMTP relay for forwarding mail from devices and apps on your LAN — printers, scanners, line-of-business software — out to Microsoft 365 or any authenticated SMTP provider (Amazon SES, SMTP2GO, SendGrid, Mailgun, Postmark, and more). It runs as a native Windows service with a local HTTPS web GUI for configuration.

  • Inbound: LAN devices connect to the relay's SMTP listener (default port 587) and authenticate via SMTP AUTH with a relay-user credential, or are allowed anonymously via the trusted IP whitelist.
  • Queue: accepted mail is written to disk immediately, then delivered by a background worker with exponential backoff (up to 8 attempts) and dead-lettering for permanent failures.
  • Outbound: the queue worker relays each message to your upstream provider over SMTP with TLS.
  • Admin GUI: HTTPS console (default port 8443) for setup, settings, relay users, queue, logs, analytics, and refused connections.

Installation

Interactive install

  1. Copy the installer to the target machine and run it. Windows prompts for administrator elevation — required for service registration and firewall rules.
  2. Complete the standard install wizard. On completion the service is registered and started, and firewall rules for ports 587 and 8443 are added automatically.
  3. Open Start Menu → SMTP Hopper Admin (or browse to https://localhost:8443/) to run first-time setup: create your admin account and configure your outbound connector.
Your browser will warn about the self-signed certificate on first run — that's expected. Replace it with a CA-issued certificate via Settings → TLS certificate when ready.

Silent / unattended install

SmtpHopperSetup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /LOG="C:\install.log"
SwitchEffect
/VERYSILENTNo installer UI at all.
/SILENTProgress bar only, no wizard pages.
/SUPPRESSMSGBOXESSuppresses message boxes so nothing blocks unattended installs.
/NORESTARTNever reboots.
/LOG="path"Writes a full install log — check this first if an unattended install seems to have failed.
/DIR="X:\path"Overrides the install directory.
UAC elevation cannot be suppressed by installer switches. For a fully unattended rollout, launch the installer from an already-elevated context — a Scheduled Task running as SYSTEM, an RMM tool, or Group Policy software deployment.

Uninstall

Uninstall via Control Panel or the Start Menu shortcut. The service is stopped and deregistered and firewall rules are removed. You'll be asked whether to also delete runtime data (config, relay users, queue, logs) — it defaults to keep, so a reinstall picks up where you left off.

Ports & connectivity

PortDirectionPurpose
TCP 587InboundSMTP listener — LAN devices connect here with SMTP AUTH + STARTTLS. Configurable in Settings.
TCP 8443InboundWeb admin GUI (HTTPS).
TCP 25 / 587 / 465OutboundRelay → your mail provider, per your connector settings.
The most common tripwire is outbound connectivity. Microsoft 365 IP connectors typically use outbound TCP 25, which many ISPs and cloud providers block by default. Authenticated providers use 587 or 465, which are less commonly blocked. Confirm your outbound path is open before assuming a misconfiguration elsewhere.

Prerequisites

  • Windows 10/11 or Windows Server, x64. No Node.js or other runtime needed — the executable is fully self-contained (~100MB installed).
  • Administrator rights for installation.
  • An outbound destination: a Microsoft 365 tenant with an inbound connector scoped to this relay's static public IP, or an account with an authenticated SMTP provider (no static IP needed).

Provider setup

Settings → Outbound connector configures where the relay sends mail:

  • Microsoft 365 IP connector — leave the auth username blank. Trust is by the relay's public IP via an inbound connector you configure in the M365 admin center. No credentials are stored.
  • Authenticated provider — fill in the username and password from your provider and pick the matching TLS mode.
TLS modeBehaviorTypical port
STARTTLSConnects plaintext, upgrades to TLS after EHLO587, 2525, 25
Implicit TLSTLS from the moment the socket opens465
NonePlaintext SMTPLocal testing only

Provider notes

  • Amazon SES — use SMTP credentials generated in the SES console (not your AWS access key). Host: email-smtp.<region>.amazonaws.com.
  • SendGrid — username is the literal string apikey; password is your API key.
  • SMTP2GO, Mailgun, Postmark — use the SMTP username/password or API key from that provider's SMTP-relay settings page.
  • Connector changes take effect immediately — no service restart.
  • Saving Settings with the password field blank keeps the existing stored password.
  • Configure your sending domain's SPF/DKIM on the provider's side for deliverability — the relay transports mail; DNS determines trust.

Security model

  • No open relay. SMTP AUTH is required for every inbound connection by default. Devices authenticate with per-device credentials managed under Relay Users.
  • Trusted IP whitelist. Devices that can't do SMTP AUTH can be allowed by exact IP or IPv4 CIDR range — everyone else still authenticates. Only list trusted internal devices; never a public IP or 0.0.0.0/0. Whitelist changes apply immediately.
  • Credential storage. Admin and relay-user passwords are bcrypt-hashed — never stored or logged in plaintext. Outbound provider passwords are stored in the config (they must be presented verbatim upstream) and protected by filesystem ACLs on %ProgramData% — keep that folder locked down.
  • Rate limiting. The Security page's sender rate limit caps per-credential volume to contain a leaked credential's blast radius. Use one credential per device, and disable a relay user immediately if its device is decommissioned or suspect.
  • Network exposure. Keep ports 587 and 8443 scoped to your internal network — never port-forward either from the public internet. Restrict the listener to a specific interface in Settings if needed.

Sync & high availability

Run two or more instances behind a load balancer and the Sync page keeps relay users and the trusted IP whitelist consistent across them. Connector settings, listener ports, TLS certs, the queue, and admin logins stay per-instance by design.

Pairing two instances

  1. On Instance A's Sync page, note "This instance's address".
  2. Still on A, use Add Peer: label, Instance B's address, and a shared secret (generate one and copy it — it's shown once).
  3. On Instance B, Add Peer pointing back at A with the same shared secret.
  4. Click Sync now on either side — both instances converge in a single exchange.
  • Sync runs automatically every 5 minutes, plus on demand via Sync now.
  • Conflicts resolve by last-write-wins; deletions propagate via tombstones (purged after 30 days).
  • Certificates are pinned trust-on-first-use. A cert mismatch status after a peer reinstall is expected — verify out-of-band, then click Re-trust this certificate.
  • Treat each peer's shared secret with the same care as your admin password.

Analytics

The Analytics page charts messages accepted, delivered, and dead-lettered over 24h / 7d / 30d / 90d ranges, and ranks top senders by relay user with counts and total size.

  • Each event records only a timestamp, relay username, envelope sender, and size — never subjects, recipients, or content.
  • Events are stored as small daily files and pruned automatically after 90 days.
  • Charts render server-side as inline SVG — no internet access or browser chart library needed.
  • Whitelisted anonymous senders appear labeled by source IP (e.g. ip:192.168.1.50).

Troubleshooting

Service won't start

Check the service wrapper log under %ProgramData%\SmtpRelay\logs\wrapper\ and the app's own relay.log. The service auto-restarts on failure with staged delays (10s → 30s → 60s).

Port already in use

netstat -ano | findstr :587
netstat -ano | findstr :8443

Free the conflicting port or change the relay's port in Settings (listener port changes require a service restart).

Messages stuck in the queue

Check the message's lastError on the Queue page. Common causes: wrong connector host/port/TLS mode, an M365 connector that doesn't match the relay's actual public IP, wrong provider credentials, or a blocked outbound port (25 especially).

Messages going straight to Dead Letters

A permanent 5xx rejection from the target. A 535 from an authenticated provider almost always means bad credentials. For M365, double-check that the IP configured in the admin center matches what this machine actually egresses as — NAT can surprise you.

Device can't authenticate

  • Confirm the relay user exists and is enabled.
  • Confirm the device uses SMTP AUTH + STARTTLS on the right port. Credentials are case-sensitive.
  • The Refused Connections page shows every turned-away send with source IP and reason — the fastest way to see why.

Locked out of the admin account

Stop the service, delete %ProgramData%\SmtpRelay\admin.json, and restart — this re-triggers first-run setup. Relay users, connector config, and the queue are untouched.

Settings changes don't apply

net stop SmtpHopper
net start SmtpHopper

Listener port/host and log level changes require a service restart; connector and whitelist changes do not.

Known v1 limitations

  • Listener port/host and log level changes require a service restart.
  • Single admin account; no MFA or email-based password reset (see the lockout recovery steps above).
  • Self-signed TLS certificate by default — replace it via Settings.
  • Sync covers relay users and the IP whitelist only; connector settings, ports, certs, and admin logins are per-instance.
  • IPv6 whitelist entries must be exact addresses (no IPv6 CIDR).
Can't find what you need? Head to the Support page — or if it's an idea rather than an issue, we'd love it on the Feature Requests page.