Every email project starts with a lie:

"I'll just test it with SMTP real quick."

That was my plan while working on EpicMail.

I wanted a boring, repeatable provider smoke test:

1. Pick a mailbox provider.
2. Add host, port, username, and password.
3. Send one message.
4. Move on with my life.

Instead, I got a tour of how consumer email providers have slowly turned "send an email" into an authentication archaeology dig.

The three providers I tested were:

• Gmail
• iCloud Mail
• Outlook.com

The surprise was not that OAuth is complicated. Everyone knows OAuth is complicated.

The surprise was how much easier the entire C# provider-testing loop became once I stopped trying to solve OAuth on day one and used app passwords for developer-owned test accounts.

This is not an argument that app passwords are better than OAuth.

It is an argument that they are a fantastic debugging ladder.

But maybe shipping the ladder as the building is not the answer also.

First C# lesson: do not start with System.Net.Mail.SmtpClient

If you are building this in .NET, the first trap is that the built-in class name looks exactly like what you want:

using System.Net.Mail;

var client = new SmtpClient("smtp.example.com");

But Microsoft's own docs say System.Net.Mail.SmtpClient is not recommended for new development because it does not support many modern protocols, and they point developers toward MailKit or other libraries instead.

So for EpicMail-style testing, I reached for MailKit:

dotnet add package MailKit

The boring version of the test looks like this:

using MailKit.Net.Smtp;
using MailKit.Security;
using MimeKit;

public sealed record SmtpSmokeTestOptions(
    string Provider,
    string Host,
    int Port,
    string Username,
    string Secret);

public static async Task SendSmokeTestAsync(
    SmtpSmokeTestOptions options,
    string recipient,
    CancellationToken cancellationToken = default)
{
    var message = new MimeMessage();
    message.From.Add(MailboxAddress.Parse(options.Username));
    message.To.Add(MailboxAddress.Parse(recipient));
    message.Subject = $"EpicMail smoke test: {options.Provider}";
    message.Body = new TextPart("plain")
    {
        Text = "If this arrived, SMTP is alive."
    };

    using var client = new SmtpClient
    {
        Timeout = 15_000
    };

    await client.ConnectAsync(
        options.Host,
        options.Port,
        SecureSocketOptions.StartTls,
        cancellationToken);

    await client.AuthenticateAsync(
        options.Username,
        options.Secret,
        cancellationToken);

    await client.SendAsync(message, cancellationToken);

    await client.DisconnectAsync(quit: true, cancellationToken);
}

That is the code I wanted the entire project to feel like.

A tiny abstraction.

A tiny config object.

A tiny smoke test.

And then reality showed up.

The provider matrix I wanted

For a developer-owned test account, the provider table feels like it should be this simple:

As configuration, that becomes extremely boring:

{
  "SmtpSmokeTests": [
    {
      "Provider": "Gmail",
      "Host": "smtp.gmail.com",
      "Port": 587,
      "Username": "you@gmail.com",
      "Secret": "<gmail app password>"
    },
    {
      "Provider": "iCloud",
      "Host": "smtp.mail.me.com",
      "Port": 587,
      "Username": "you@icloud.com",
      "Secret": "<apple app-specific password>"
    },
    {
      "Provider": "Outlook.com",
      "Host": "smtp-mail.outlook.com",
      "Port": 587,
      "Username": "you@outlook.com",
      "Secret": "<microsoft app password or oauth token path>"
    }
  ]
}

The protocol part is not the hard part.

The hard part is proving to three giant identity systems that your tiny test harness is not suspicious.

Gmail: the trick is not your normal password

Gmail's SMTP settings are conventional enough: smtp.gmail.com, port 587, STARTTLS, authentication required.

The trick is that the useful test credential is not your normal Google password.

It is a generated app password.

That turns this kind of failure:

535-5.7.8 Username and Password not accepted

into this kind of progress:

250 2.1.5 OK

For a smoke test, that is a massive difference.

No consent screen.

No redirect URI.

No token refresh.

No "is my OAuth app still in testing mode?" rabbit hole.

Just a dev mailbox and a generated credential.

Google's own Gmail client setup docs list smtp.gmail.com, STARTTLS on port 587, and suggest trying an app password when 2-Step Verification is enabled and a mail client cannot sign in.

iCloud Mail: refreshingly literal

