Zerosmtp README

Contents

• What's in here
• Quickstart
• Why ZeroSMTP?
• ⭐ Support ZeroSMTP
• How does this compare to other options?
• GitHub Actions
• Code Examples
• Security & Deliverability
• Star History

Arrived from the GitHub Marketplace?

This page is the README of the whole project, which is a free SMTP relay — so the action you came for is below the fold. Here it is:

yaml

Copy

- uses: msgwing/ZeroSMTP@v1
  with:
    host: smtp.office365.com
    cert-expiry-days: '14'

It checks outbound SMTP from the runner — ports, TLS, certificate and the AUTH mechanisms offered — and fails the job when the mail server's certificate is inside the window you set. Nobody watches a mail certificate; it expires on a Sunday and the first report is somebody saying scanning stopped working.

No install and no npm: the tool has no dependencies, so the action runs the file shipped beside it. Every input, and the scheduled-canary setup that reports without failing, is in GitHub Actions further down.

What's in here

Plus what every error message actually means, and a migration guide that covers Graph API, Direct Send and paid relays — not just this one.

How big is this actually? Nobody had published a number, so we measure one every week: at least 24,960 public files on GitHub still contain a Microsoft 365 SMTP hostname. That is a count of files, not of systems that will break, and the page says exactly what it does and does not mean — along with the raw data, so you can check it rather than trust it.

Getting 535 5.7.139 Authentication unsuccessful, basic authentication is disabled? That's Microsoft switching off Basic auth for SMTP AUTH — start here. Three of the four causes are still reversible until the end of December 2026.

Want to know the day this changes? Subscribe to the dated timeline — one comment per confirmed change, nothing else.

Terminal

Copy

npx zerosmtp-check --explain "535 5.7.139 Authentication unsuccessful"

Paste whatever your client printed — a Postfix SASL line, a Python traceback, 1102 off a Kyocera panel, or the curl: (67) Login denied that hides the server's answer entirely. They are the same refusal wearing different clothes, and it says which case you are in and whether it can still be switched back on. No install, nothing sent.

curl --url "smtps://mx.msgwing.com:465" \
  --user "$ZEROSMTP_USERNAME:$ZEROSMTP_PASSWORD" \
  --mail-from "$ZEROSMTP_FROM" --mail-rcpt "$ZEROSMTP_TO" \
  --upload-file <(printf 'Subject: Test\r\n\r\nHello from ZeroSMTP!') --ssl-reqd

That's the whole thing — no SDK, no API key, just SMTP credentials that work with anything that already speaks SMTP.

Quickstart

1. Register your free account → — 30 seconds, no credit card, no trial. You immediately get a random @msgwing.com login and password.
2. Copy .env.example to .env and fill in your credentials.
3. Run the curl snippet above (export $(grep -v '^#' .env | xargs) first), or pick your language from the Code Examples table — every example reads the same .env variables.
4. Having trouble? Check your network lets SMTP out at all — Test-NetConnection mx.msgwing.com -Port 587 on Windows, or openssl s_client -starttls smtp -connect mx.msgwing.com:587 elsewhere. That is what most first-run failures turn out to be. Then see Error messages · Troubleshooting.

Prefer not to install anything locally? Every runtime used below (Python, PHP, Node, Ruby, Go, Java, Kotlin/Gradle, .NET, Rust) is preinstalled in the included Dev Container / Codespace.

Why ZeroSMTP?

• Nothing to run and nothing to pay for. No mail server, no API key, no credit card, no per-email pricing tier to graduate into.
• Works with anything that already speaks SMTP — apps, scripts, network printers, NAS boxes, IoT hardware. If it has a "SMTP server" field, it works.
• Plain SMTP AUTH still accepted. No OAuth2 flow to implement, which is the whole point for old devices that will never get a firmware update.
• Managed reputation. Accounts are randomly generated on a domain that's actively monitored for abuse, so you're not warming up an IP yourself.
• 21 copy-paste examples across 19 languages, all reading the same environment variables, plus Ansible and Docker Compose recipes and setup guides for Windows Server, Linux, and printers by brand.
• Verifiably up — the card above is a real check against mx.msgwing.com, not a static image: every completed run is drawn, and the spacing printed on it is measured from those runs rather than copied from the schedule. GitHub delays scheduled workflows, so the cron asks for 15 minutes and the median gap is closer to 45.
• Auditable handling — where mail is processed, what is kept and for how long, and the TLS versions the relay actually accepts and refuses, measured rather than claimed: What happens to mail sent through this relay.

Good for: contact forms · password resets · CI/CD and monitoring alerts · scan-to-email · IoT and device notifications · homelabs.

⚠️ Losing SMTP AUTH on Exchange Online / Microsoft 365?

Microsoft disables Basic authentication for SMTP AUTH by default at the end of December 2026. Printers, NAS boxes, backup jobs and monitoring tools that can't do OAuth stop sending — and the alerting ones fail silently, so you find out during the incident they should have warned you about.

Dated timeline → — subscribe and you get an email the day Microsoft changes either date. December 2026 is the default being switched off, not the removal; the final date is announced in H2 2027.

Migration guide → covers every option (Graph API, Direct Send, on-prem relay, paid services), not just this one. What breaks → is the audit list, including models whose vendor has said no OAuth firmware is coming.

