Hosting MTA-STS Policies with GitHub Pages

Secure email delivery—without infrastructure. Learn how to host your MTA-STS policy file over HTTPS using GitHub Pages, at no cost and with full admin control.

MTA-STS (Mail Transfer Agent – Strict Transport Security) is one of the best defences against SMTP downgrade attacks and email interception. To enforce MTA-STS, your domain must serve a valid policy file over HTTPS from a very specific location: https://mta-sts.<yourdomain>/.well-known/mta-sts.txt. If you don't already run a web server for this subdomain, GitHub Pages is a secure, free alternative that handles TLS certificates and hosting while you stay in control.

Why Use GitHub Pages?

  • Free Hosting: No infrastructure costs or server management required.
  • Automatic HTTPS: GitHub handles SSL certificate provisioning via Let's Encrypt.
  • Version Control: Your policy file is fully version-controlled and easily updated.
  • Global CDN: Fast, reliable access worldwide through GitHub's infrastructure.
  • Custom Domains: Easy setup with your own subdomain for MTA-STS compliance.

Before You Start

You'll need:

Step-by-Step Guide

  1. Create a New GitHub Repository
    • Go to github.com/new
    • Name it anything (e.g., mta-sts-policy)
    • Set visibility to Public (required for GitHub Pages on free accounts)
    • Create the repo
  2. Create the Policy File
    • In your repo, click Add file → Create new file
    • Name it exactly: .well-known/mta-sts.txt
    • Paste in your MTA-STS policy (use our MTA-STS readiness checker to generate a sample)
    • Commit the file to the main branch
    Sample Policy Content:
    version: STSv1
mode: testing
mx: mx1.yourdomain.com
mx: mx2.yourdomain.com
max_age: 86401

    Note: Replace mx1.yourdomain.com & mx2.yourdomain.com with your actual MX records.

  3. Enable GitHub Pages
    • Go to Settings → Pages
    • Under "Source," choose Deploy from a branch
    • Select main branch and root / folder
  4. Create a Custom Domain for MTA-STS
    • Go to your DNS provider and create a CNAME record:
    mta-sts.yourdomain.com → <username>.github.io
  5. Link the Custom Domain in GitHub
    • Back in Settings → Pages, enter your custom domain: mta-sts.yourdomain.com
  6. Enable HTTPS Enforcement
    • Wait for GitHub to issue the HTTPS certificate (usually takes a few minutes, but can take up to 15 minutes)
    • Once the certificate is issued, go back to Settings → Pages
    • Check the Enforce HTTPS checkbox to ensure all traffic is redirected to HTTPS

    Important: The "Enforce HTTPS" option will only be clickable after GitHub has successfully issued the SSL certificate. If you don't see this option, wait a few more minutes and refresh the page.

Final Checks

Use Cydaura's free MTA-STS Readiness Checker to confirm:

  • HTTPS is reachable and certificate is valid
  • The mta-sts DNS subdomain resolves correctly
  • Your _mta-sts DNS TXT record is present and correctly formatted
  • The .well-known/mta-sts.txt file is valid and reachable
  • Monitor the TLS Reports for your domain for a reasonable period (2-8 weeks is usually enough) to ensure there are no failures
  • Once you're happy, you can move to enforce mode by editing the policy file to change the mode: testing line to mode: enforce, increase the Max_Age to 1814400 (21 days) and update the _mta-sts DNS TXT record id to a new value

Tips & Limitations

Advantages:

  • ✅ Free, globally accessible HTTPS hosting
  • ✅ Automatic certificate management
  • ✅ No infrastructure required
  • ✅ Fully version-controlled

Limitations:

  • Requires public repo (unless using GitHub Pro)
  • DNS propagation and HTTPS certificate issuance can take a few minutes to hours

Test Your MTA-STS Deployment

Once you've deployed your MTA-STS policy using GitHub Pages, you'll want to verify everything is working correctly before moving to enforce mode.

Validate Your Setup

Use our free MTA-STS Readiness Checker to test your deployment and identify any configuration issues before they impact email delivery.

Test Your MTA-STS Policy →

Our tool checks your policy syntax, DNS records, HTTPS configuration, and provides actionable feedback to ensure your MTA-STS implementation is ready for production use.

Further Reading & Resources

Need Help?

Cydaura has worked with public and private sector teams across the UK and beyond to implement MTA-STS and other secure email protocols. Whether you're running a proof of concept or need enterprise-grade implementation support, we're here to help.

Book a free consultation