iCloud Mail was the provider that felt closest to the old-school SMTP mental model.

Apple's settings are direct:

SMTP server: smtp.mail.me.com
Port: 587
Authentication: required
Username: full iCloud email address
Password: app-specific password

The important detail is the username.

For SMTP, Apple says to use the full iCloud Mail email address, not just the local part.

So this is good:

you@icloud.com

This is the kind of tiny detail that costs 30 minutes when your test harness only says:

Authentication failed.

And it is exactly why provider diagnostics matter.

A good product should say:

iCloud rejected SMTP authentication.

Check:
- Are you using smtp.mail.me.com on port 587?
- Are you using STARTTLS?
- Is the username your full iCloud Mail address?
- Is the password an Apple app-specific password rather than your Apple Account password?

That is not just error handling.

That is product UX.

Outlook.com: where SMTP becomes an identity-platform problem

Outlook.com is where the simple smoke test started to feel like a boss fight.

The rough shape still looks familiar:

SMTP server: smtp-mail.outlook.com
Port: 587
Encryption: STARTTLS

But then the auth story gets more interesting. With a new Outlook.com test account, I was not able to turn on SMTP... it looked like turned it on, but when I refreshed the page, it showed that it was still off. When I tried to investigate deeper, I noticed that the "Inspect/Developer Tools" Network tab showed an error in the response:

POST https://outlook.live.com/owa/0/service.svc?action=SetConsumerMailbox&app=Mail&n=36
412 (Precondition Failed)
Uncaught (in promise) Error: SetConsumerMailbox failed:
Microsoft.Exchange.Clients.Owa2.Server.Core.OwaInvalidServiceRequestException

Furthermore, Microsoft's Outlook.com SMTP settings list OAuth2 / Modern Auth as the authentication method. The same support surface also documents app passwords for Outlook.com accounts using two-factor authentication when a password is not accepted by another program.

That is where the provider test stops being a socket problem and becomes an account-state problem.

When Outlook.com rejects you, the question is not just:

Did my C# code authenticate correctly?

The question becomes:

Which authentication universe is this account currently living in?

For a developer-owned EpicMail smoke test, an app password was the shortest path to answering the narrow question I cared about first:

Can this adapter send one message through Outlook.com SMTP?

But I would not treat that as the long-term product answer.

For real user onboarding, Outlook.com is clearly pointing the ecosystem toward Modern Auth / OAuth2.

That is the central distinction:

Dev-owned smoke test:
  App password is great.

User-owned production account:
  OAuth2 / provider API is the responsible path.

The problem is that both of those workflows might touch the same SMTP host and port.

So your code has to know which game it is playing.

App passwords are not "better OAuth"

This is the key lesson.

App passwords are not a better security model than OAuth.

They are a faster way to answer a narrower engineering question:

Can this provider send mail from this controlled test account using SMTP?

For EpicMail, that was exactly the question I needed answered first.

The app-password credential shape is tiny:

public sealed record AppPasswordCredential(
    string Username,
    string AppPassword);

The send path is tiny:

await client.AuthenticateAsync(
    credential.Username,
    credential.AppPassword,
    cancellationToken);

OAuth is a different animal:

public sealed record OAuthSmtpCredential(
    string Username,
    string AccessToken,
    string? RefreshToken,
    DateTimeOffset ExpiresAt,
    string[] Scopes,
    string ProviderClientId);

And yes, MailKit can authenticate with an OAuth2 access token:

using MailKit.Security;

var oauth2 = new SaslMechanismOAuth2(
    credential.Username,
    credential.AccessToken);

await client.AuthenticateAsync(oauth2, cancellationToken);

But that line is not the hard part.

The hard part is everything required to make that line safe and repeatable:

• provider app registration
• redirect URIs
• local development callback URLs
• consent screen configuration
• scopes
• token exchange
• refresh token storage
• encryption at rest
• token refresh
• revoked consent
• expired refresh tokens
• tenant or account policy
• provider-specific support docs
• user-facing recovery flows

For a real multi-user product, that work is justified.

For a smoke test, it can be a trap.

The abstraction changed once I separated the two paths

The useful design move was to stop pretending that "SMTP auth" is one thing.

It is not.

At minimum, EpicMail needs to model two credential modes:

public abstract record ProviderCredential(string Username);