Run Find-SmtpAuthExposure.ps1 to get the answer for your own tenant. Read-only, and it counts the mailboxes that inherit the tenant setting — the ones the usual one-liner misses.

Setup guides: Network printers · Popular applications · Linux (Debian/Ubuntu/Rocky/Fedora/openSUSE) · System-wide mail relay (Postfix/msmtp/Exim4) · Windows Server · Exchange Online SMTP AUTH migration · Monitoring alerts · OAuth compatibility list · No OAuth firmware coming · Device case studies · Troubleshooting · Reliability (retries) · vs. other free relays · How much public code breaks · FAQ

Did this get a specific device sending again? Tell us which one — a device report takes a couple of minutes. Vendors publish headline model lists; firmware branches, regional names and OEM rebadges drift away from them, so a report from someone holding the hardware is the part of the compatibility list nobody else can copy. Confirming a device that works is just as useful as reporting one that doesn't.

⭐ Support ZeroSMTP

This project is free, with no paid tier and no ads — it exists because the people who found it useful decided to help the next person find it too.

One star on GitHub is the cheapest way to do that. GitHub ranks and recommends repositories partly by stars, so it changes whether the next sysadmin with a dead printer at 2am finds this — or spends the night rebuilding what is already here.

▶️ Give ZeroSMTP a star on GitHub

Already starred? Create your free account is the second best thing you can do — it takes 30 seconds and it means the next person who lands here finds a healthy, active service rather than a side-project graveyard.

Have a question first? Browse Discussions — the same questions most people ask before trusting a free relay are already answered there.

How does this compare to other options?

Free-tier terms above change over time — check each provider's current pricing page before committing to one.

What about self-hosting my own mail server?

Popular self-hosted options like docker-mailserver, Mailu, or mailcow give you a mailbox on your own domain and full control — but you're the one running Postfix, DKIM/SPF/DMARC, spam filtering, and IP/domain reputation, which is real ongoing maintenance, not a one-time setup. ZeroSMTP is the other end of that trade-off: zero setup and zero maintenance, in exchange for sending from the shared @msgwing.com address instead of your own domain. If you already run one of those and it's working, there's no reason to switch. If you're not sure the effort is worth it yet for a script, contact form, or side project, ZeroSMTP costs nothing to try first.

GitHub Actions

Two actions, and they do opposite things.

msgwing/ZeroSMTP — check that mail can be sent. Runs the connectivity check from the runner and fails the job when the mail server's certificate is inside a window you choose. Nobody watches a mail certificate; it expires on a Sunday and the first report is a user saying scanning stopped working. No credentials and no mail sent.

- uses: msgwing/ZeroSMTP@v1
  with:
    host: smtp.office365.com
    cert-expiry-days: '14'

msgwing/send-email-action — actually send one. For CI failure alerts, deploy notifications and scheduled reports. On the GitHub Marketplace, it wraps the setup below into one step:

- uses: msgwing/send-email-action@v1
  with:
    username: ${{ secrets.ZEROSMTP_USERNAME }}
    password: ${{ secrets.ZEROSMTP_PASSWORD }}
    from: ${{ secrets.ZEROSMTP_USERNAME }}
    to: you@example.com
    subject: "Build failed"
    body: "See the run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

Code Examples

Ready-to-run, production-ready examples for mx.msgwing.com:465 (SSL/TLS) or :587 (STARTTLS), one file per language:

Each example reads credentials from ZEROSMTP_* environment variables (ZEROSMTP_USERNAME, ZEROSMTP_PASSWORD, ZEROSMTP_FROM, ZEROSMTP_TO, ZEROSMTP_SUBJECT) — never hardcode real credentials into a script.

Deployment recipes

Not every migration is a code change. Two of the places SMTP settings actually live:

Installing dependencies

Every example that needs a third-party library has a matching manifest at the repo root, so you can install with each ecosystem's normal command instead of hunting down library names/versions yourself:

Easy Configuration:

• Login: randomly generated address @msgwing.com
• SMTP Server: mx.msgwing.com
• Port: 587 (STARTTLS) or 465 (SSL/TLS)
• Encryption: SSL/TLS - required

We respect your privacy - your data is not processed for any marketing or commercial purposes.

Security & Deliverability

What we do:

• SPF, DKIM and DMARC (p=reject) are aligned on msgwing.com — check it yourself: dig txt msgwing.com, dig txt _dmarc.msgwing.com.
• Accounts that abuse the relay are actively removed (see FAQ).
• Sending is rate-limited per account to keep the shared domain's reputation good for everyone (see sending limits).

What we don't promise: a shared domain means shared risk. No single account controls the reputation of the whole pool, unlike your own domain, where you're the only one who can damage it. If mail must come from your own domain, ZeroSMTP is the wrong tool — see Alternatives.

What we don't disclose, and why: see SECURITY.md.

Test it yourself

Don't take our word for it — check with mail-tester.com:

1. Create a free SMTP account at msgwing.com
2. Use our PowerShell test script: SendEmailTest_mail-tester.com.ps1
3. Generate a random email at mail-tester.com and send a test message from your @msgwing.com address
4. Read the score and the detailed analysis

If you have any questions, feel free to contact us: abuse@msgwing.com

Registration is available at: https://msgwing.com

Star History