public sealed record AppPasswordCredential(
    string Username,
    string AppPassword) : ProviderCredential(Username);

public sealed record OAuthCredential(
    string Username,
    string AccessToken,
    string? RefreshToken,
    DateTimeOffset ExpiresAt) : ProviderCredential(Username);

Then the adapter can be honest:

public interface IEmailProviderAdapter
{
    string ProviderName { get; }

    Task SendSmokeTestAsync(
        ProviderCredential credential,
        string recipient,
        CancellationToken cancellationToken = default);

    ProviderDiagnostic Diagnose(Exception exception);
}

And the Outlook.com adapter can say something useful instead of pretending all failures are equal:

if (ProviderName == "Outlook.com" && credential is AppPasswordCredential)
{
    diagnostic.Warnings.Add(
        "App passwords are useful for controlled Outlook.com smoke tests, " +
        "but OAuth2 / Modern Auth is the better user-facing path.");
}

That warning is not bureaucracy.

It is future you leaving a note for support-ticket you.

The error taxonomy became the real feature

The most useful part of this work was not the successful send.

It was cataloging failures.

The first version of an email integration usually thinks it needs this:

public bool Sent { get; init; }

What it actually needs is closer to this:

public enum ProviderDiagnosticCode
{
    Success,
    TcpConnectionFailed,
    StartTlsFailed,
    AuthenticationRejected,
    SenderRejected,
    RecipientRejected,
    ProviderPolicyRejected,
    RateLimited,
    MessageRejected,
    Unknown
}

Because users do not need to know that SmtpCommandException happened.

They need to know what to do next.

A raw error says:

MailKit.Security.AuthenticationException: Authentication failed.

A useful EpicMail-style diagnostic says:

Outlook.com rejected SMTP authentication.

Check:
- Are you using smtp-mail.outlook.com on port 587?
- Are you using STARTTLS?
- Is this account expecting OAuth2 / Modern Auth?
- If this is a dev-owned smoke test, is the Microsoft app password valid?
- Did Microsoft flag the sign-in in Recent Activity?

That is the difference between supporting SMTP and understanding email providers.

The C# testing loop I wish I had started with

Instead of starting with "send an email," I wish I had started with a checklist:

var checks = new[]
{
    "Can resolve SMTP host",
    "Can open TCP connection",
    "Can upgrade with STARTTLS",
    "Can authenticate",
    "Can send MAIL FROM",
    "Can send RCPT TO",
    "Can send DATA",
    "Can receive final provider response",
    "Can map provider error to setup advice"
};

The happy path is one row in that table.

The product is the rest of the table.

For each provider, I now want cases like:

✅ valid app password
❌ normal account password
❌ revoked app password
❌ wrong SMTP host
❌ wrong port
❌ STARTTLS disabled
❌ username missing full iCloud address
❌ Outlook.com account expects OAuth2 / Modern Auth
❌ provider flags suspicious login
❌ provider accepts login but rejects sender
❌ provider rate-limits or policy-blocks the message

That is where the value is.

A generic SMTP client can throw raw provider errors.

A product should translate them.

The practical rule I ended up with

My current rule for EpicMail is:

For developer-owned smoke tests:
  Use app passwords when the provider supports them.

For user-owned accounts:
  Use OAuth2 / provider-approved auth flows.

For serious production sending:
  Consider transactional email providers instead of consumer inboxes.

App passwords made Gmail, iCloud Mail, and Outlook.com easier to compare because they reduced the test surface area.

That mattered.

It let me test the boring-but-critical pieces first:

• SMTP host and port
• STARTTLS behavior
• message construction
• sender validation
• recipient validation
• provider-specific rejection messages
• useful diagnostics

Then OAuth can come later as a product-grade authentication layer instead of blocking the first transport-layer proof.

OAuth is the production path.

App passwords are the debugging ladder.

Do not ship the ladder as the building... or if you do then version 1.1 should be adding OATH to Outlook, Gmail, iCloud... probably in that order too.

References

• Gmail Help: Gmail SMTP settings and app password troubleshooting
• Apple Support: iCloud Mail server settings for other email client apps
• Microsoft Support: POP, IMAP, and SMTP settings for Outlook.com
• Microsoft Support: Generate an app password for Outlook.com
• Microsoft Learn: System.Net.Mail.SmtpClient is not recommended for new development