Bastion Mail Sdk

VB.NET

AddHandler client.CommandSent, Sub(s, e) Console.WriteLine("C: " + e.Line)
AddHandler client.ResponseReceived, Sub(s, e) Console.WriteLine("S: " + e.Line)

VB.NET

Dim client As New ImapClient()
client.EnableLogging = True

Code

%TEMP%\yyyy-MM-dd.Application.PROTOCOL.txt

for example:  2026-07-27.Pop3MailClient.IMAP.txt

Command line

Pop3ToSqlite <database> <host> <port> <user> <password>

Pop3ToSqlite mail.db pop.example.net 995 chris@example.net secret

Command line

ImapToSqlite mail.db imap.example.net 993 chris@example.net secret
ImapToSqlite mail.db imap.example.net 993 chris@example.net secret INBOX Archive

Command line

SmtpToSqlite mail.db smtp.example.net 465 chris@example.net secret chris@example.net you@example.org "Hello"

First run

The maildrop holds 5 message(s).

  stored  Quarterly figures
  stored  Re: invoice 10432
  ...

Downloaded 5, already held 0.
The store now holds 5 message(s).

Second run

Store mail.db holds 5 message(s) for this account.
The maildrop holds 5 message(s).
Downloaded 0, already held 5.
The store now holds 5 message(s).

VB.NET

Dim message As New MailMessage()

' From and To are collections, because a message may legitimately
' have several of either. Add takes a display name and an address,
' or just an address.
message.From.Add("Chris", "chris@example.net")
message.[To].Add("alice@example.org")
message.Cc.Add("Accounts", "accounts@example.org")

message.Subject = "Quarterly figures"
message.[Date] = DateTimeOffset.Now

' Generate your own identifier rather than letting the server invent
' one. It gives better threading in the recipient's client, and
' keeping it stable across a retry is what lets them deduplicate.
message.MessageId = "<" & Guid.NewGuid().ToString("N") & "@example.net>"

' A single text body. For anything richer, see the recipes below.
Dim body As New MimePart("text", "plain")
body.SetText("The figures are ready for review.")
message.Body = body

C#

var message = new MailMessage();

// From and To are collections, because a message may legitimately
// have several of either. Add takes a display name and an address,
// or just an address.
message.From.Add("Chris", "chris@example.net");
message.To.Add("alice@example.org");
message.Cc.Add("Accounts", "accounts@example.org");

message.Subject = "Quarterly figures";
message.Date = DateTimeOffset.Now;

// Generate your own identifier rather than letting the server invent
// one. It gives better threading in the recipient's client, and
// keeping it stable across a retry is what lets them deduplicate.
message.MessageId = "<" + Guid.NewGuid().ToString("N") + "@example.net>";

// A single text body. For anything richer, see the recipes below.
var body = new MimePart("text", "plain");
body.SetText("The figures are ready for review.");
message.Body = body;

PowerShell

$message = New-Object Bastion.Mail.MailMessage
$message.From.Add('Chris', 'chris@example.net')
$message.To.Add('alice@example.org')
$message.Cc.Add('Accounts', 'accounts@example.org')

$message.Subject = 'Quarterly figures'
$message.Date = [System.DateTimeOffset]::Now

# Your own identifier, for threading and for deduplication on retry.
$message.MessageId = "<$([guid]::NewGuid().ToString('N'))@example.net>"

$body = New-Object Bastion.Mail.MimePart 'text', 'plain'
$body.SetText('The figures are ready for review.')
$message.Body = $body

VB.NET

' multipart/alternative means "the same content, rendered two ways -
' pick one". The client takes the LAST part it understands, so plain
' text goes first and HTML last. Reverse them and everyone sees
' plain text.
Dim alternative As New Multipart("alternative")

Dim plain As New MimePart("text", "plain")
plain.SetText("The figures are ready for review.")
alternative.Children.Add(plain)

Dim html As New MimePart("text", "html")
html.SetText("<html><body><p>The figures are <b>ready</b> for review.</p></body></html>")
alternative.Children.Add(html)

message.Body = alternative

C#

// multipart/alternative means "the same content, rendered two ways -
// pick one". The client takes the LAST part it understands, so plain
// text goes first and HTML last. Reverse them and everyone sees
// plain text.
var alternative = new Multipart("alternative");

var plain = new MimePart("text", "plain");
plain.SetText("The figures are ready for review.");
alternative.Children.Add(plain);

var html = new MimePart("text", "html");
html.SetText("<html><body><p>The figures are <b>ready</b> for review.</p></body></html>");
alternative.Children.Add(html);

message.Body = alternative;

PowerShell

$alternative = New-Object Bastion.Mail.Multipart 'alternative'

# Plain first...
$plain = New-Object Bastion.Mail.MimePart 'text', 'plain'
$plain.SetText('The figures are ready for review.')
$alternative.Children.Add($plain)

# ...HTML last, because the client takes the last part it understands.
$html = New-Object Bastion.Mail.MimePart 'text', 'html'
$html.SetText('<html><body><p>The figures are <b>ready</b>.</p></body></html>')
$alternative.Children.Add($html)

$message.Body = $alternative

Visual Basic — from a file

' Attachments live beside the body in a multipart/mixed, never inside
' the alternative pair. Wrap whatever body already exists.
Dim mixed As New Multipart("mixed")
mixed.Children.Add(message.Body)

Dim attachment As New MimePart("application", "octet-stream")

' Content-Disposition is what makes it an attachment rather than
' another body part, and carries the file name the recipient sees.
' Quote the name: it may contain spaces.
attachment.ContentDisposition =
    ContentDisposition.Parse("attachment; filename=""" & Path.GetFileName(filePath) & """")

' SetContent takes the raw octets. The library chooses a transfer
' encoding - base64 for binary - and applies it when writing.
attachment.SetContent(File.ReadAllBytes(filePath))

mixed.Children.Add(attachment)
message.Body = mixed

C# — from a file

// Attachments live beside the body in a multipart/mixed, never inside
// the alternative pair. Wrap whatever body already exists.
var mixed = new Multipart("mixed");
mixed.Children.Add(message.Body);

var attachment = new MimePart("application", "octet-stream");

// Content-Disposition is what makes it an attachment rather than
// another body part, and carries the file name the recipient sees.
// Quote the name: it may contain spaces.
attachment.ContentDisposition =
    ContentDisposition.Parse("attachment; filename=\"" + Path.GetFileName(filePath) + "\"");

// SetContent takes the raw octets. The library chooses a transfer
// encoding - base64 for binary - and applies it when writing.
attachment.SetContent(File.ReadAllBytes(filePath));

mixed.Children.Add(attachment);
message.Body = mixed;

Visual Basic — from bytes

' Nothing has to come from disk. A report generated in memory is
' attached the same way - only the media type differs, and it is
' worth setting accurately so the recipient's client offers the right
' application to open it.
Dim mixed As New Multipart("mixed")
mixed.Children.Add(message.Body)

Dim attachment As New MimePart("text", "csv")
attachment.ContentDisposition =
    ContentDisposition.Parse("attachment; filename=""" & fileName & """")
attachment.SetContent(content)

mixed.Children.Add(attachment)
message.Body = mixed

C# — from bytes

// Nothing has to come from disk. A report generated in memory is
// attached the same way - only the media type differs, and it is
// worth setting accurately so the recipient's client offers the right
// application to open it.
var mixed = new Multipart("mixed");
mixed.Children.Add(message.Body);

var attachment = new MimePart("text", "csv");
attachment.ContentDisposition =
    ContentDisposition.Parse("attachment; filename=\"" + fileName + "\"");
attachment.SetContent(content);

mixed.Children.Add(attachment);
message.Body = mixed;

PowerShell

# Wrap whatever body already exists in a mixed part, then add the file.
$mixed = New-Object Bastion.Mail.Multipart 'mixed'
$mixed.Children.Add($message.Body)

$attachment = New-Object Bastion.Mail.MimePart 'application', 'octet-stream'

$name = [System.IO.Path]::GetFileName($filePath)
$attachment.ContentDisposition =
    [Bastion.Mail.ContentDisposition]::Parse("attachment; filename=""$name""")

$attachment.SetContent([System.IO.File]::ReadAllBytes($filePath))

$mixed.Children.Add($attachment)
$message.Body = $mixed

VB.NET

' An inline image is NOT an attachment. It is a resource the HTML
' refers to, so the two go in a multipart/related and the HTML
' points at the image by Content-ID.
Dim contentId = Guid.NewGuid().ToString("N") & "@example.net"

Dim html As New MimePart("text", "html")
html.SetText("<html><body><p>Our logo:</p>" &
             "<img src=""cid:" & contentId & """ alt=""logo"" />" &
             "</body></html>")

Dim image As New MimePart("image", "png")

' The angle brackets are part of the header syntax. The cid: URL in
' the HTML uses the identifier WITHOUT them.
image.ContentId = "<" & contentId & ">"
image.ContentDisposition = ContentDisposition.Parse("inline")
image.SetContent(imageBytes)

Dim related As New Multipart("related")
related.Children.Add(html)
related.Children.Add(image)

message.Body = related

C#

// An inline image is NOT an attachment. It is a resource the HTML
// refers to, so the two go in a multipart/related and the HTML
// points at the image by Content-ID.
var contentId = Guid.NewGuid().ToString("N") + "@example.net";

var html = new MimePart("text", "html");
html.SetText("<html><body><p>Our logo:</p>" +
             "<img src=\"cid:" + contentId + "\" alt=\"logo\" />" +
             "</body></html>");

var image = new MimePart("image", "png");

// The angle brackets are part of the header syntax. The cid: URL in
// the HTML uses the identifier WITHOUT them.
image.ContentId = "<" + contentId + ">";
image.ContentDisposition = ContentDisposition.Parse("inline");
image.SetContent(imageBytes);

var related = new Multipart("related");
related.Children.Add(html);
related.Children.Add(image);

message.Body = related;

VB.NET

Dim description As New StringBuilder()

' From is a collection, but in practice carries one address.
If message.From.Count > 0 Then
    description.AppendLine("From:    " & message.From(0).Address)
    description.AppendLine("Name:    " & message.From(0).DisplayName)
End If

description.AppendLine("Subject: " & message.Subject)

' Date is nullable - a malformed or missing Date header is common
' enough in real mail that it cannot be assumed present.
If message.[Date].HasValue Then
    description.AppendLine("Date:    " & message.[Date].Value.ToString("u"))
End If

' TextBody and HtmlBody find the right part in the tree for you.
' Either may be Nothing: a message is not obliged to have both.
description.AppendLine("Text:    " & If(message.TextBody, "(none)"))
description.AppendLine("HTML:    " & If(message.HtmlBody, "(none)"))

For Each attachment In message.Attachments
    description.AppendLine("Attached: " & attachment.FileName)
Next

C#

var description = new StringBuilder();

// From is a collection, but in practice carries one address.
if (message.From.Count > 0)
{
    description.AppendLine("From:    " + message.From[0].Address);
    description.AppendLine("Name:    " + message.From[0].DisplayName);
}

description.AppendLine("Subject: " + message.Subject);

// Date is nullable - a malformed or missing Date header is common
// enough in real mail that it cannot be assumed present.
if (message.Date.HasValue)
    description.AppendLine("Date:    " + message.Date.Value.ToString("u"));

// TextBody and HtmlBody find the right part in the tree for you.
// Either may be null: a message is not obliged to have both.
description.AppendLine("Text:    " + (message.TextBody ?? "(none)"));
description.AppendLine("HTML:    " + (message.HtmlBody ?? "(none)"));

foreach (var attachment in message.Attachments)
    description.AppendLine("Attached: " + attachment.FileName);

PowerShell

[pscustomobject]@{
    From        = ($message.From | ForEach-Object { $_.Address }) -join '; '
    Subject     = $message.Subject
    Date        = if ($message.Date.HasValue) { $message.Date.Value.UtcDateTime } else { $null }
    TextBody    = $message.TextBody
    HtmlBody    = $message.HtmlBody
    Attachments = ($message.Attachments | ForEach-Object { $_.FileName }) -join '; '
}

VB.NET

' TextBody, HtmlBody and Attachments cover most needs. Walk the tree
' yourself when they do not - finding every image regardless of
' disposition, say, or reporting the structure for diagnosis.
into.Append(New String(" "c, depth * 2))
into.AppendLine(entity.ContentType.MediaType & "/" & entity.ContentType.MediaSubtype)

Dim branch = TryCast(entity, Multipart)
If branch IsNot Nothing Then
    ' A Multipart holds children and no content of its own.
    For Each child In branch.Children
        WalkParts(child, depth + 1, into)
    Next
    Return
End If

Dim leaf = TryCast(entity, MimePart)
If leaf IsNot Nothing AndAlso leaf.FileName IsNot Nothing Then
    into.Append(New String(" "c, depth * 2 + 2))
    into.AppendLine("file: " & leaf.FileName)
End If

C#

// TextBody, HtmlBody and Attachments cover most needs. Walk the tree
// yourself when they do not - finding every image regardless of
// disposition, say, or reporting the structure for diagnosis.
into.Append(new string(' ', depth * 2));
into.AppendLine(entity.ContentType.MediaType + "/" + entity.ContentType.MediaSubtype);

if (entity is Multipart branch)
{
    // A Multipart holds children and no content of its own.
    foreach (var child in branch.Children)
        WalkParts(child, depth + 1, into);

    return;
}

if (entity is MimePart leaf && leaf.FileName != null)
{
    into.Append(new string(' ', depth * 2 + 2));
    into.AppendLine("file: " + leaf.FileName);
}

VB.NET

' ToByteArray writes RFC 5322 text - exactly what a .eml file is, and
' what every other mail program can open.
File.WriteAllBytes(path, message.ToByteArray())

' Parse reads it back. A message that has been round-tripped keeps
' its shape: bodies are not re-encoded and headers are not
' reordered, so signatures survive and the recipient sees what was
' signed.
Dim reloaded = MailMessage.Parse(File.ReadAllBytes(path))

C#

// ToByteArray writes RFC 5322 text - exactly what a .eml file is, and
// what every other mail program can open.
File.WriteAllBytes(path, message.ToByteArray());

// Parse reads it back. A message that has been round-tripped keeps
// its shape: bodies are not re-encoded and headers are not
// reordered, so signatures survive and the recipient sees what was
// signed.
var reloaded = MailMessage.Parse(File.ReadAllBytes(path));

PowerShell

# Save as .eml - readable by Outlook, Thunderbird and anything else.
[System.IO.File]::WriteAllBytes('C:\mail\archive\message.eml', $message.ToByteArray())

# And back again.
$reloaded = [Bastion.Mail.MailMessage]::Parse(
    [System.IO.File]::ReadAllBytes('C:\mail\archive\message.eml'))

VB.NET

Directory.CreateDirectory(folder)

For Each attachment In message.Attachments
    ' A file name from a message is untrusted input. It may be
    ' absent, and it may contain path separators or "..", which
    ' would write outside the folder you intended. Take the leaf
    ' name and nothing else.
    Dim suggested = attachment.FileName
    If String.IsNullOrEmpty(suggested) Then suggested = "attachment.dat"

    Dim safeName = Path.GetFileName(suggested)
    If String.IsNullOrEmpty(safeName) Then safeName = "attachment.dat"

    ' GetContent decodes the transfer encoding and hands back the
    ' original octets. For a large attachment prefer OpenRead, which
    ' streams instead of materialising the whole thing.
    File.WriteAllBytes(Path.Combine(folder, safeName), attachment.GetContent())
Next

C#

Directory.CreateDirectory(folder);

foreach (var attachment in message.Attachments)
{
    // A file name from a message is untrusted input. It may be
    // absent, and it may contain path separators or "..", which
    // would write outside the folder you intended. Take the leaf
    // name and nothing else.
    var suggested = attachment.FileName;
    if (string.IsNullOrEmpty(suggested)) suggested = "attachment.dat";

    var safeName = Path.GetFileName(suggested);
    if (string.IsNullOrEmpty(safeName)) safeName = "attachment.dat";

    // GetContent decodes the transfer encoding and hands back the
    // original octets. For a large attachment prefer OpenRead, which
    // streams instead of materialising the whole thing.
    File.WriteAllBytes(Path.Combine(folder, safeName), attachment.GetContent());
}

Visual Basic — streaming

' OpenRead gives a decoding stream. Copying from it never holds the
' whole attachment in memory, which matters once they reach tens of
' megabytes.
Using source = attachment.OpenRead()
    Using destination = File.Create(path)
        source.CopyTo(destination)
    End Using
End Using

C# — streaming

// OpenRead gives a decoding stream. Copying from it never holds the
// whole attachment in memory, which matters once they reach tens of
// megabytes.
using (var source = attachment.OpenRead())
using (var destination = File.Create(path))
{
    source.CopyTo(destination);
}

PowerShell

$folder = 'C:\mail\attachments'
New-Item -ItemType Directory -Path $folder -Force | Out-Null

foreach ($attachment in $message.Attachments) {
    # Never trust the name in the message - reduce it to a leaf.
    $suggested = if ($attachment.FileName) { $attachment.FileName } else { 'attachment.dat' }
    $safeName = [System.IO.Path]::GetFileName($suggested)
    if (-not $safeName) { $safeName = 'attachment.dat' }

    $target = Join-Path $folder $safeName
    [System.IO.File]::WriteAllBytes($target, $attachment.GetContent())

    Write-Host "Saved $safeName"
}

VB.NET

' Port 995 is implicit TLS: the connection is encrypted before a
' single byte of POP3 travels. This is the one to prefer.
Using client As New Pop3Client()
    Await client.ConnectAsync("pop.example.net", 995,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None)

    Await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None)

    ' IsSecure confirms it. Worth asserting in code that must never
    ' run unprotected.
    If Not client.IsSecure Then Throw New InvalidOperationException("Not secured.")

    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// Port 995 is implicit TLS: the connection is encrypted before a
// single byte of POP3 travels. This is the one to prefer.
using (var client = new Pop3Client())
{
    await client.ConnectAsync("pop.example.net", 995,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None);

    await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None);

    // IsSecure confirms it. Worth asserting in code that must never
    // run unprotected.
    if (!client.IsSecure) throw new InvalidOperationException("Not secured.");

    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

# Match the build to the PowerShell edition. The two editions run on different
# runtimes and must load different builds; a script that hard-codes one path
# fails confusingly under the other.
$targetFramework = if ($PSVersionTable.PSEdition -eq 'Core') { 'net8.0' } else { 'net48' }
$binaryPath = "C:\BastionMail\lib\$targetFramework"

Add-Type -Path (Join-Path $binaryPath 'Bastion.Mail.Core.dll')
Add-Type -Path (Join-Path $binaryPath 'Bastion.POP3.dll')

$secure = Read-Host -Prompt 'Password' -AsSecureString
$plain = (New-Object System.Net.NetworkCredential('', $secure)).Password

$client = New-Object Bastion.POP3.Pop3Client
try {
    # PowerShell has no await, so each asynchronous call is completed with
    # GetAwaiter().GetResult(). That blocks the pipeline, which is what a
    # script wants.
    $token = [System.Threading.CancellationToken]::None
    $security = [Bastion.Mail.MailTransportSecurity]::ImplicitTls

    $client.ConnectAsync('pop.example.net', 995, $security, $token).GetAwaiter().GetResult()
    $client.AuthenticateAsync('chris@example.net', $plain, $token).GetAwaiter().GetResult()

    Write-Host "Secured: $($client.IsSecure)"

    $client.DisconnectAsync($token).GetAwaiter().GetResult()
}
finally {
    $client.Dispose()
    $plain = $null
}

VB.NET

' Port 110 begins in cleartext and is upgraded in band by STLS
' before any credential is sent. Use it when the server offers
' nothing better - the session starts unprotected, and that request
' to upgrade can in principle be stripped by an attacker in the path.
'
' If the upgrade does not succeed, this client refuses to
' authenticate rather than continuing in the clear.
Using client As New Pop3Client()
    Await client.ConnectAsync("pop.example.net", 110,
                              MailTransportSecurity.StartTls,
                              CancellationToken.None)

    Await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None)

    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// Port 110 begins in cleartext and is upgraded in band by STLS
// before any credential is sent. Use it when the server offers
// nothing better - the session starts unprotected, and that request
// to upgrade can in principle be stripped by an attacker in the path.
//
// If the upgrade does not succeed, this client refuses to
// authenticate rather than continuing in the clear.
using (var client = new Pop3Client())
{
    await client.ConnectAsync("pop.example.net", 110,
                              MailTransportSecurity.StartTls,
                              CancellationToken.None);

    await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None);

    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

$security = [Bastion.Mail.MailTransportSecurity]::StartTls
$client.ConnectAsync('pop.example.net', 110, $security, $token).GetAwaiter().GetResult()
$client.AuthenticateAsync('chris@example.net', $plain, $token).GetAwaiter().GetResult()

VB.NET

' TWO switches are needed, not one, and that is deliberate. A single
' flag can be set by accident or copied from a sample unread; two
' cannot. Sending a password over an unencrypted socket has to be
' something you meant.
'
' This belongs against a loopback test server, where there is no
' network to eavesdrop on. A code review that finds it pointed at a
' real mail server should treat it as a defect.
Using client As New Pop3Client()
    client.AllowInsecureCleartext = True

    Await client.ConnectAsync(host, port,
                              MailTransportSecurity.None,
                              CancellationToken.None)

    Await client.AuthenticateAsync("demo", "demo", CancellationToken.None)
    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// TWO switches are needed, not one, and that is deliberate. A single
// flag can be set by accident or copied from a sample unread; two
// cannot. Sending a password over an unencrypted socket has to be
// something you meant.
//
// This belongs against a loopback test server, where there is no
// network to eavesdrop on. A code review that finds it pointed at a
// real mail server should treat it as a defect.
using (var client = new Pop3Client())
{
    client.AllowInsecureCleartext = true;

    await client.ConnectAsync(host, port,
                              MailTransportSecurity.None,
                              CancellationToken.None);

    await client.AuthenticateAsync("demo", "demo", CancellationToken.None);
    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

$client.AllowInsecureCleartext = $true
$security = [Bastion.Mail.MailTransportSecurity]::None
$client.ConnectAsync('127.0.0.1', 11000, $security, $token).GetAwaiter().GetResult()

VB.NET

' Google and Microsoft 365 have both disabled password
' authentication for mail. When that is what you are talking to,
' SmtpAuthenticationException.IsServerPolicyFailure comes back True
' and no password will ever work - the account needs OAuth.
'
' Acquiring the token is the provider's SDK's job, not this
' library's. Pass the bare access token here, with no "Bearer"
' prefix; the mechanism adds what the wire format needs.
Using client As New Pop3Client()
    Await client.ConnectAsync("pop.gmail.com", 995,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None)

    ' XOAUTH2 is Google's scheme and the one the large providers
    ' accept. SaslOAuthBearer is the RFC 7628 standard - use it when
    ' the server advertises OAUTHBEARER, and fall back to this.
    Dim mechanism As New SaslXOAuth2("chris@example.net", accessToken)
    Await client.AuthenticateAsync(mechanism, CancellationToken.None)

    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// Google and Microsoft 365 have both disabled password
// authentication for mail. When that is what you are talking to,
// IsServerPolicyFailure comes back true and no password will ever
// work - the account needs OAuth.
//
// Acquiring the token is the provider's SDK's job, not this
// library's. Pass the bare access token here, with no "Bearer"
// prefix; the mechanism adds what the wire format needs.
using (var client = new Pop3Client())
{
    await client.ConnectAsync("pop.gmail.com", 995,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None);

    // XOAUTH2 is Google's scheme and the one the large providers
    // accept. SaslOAuthBearer is the RFC 7628 standard - use it when
    // the server advertises OAUTHBEARER, and fall back to this.
    var mechanism = new SaslXOAuth2("chris@example.net", accessToken);
    await client.AuthenticateAsync(mechanism, CancellationToken.None);

    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

# XOAUTH2 is Google's scheme and the one the large providers accept.
# SaslOAuthBearer is the RFC 7628 standard - use it when the server advertises
# OAUTHBEARER, and fall back to this.
$mechanism = New-Object Bastion.Mail.Sasl.SaslXOAuth2 'chris@example.net', $accessToken
$client.AuthenticateAsync($mechanism, $token).GetAwaiter().GetResult()

VB.NET

' STAT is cheap. Call it before deciding whether there is any point
' doing the expensive part.
Dim status = Await client.GetStatusAsync(CancellationToken.None)

If status.MessageCount = 0 Then Return "Nothing waiting."

' LIST gives per-message sizes, so you can skip or defer anything
' enormous rather than discovering it mid-download.
Dim sizes = Await client.GetMessageListAsync(CancellationToken.None)

Dim largest = 0
For Each entry In sizes
    If entry.Size > largest Then largest = entry.Size
Next

Return String.Format("{0} message(s), {1} octets in total, largest {2}",
                     status.MessageCount, status.TotalSize, largest)

C#

// STAT is cheap. Call it before deciding whether there is any point
// doing the expensive part.
var status = await client.GetStatusAsync(CancellationToken.None);

if (status.MessageCount == 0) return "Nothing waiting.";

// LIST gives per-message sizes, so you can skip or defer anything
// enormous rather than discovering it mid-download.
var sizes = await client.GetMessageListAsync(CancellationToken.None);

var largest = 0;
foreach (var entry in sizes)
    if (entry.Size > largest) largest = entry.Size;

return string.Format("{0} message(s), {1} octets in total, largest {2}",
                     status.MessageCount, status.TotalSize, largest);

PowerShell

$status = $client.GetStatusAsync($token).GetAwaiter().GetResult()
Write-Host "$($status.MessageCount) message(s), about $($status.TotalSize) octets"

$sizes = $client.GetMessageListAsync($token).GetAwaiter().GetResult()
$sizes | Sort-Object Size -Descending | Select-Object -First 5

VB.NET

Dim collected As New List(Of MailMessage)()

' UIDL pairs each message with an identifier that survives between
' sessions. The message NUMBER does not: delete message 3 and
' reconnect, and what was 4 is now 3. Store identifiers only.
For Each entry In Await client.GetUniqueIdsAsync(CancellationToken.None)

    If alreadySeen.Contains(entry.UniqueId) Then Continue For

    ' The identifier is what persists; the CALL takes this session's
    ' number.
    Dim message = Await client.GetMessageAsync(entry.MessageNumber,
                                               CancellationToken.None)
    collected.Add(message)
    alreadySeen.Add(entry.UniqueId)
Next

Return collected

C#

var collected = new List<MailMessage>();

// UIDL pairs each message with an identifier that survives between
// sessions. The message NUMBER does not: delete message 3 and
// reconnect, and what was 4 is now 3. Store identifiers only.
foreach (var entry in await client.GetUniqueIdsAsync(CancellationToken.None))
{
    if (alreadySeen.Contains(entry.UniqueId)) continue;

    // The identifier is what persists; the CALL takes this session's
    // number.
    var message = await client.GetMessageAsync(entry.MessageNumber,
                                               CancellationToken.None);
    collected.Add(message);
    alreadySeen.Add(entry.UniqueId);
}

return collected;

PowerShell

# Identifiers collected on earlier runs, one per line.
$seenFile = 'C:\mail\state\seen.txt'
$seen = New-Object System.Collections.Generic.HashSet[string]
if (Test-Path $seenFile) {
    Get-Content $seenFile | ForEach-Object { [void]$seen.Add($_) }
}

foreach ($entry in $client.GetUniqueIdsAsync($token).GetAwaiter().GetResult()) {
    if ($seen.Contains($entry.UniqueId)) { continue }

    $message = $client.GetMessageAsync($entry.MessageNumber, $token).GetAwaiter().GetResult()

    [pscustomobject]@{
        UniqueId = $entry.UniqueId
        From     = ($message.From | ForEach-Object { $_.Address }) -join '; '
        Subject  = $message.Subject
    }

    [void]$seen.Add($entry.UniqueId)
}

$seen | Set-Content $seenFile

VB.NET

' TOP fetches the headers plus a chosen number of body lines. On a
' mailbox holding a few large messages this is the difference
' between a fast sync and a slow one - you decide what is worth
' downloading before paying for it. Zero body lines means headers
' alone.
'
' It returns the raw octets rather than a parsed message, because
' what comes back is a fragment. Parse gives you the headers.
Dim raw = Await client.GetMessageHeadersAsync(messageNumber, 0,
                                              CancellationToken.None)

Dim headers = MailMessage.Parse(raw)

If headers.Subject IsNot Nothing AndAlso
   headers.Subject.StartsWith("[spam]", StringComparison.OrdinalIgnoreCase) Then
    Return Nothing
End If

Return Await client.GetMessageAsync(messageNumber, CancellationToken.None)

C#

// TOP fetches the headers plus a chosen number of body lines. On a
// mailbox holding a few large messages this is the difference
// between a fast sync and a slow one - you decide what is worth
// downloading before paying for it. Zero body lines means headers
// alone.
//
// It returns the raw octets rather than a parsed message, because
// what comes back is a fragment. Parse gives you the headers.
var raw = await client.GetMessageHeadersAsync(messageNumber, 0,
                                              CancellationToken.None);

var headers = MailMessage.Parse(raw);

if (headers.Subject != null &&
    headers.Subject.StartsWith("[spam]", StringComparison.OrdinalIgnoreCase))
{
    return null;
}

return await client.GetMessageAsync(messageNumber, CancellationToken.None);

VB.NET

Directory.CreateDirectory(folder)
Dim written = 0

For Each entry In Await client.GetUniqueIdsAsync(CancellationToken.None)

    ' GetMessageBytesAsync returns the raw RFC 5322 octets, exactly
    ' as the server holds them. For an archive this is what you
    ' want: no parse, no re-encode, nothing that could alter a
    ' signature. GetMessageAsync would parse it, which costs time
    ' you do not need to spend.
    Dim raw = Await client.GetMessageBytesAsync(entry.MessageNumber,
                                                CancellationToken.None)

    ' The identifier is server-chosen and may contain characters a
    ' file name cannot. Replace anything unusable rather than
    ' trusting it.
    Dim safeName = entry.UniqueId
    For Each bad In Path.GetInvalidFileNameChars()
        safeName = safeName.Replace(bad, "_"c)
    Next

    File.WriteAllBytes(Path.Combine(folder, safeName & ".eml"), raw)
    written += 1
Next

Return written

C#

Directory.CreateDirectory(folder);
var written = 0;

foreach (var entry in await client.GetUniqueIdsAsync(CancellationToken.None))
{
    // GetMessageBytesAsync returns the raw RFC 5322 octets, exactly
    // as the server holds them. For an archive this is what you
    // want: no parse, no re-encode, nothing that could alter a
    // signature. GetMessageAsync would parse it, which costs time
    // you do not need to spend.
    var raw = await client.GetMessageBytesAsync(entry.MessageNumber,
                                                CancellationToken.None);

    // The identifier is server-chosen and may contain characters a
    // file name cannot. Replace anything unusable rather than
    // trusting it.
    var safeName = entry.UniqueId;
    foreach (var bad in Path.GetInvalidFileNameChars())
        safeName = safeName.Replace(bad, '_');

    File.WriteAllBytes(Path.Combine(folder, safeName + ".eml"), raw);
    written++;
}

return written;

PowerShell

$folder = 'C:\mail\archive'
New-Item -ItemType Directory -Path $folder -Force | Out-Null

$invalid = [System.IO.Path]::GetInvalidFileNameChars()

foreach ($entry in $client.GetUniqueIdsAsync($token).GetAwaiter().GetResult()) {
    # Raw octets - no parse, no re-encode, signatures intact.
    $raw = $client.GetMessageBytesAsync($entry.MessageNumber, $token).GetAwaiter().GetResult()

    $safeName = $entry.UniqueId
    foreach ($bad in $invalid) { $safeName = $safeName.Replace($bad, '_') }

    [System.IO.File]::WriteAllBytes((Join-Path $folder "$safeName.eml"), $raw)
}

VB.NET

For Each number In numbers
    ' DELE only MARKS. Nothing has been removed yet.
    Await client.DeleteMessageAsync(number, CancellationToken.None)
Next

If Not commit Then
    ' RSET unmarks everything marked this session. Useful when a
    ' later step fails and you would rather leave the mailbox as you
    ' found it.
    Await client.ResetAsync(CancellationToken.None)
End If

' QUIT is what commits the marks. Drop the connection instead and the
' server discards them all - you may download something twice, but
' you will never lose it. Handle DeletionsCommitted to know when a
' deletion has genuinely become permanent.
Await client.DisconnectAsync(CancellationToken.None)

C#

foreach (var number in numbers)
{
    // DELE only MARKS. Nothing has been removed yet.
    await client.DeleteMessageAsync(number, CancellationToken.None);
}

if (!commit)
{
    // RSET unmarks everything marked this session. Useful when a
    // later step fails and you would rather leave the mailbox as you
    // found it.
    await client.ResetAsync(CancellationToken.None);
}

// QUIT is what commits the marks. Drop the connection instead and the
// server discards them all - you may download something twice, but
// you will never lose it. Handle DeletionsCommitted to know when a
// deletion has genuinely become permanent.
await client.DisconnectAsync(CancellationToken.None);

PowerShell

foreach ($number in $toDelete) {
    # Marks only.
    $client.DeleteMessageAsync($number, $token).GetAwaiter().GetResult()
}

if (-not $commit) {
    # Unmark everything marked this session.
    $client.ResetAsync($token).GetAwaiter().GetResult()
}

# QUIT - this is what commits the marks.
$client.DisconnectAsync($token).GetAwaiter().GetResult()

VB.NET

' Progress fires as octets arrive. PercentComplete is nullable
' because the total is not always known in advance - POP3 sizes are
' the server's estimate, so clamp rather than trusting them for a
' progress bar.
AddHandler client.Progress,
    Sub(s, e)
        If e.PercentComplete.HasValue Then
            Console.WriteLine("{0}% ({1} of {2} bytes)",
                              Math.Min(100, e.PercentComplete.Value),
                              e.BytesTransferred, e.TotalBytes)
        Else
            Console.WriteLine("{0} bytes", e.BytesTransferred)
        End If
    End Sub

VB.NET

' Port 993 is implicit TLS: encrypted before any IMAP travels.
' Port 143 with StartTls is the in-band alternative.
Using client As New ImapClient()

    ' Servers send unsolicited notices - a mailbox closing for
    ' maintenance, a quota warning. They are written for the user to
    ' read, so show them rather than swallowing them.
    AddHandler client.AlertReceived,
        Sub(s, e) Console.WriteLine("SERVER ALERT: " & e.Message)

    Await client.ConnectAsync("imap.example.net", 993,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None)

    Await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None)

    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// Port 993 is implicit TLS: encrypted before any IMAP travels.
// Port 143 with StartTls is the in-band alternative.
using (var client = new ImapClient())
{
    // Servers send unsolicited notices - a mailbox closing for
    // maintenance, a quota warning. They are written for the user to
    // read, so show them rather than swallowing them.
    client.AlertReceived += (s, e) =>
        Console.WriteLine("SERVER ALERT: " + e.Message);

    await client.ConnectAsync("imap.example.net", 993,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None);

    await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None);

    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

$targetFramework = if ($PSVersionTable.PSEdition -eq 'Core') { 'net8.0' } else { 'net48' }
$binaryPath = "C:\BastionMail\lib\$targetFramework"

Add-Type -Path (Join-Path $binaryPath 'Bastion.Mail.Core.dll')
Add-Type -Path (Join-Path $binaryPath 'Bastion.IMAP.dll')

$secure = Read-Host -Prompt 'Password' -AsSecureString
$plain = (New-Object System.Net.NetworkCredential('', $secure)).Password

$client = New-Object Bastion.IMAP.ImapClient
try {
    $token = [System.Threading.CancellationToken]::None
    $security = [Bastion.Mail.MailTransportSecurity]::ImplicitTls

    $client.ConnectAsync('imap.example.net', 993, $security, $token).GetAwaiter().GetResult()
    $client.AuthenticateAsync('chris@example.net', $plain, $token).GetAwaiter().GetResult()
}
finally {
    $plain = $null
}

VB.NET

' Required by Gmail and Microsoft 365, which no longer accept
' passwords for mail access. Acquiring the token is the provider's
' SDK's job; pass the bare access token with no "Bearer" prefix.
Using client As New ImapClient()
    Await client.ConnectAsync("imap.gmail.com", 993,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None)

    Dim mechanism As New SaslXOAuth2("chris@example.net", accessToken)
    Await client.AuthenticateAsync(mechanism, CancellationToken.None)

    Await client.DisconnectAsync(CancellationToken.None)
End Using

PowerShell

$mechanism = New-Object Bastion.Mail.Sasl.SaslXOAuth2 'chris@example.net', $accessToken
$client.AuthenticateAsync($mechanism, $token).GetAwaiter().GetResult()

VB.NET

' An empty reference and "*" mean "everything from the root down".
' Narrow the pattern on a large account rather than listing
' thousands of folders you will not use.
For Each folder In Await client.GetFoldersAsync("", "*", CancellationToken.None)
    Console.WriteLine("{0}  (delimiter {1})", folder.Name, folder.Delimiter)
Next

' The hierarchy delimiter is the SERVER's choice - a dot on some, a
' slash on others. Never hard-code one: read it from a folder and
' build paths with it.
Await client.CreateFolderAsync("Archive/2026", CancellationToken.None)

Await client.DeleteFolderAsync("Archive/2025", CancellationToken.None)

C#

// An empty reference and "*" mean "everything from the root down".
// Narrow the pattern on a large account rather than listing
// thousands of folders you will not use.
foreach (var folder in await client.GetFoldersAsync("", "*", CancellationToken.None))
    Console.WriteLine("{0}  (delimiter {1})", folder.Name, folder.Delimiter);

// The hierarchy delimiter is the SERVER's choice - a dot on some, a
// slash on others. Never hard-code one: read it from a folder and
// build paths with it.
await client.CreateFolderAsync("Archive/2026", CancellationToken.None);

await client.DeleteFolderAsync("Archive/2025", CancellationToken.None);

PowerShell

# Empty reference and "*" mean everything from the root down. Narrow the
# pattern on a large account rather than listing thousands of folders.
$folders = $client.GetFoldersAsync('', '*', $token).GetAwaiter().GetResult()

$folders | ForEach-Object {
    [pscustomobject]@{
        Name       = $_.Name
        Delimiter  = $_.Delimiter
        Selectable = $_.IsSelectable
        SpecialUse = $_.SpecialUse
    }
}

$client.CreateFolderAsync('Archive/2026', $token).GetAwaiter().GetResult()

VB.NET

' False means read-write. Pass True for read-only when reading must
' not set the Seen flag as a side effect - an indexer, or a preview.
Dim status = Await client.SelectFolderAsync(folder, False, CancellationToken.None)

' THE CHECK. Do this every time, before trusting a single cached
' identifier.
'
' UidValidity stamps the whole numbering scheme for the folder. If
' the server ever renumbers - a restore from backup, a migration -
' it changes, and every identifier you stored now points somewhere
' else. Ignoring this does not fail loudly: it eventually shows one
' message's body under another's headers, weeks later.
If status.UidValidity <> storedUidValidity Then Return True

Return False

C#

// false means read-write. Pass true for read-only when reading must
// not set the Seen flag as a side effect - an indexer, or a preview.
var status = await client.SelectFolderAsync(folder, false, CancellationToken.None);

// THE CHECK. Do this every time, before trusting a single cached
// identifier.
//
// UidValidity stamps the whole numbering scheme for the folder. If
// the server ever renumbers - a restore from backup, a migration -
// it changes, and every identifier you stored now points somewhere
// else. Ignoring this does not fail loudly: it eventually shows one
// message's body under another's headers, weeks later.
return status.UidValidity != storedUidValidity;

PowerShell

# $false = read-write. $true opens read-only, leaving the Seen flag alone.
$status = $client.SelectFolderAsync('INBOX', $false, $token).GetAwaiter().GetResult()

if ($status.UidValidity -ne $storedUidValidity) {
    Write-Warning 'UidValidity changed - the cache for this folder is void.'
    Remove-Item $cachePath -Recurse -Force -ErrorAction SilentlyContinue
    $storedUidValidity = $status.UidValidity
}

VB.NET

' Search runs on the SERVER and returns identifiers only. Filtering
' here rather than downloading and filtering locally is the single
' biggest difference between a fast IMAP client and a slow one.
'
' The criteria are IMAP's own: UNSEEN, ALL, FLAGGED,
' "SINCE 1-Jan-2026", "FROM alice@example.org", and combinations.
Dim uids = Await client.SearchAsync("UNSEEN", CancellationToken.None)

Dim lines As New List(Of String)()
If uids.Count = 0 Then Return lines

' Summaries fetch headers and structure - enough to build a message
' list, with no bodies and no attachments. Fetching whole messages
' just to read their subjects is the classic way to make a mailbox
' feel slow.
For Each summary In Await client.FetchSummariesAsync(uids, CancellationToken.None)
    lines.Add(String.Format("{0}  {1}", summary.Uid, summary.Envelope.Subject))
Next

Return lines

C#

// Search runs on the SERVER and returns identifiers only. Filtering
// here rather than downloading and filtering locally is the single
// biggest difference between a fast IMAP client and a slow one.
//
// The criteria are IMAP's own: UNSEEN, ALL, FLAGGED,
// "SINCE 1-Jan-2026", "FROM alice@example.org", and combinations.
var uids = await client.SearchAsync("UNSEEN", CancellationToken.None);

var lines = new List<string>();
if (uids.Count == 0) return lines;

// Summaries fetch headers and structure - enough to build a message
// list, with no bodies and no attachments. Fetching whole messages
// just to read their subjects is the classic way to make a mailbox
// feel slow.
foreach (var summary in await client.FetchSummariesAsync(uids, CancellationToken.None))
    lines.Add(string.Format("{0}  {1}", summary.Uid, summary.Envelope.Subject));

return lines;

PowerShell

$uids = $client.SearchAsync('UNSEEN', $token).GetAwaiter().GetResult()
Write-Host "$($uids.Count) unseen message(s)"

if ($uids.Count -gt 0) {
    $summaries = $client.FetchSummariesAsync($uids, $token).GetAwaiter().GetResult()

    $summaries | ForEach-Object {
        [pscustomobject]@{
            Uid     = $_.Uid
            Subject = $_.Envelope.Subject
            From    = ($_.Envelope.From | ForEach-Object { $_.Address }) -join '; '
            Size    = $_.Size
            Flags   = $_.Flags
        }
    }
}

VB.NET

Directory.CreateDirectory(folder)
Dim written = 0

For Each uid In uids
    ' Fetch the whole message only for the ones actually being
    ' archived - not for every message in the folder.
    Dim message = Await client.FetchMessageAsync(uid)

    ' ToByteArray writes RFC 5322 text: a .eml file any other mail
    ' program can open.
    File.WriteAllBytes(Path.Combine(folder, uid.ToString() & ".eml"),
                       message.ToByteArray())
    written += 1
Next

Return written

C#

Directory.CreateDirectory(folder);
var written = 0;

foreach (var uid in uids)
{
    // Fetch the whole message only for the ones actually being
    // archived - not for every message in the folder.
    var message = await client.FetchMessageAsync(uid);

    // ToByteArray writes RFC 5322 text: a .eml file any other mail
    // program can open.
    File.WriteAllBytes(Path.Combine(folder, uid + ".eml"), message.ToByteArray());
    written++;
}

return written;

PowerShell

$folder = 'C:\mail\archive'
New-Item -ItemType Directory -Path $folder -Force | Out-Null

foreach ($uid in $uids) {
    $message = $client.FetchMessageAsync($uid).GetAwaiter().GetResult()
    [System.IO.File]::WriteAllBytes((Join-Path $folder "$uid.eml"), $message.ToByteArray())
}

VB.NET

' Flags live on the server, so a change here is what the customer's
' phone will see too. That is the point of IMAP, and it is also why
' setting Seen carelessly is rude: it marks mail read that nobody
' has read.
Await client.StoreFlagsAsync(uids, ImapMessageFlags.Seen, Nothing, True,
                             CancellationToken.None)

' Removing works the same way, with add set to False.
Await client.StoreFlagsAsync(uids, ImapMessageFlags.Seen, Nothing, False,
                             CancellationToken.None)

' \Flagged is the star or exclamation mark in most clients.
Await client.StoreFlagsAsync(uids, ImapMessageFlags.Flagged, Nothing, True,
                             CancellationToken.None)

C#

// Flags live on the server, so a change here is what the customer's
// phone will see too. That is the point of IMAP, and it is also why
// setting Seen carelessly is rude: it marks mail read that nobody
// has read.
await client.StoreFlagsAsync(uids, ImapMessageFlags.Seen, null, true,
                             CancellationToken.None);

// Removing works the same way, with add set to false.
await client.StoreFlagsAsync(uids, ImapMessageFlags.Seen, null, false,
                             CancellationToken.None);

// Flagged is the star or exclamation mark in most clients.
await client.StoreFlagsAsync(uids, ImapMessageFlags.Flagged, null, true,
                             CancellationToken.None);

PowerShell

$seen = [Bastion.IMAP.ImapMessageFlags]::Seen
$flagged = [Bastion.IMAP.ImapMessageFlags]::Flagged

# Add.
$client.StoreFlagsAsync($uids, $seen, $null, $true, $token).GetAwaiter().GetResult()

# Remove.
$client.StoreFlagsAsync($uids, $seen, $null, $false, $token).GetAwaiter().GetResult()

# The star or exclamation mark in most clients.
$client.StoreFlagsAsync($uids, $flagged, $null, $true, $token).GetAwaiter().GetResult()

VB.NET

' Copy leaves the original in place.
Await client.CopyMessagesAsync(uids, "Archive/2026", CancellationToken.None)

' Move does not. Where the server supports MOVE it is one atomic
' operation, which matters: a copy-then-delete that fails halfway
' leaves the message in both folders or neither.
Await client.MoveMessagesAsync(uids, "Archive/2026", CancellationToken.None)

' Deleting is two steps in IMAP, as in POP3. This marks \Deleted.
Await client.DeleteMessagesAsync(uids, CancellationToken.None)

' And this is what actually removes them. Until Expunge, a marked
' message is still there and can still be fetched - which is a
' feature, not an inconvenience.
Await client.ExpungeAsync(uids, CancellationToken.None)

C#

// Copy leaves the original in place.
await client.CopyMessagesAsync(uids, "Archive/2026", CancellationToken.None);

// Move does not. Where the server supports MOVE it is one atomic
// operation, which matters: a copy-then-delete that fails halfway
// leaves the message in both folders or neither.
await client.MoveMessagesAsync(uids, "Archive/2026", CancellationToken.None);

// Deleting is two steps in IMAP, as in POP3. This marks Deleted.
await client.DeleteMessagesAsync(uids, CancellationToken.None);

// And this is what actually removes them. Until Expunge, a marked
// message is still there and can still be fetched - which is a
// feature, not an inconvenience.
await client.ExpungeAsync(uids, CancellationToken.None);

PowerShell

# Atomic where the server supports MOVE.
$client.MoveMessagesAsync($uids, 'Archive/2026', $token).GetAwaiter().GetResult()

# Two steps: mark, then remove.
$client.DeleteMessagesAsync($uids, $token).GetAwaiter().GetResult()
$client.ExpungeAsync($uids, $token).GetAwaiter().GetResult()

VB.NET

' SMTP submits a message; it does not file a copy. If the customer
' expects to see what they sent - and they do - the sending program
' has to put it in the Sent folder itself.
'
' Mark it \Seen: the user wrote it, so presenting it as unread mail
' is wrong.
Await client.AppendAsync("Sent", message, ImapMessageFlags.Seen,
                         CancellationToken.None)

C#

// SMTP submits a message; it does not file a copy. If the customer
// expects to see what they sent - and they do - the sending program
// has to put it in the Sent folder itself.
//
// Mark it Seen: the user wrote it, so presenting it as unread mail
// is wrong.
await client.AppendAsync("Sent", message, ImapMessageFlags.Seen,
                         CancellationToken.None);

PowerShell

$seen = [Bastion.IMAP.ImapMessageFlags]::Seen
$client.AppendAsync('Sent', $message, $seen, $token).GetAwaiter().GetResult()

VB.NET

' IDLE means the server tells you when something happens, instead of
' you asking every thirty seconds. It is dramatically cheaper for
' both ends, and new mail appears at once rather than at the next
' poll.
AddHandler client.MessageCountChanged,
    Sub(s, e) Console.WriteLine("{0} new message(s); now {1}", e.Delta, e.NewCount)

AddHandler client.MessagesExpunged,
    Sub(s, e) Console.WriteLine("A message was removed by another client.")

' The timeout is not optional, and the value matters. RFC 2177 says
' a client MUST re-issue IDLE at least every 29 minutes, because
' servers are entitled to drop an idle connection after 30. Pass a
' little under that and call it again in a loop; treat the return as
' "time to renew", not as an error.
Await client.IdleAsync(TimeSpan.FromMinutes(28), cancellationToken)

C#

// IDLE means the server tells you when something happens, instead of
// you asking every thirty seconds. It is dramatically cheaper for
// both ends, and new mail appears at once rather than at the next
// poll.
client.MessageCountChanged += (s, e) =>
    Console.WriteLine("{0} new message(s); now {1}", e.Delta, e.NewCount);

client.MessagesExpunged += (s, e) =>
    Console.WriteLine("A message was removed by another client.");

// The timeout is not optional, and the value matters. RFC 2177 says
// a client MUST re-issue IDLE at least every 29 minutes, because
// servers are entitled to drop an idle connection after 30. Pass a
// little under that and call it again in a loop; treat the return as
// "time to renew", not as an error.
await client.IdleAsync(TimeSpan.FromMinutes(28), cancellationToken);

VB.NET

' Port 465 with implicit TLS is the preferred submission port. It is
' sometimes still called legacy; it is not. RFC 8314 section 7.3
' re-registered it with IANA as "submissions", and section 3.3 says
' implicit TLS is preferred over STARTTLS for submission.
Using client As New SmtpClient()
    Await client.ConnectAsync("smtp.example.net", 465,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None)

    Await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None)

    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// Port 465 with implicit TLS is the preferred submission port. It is
// sometimes still called legacy; it is not. RFC 8314 section 7.3
// re-registered it with IANA as "submissions", and section 3.3 says
// implicit TLS is preferred over STARTTLS for submission.
using (var client = new SmtpClient())
{
    await client.ConnectAsync("smtp.example.net", 465,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None);

    await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None);

    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

$targetFramework = if ($PSVersionTable.PSEdition -eq 'Core') { 'net8.0' } else { 'net48' }
$binaryPath = "C:\BastionMail\lib\$targetFramework"

Add-Type -Path (Join-Path $binaryPath 'Bastion.Mail.Core.dll')
Add-Type -Path (Join-Path $binaryPath 'Bastion.SMTP.dll')

$secure = Read-Host -Prompt 'Password' -AsSecureString
$plain = (New-Object System.Net.NetworkCredential('', $secure)).Password

$client = New-Object Bastion.SMTP.SmtpClient
try {
    $token = [System.Threading.CancellationToken]::None
    $security = [Bastion.Mail.MailTransportSecurity]::ImplicitTls

    $client.ConnectAsync('smtp.example.net', 465, $security, $token).GetAwaiter().GetResult()
    $client.AuthenticateAsync('chris@example.net', $plain, $token).GetAwaiter().GetResult()
}
finally {
    $plain = $null
}

VB.NET

' Port 587 begins in cleartext and upgrades in band. Use it where 465
' is not offered. Port 25 is for server-to-server relay, not
' submission, and most networks block it outright.
Using client As New SmtpClient()

    ' The name given in EHLO. Some servers check that it resolves, and
    ' a few reject a greeting they consider unhelpful. The default
    ' leaks nothing about the local machine; set it when a server
    ' insists on something specific.
    client.ClientIdentity = "mail.example.net"

    Await client.ConnectAsync("smtp.example.net", 587,
                              MailTransportSecurity.StartTls,
                              CancellationToken.None)

    Await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None)

    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// Port 587 begins in cleartext and upgrades in band. Use it where 465
// is not offered. Port 25 is for server-to-server relay, not
// submission, and most networks block it outright.
using (var client = new SmtpClient())
{
    // The name given in EHLO. Some servers check that it resolves, and
    // a few reject a greeting they consider unhelpful. The default
    // leaks nothing about the local machine; set it when a server
    // insists on something specific.
    client.ClientIdentity = "mail.example.net";

    await client.ConnectAsync("smtp.example.net", 587,
                              MailTransportSecurity.StartTls,
                              CancellationToken.None);

    await client.AuthenticateAsync("chris@example.net", password,
                                   CancellationToken.None);

    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

$client.ClientIdentity = 'mail.example.net'

$security = [Bastion.Mail.MailTransportSecurity]::StartTls
$client.ConnectAsync('smtp.example.net', 587, $security, $token).GetAwaiter().GetResult()
$client.AuthenticateAsync('chris@example.net', $plain, $token).GetAwaiter().GetResult()

VB.NET

' If SmtpAuthenticationException.IsServerPolicyFailure comes back
' True, the password was not the problem - the server has disabled
' password authentication altogether. Google and Microsoft 365 both
' have. No password will ever work on such an account.
'
' Acquiring the token is the provider's SDK's job. Pass the bare
' access token, with no "Bearer" prefix.
Using client As New SmtpClient()
    Await client.ConnectAsync("smtp.gmail.com", 465,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None)

    Dim mechanism As New SaslXOAuth2("chris@example.net", accessToken)
    Await client.AuthenticateAsync(mechanism, CancellationToken.None)

    Await client.DisconnectAsync(CancellationToken.None)
End Using

C#

// If IsServerPolicyFailure comes back true, the password was not the
// problem - the server has disabled password authentication
// altogether. Google and Microsoft 365 both have. No password will
// ever work on such an account.
//
// Acquiring the token is the provider's SDK's job. Pass the bare
// access token, with no "Bearer" prefix.
using (var client = new SmtpClient())
{
    await client.ConnectAsync("smtp.gmail.com", 465,
                              MailTransportSecurity.ImplicitTls,
                              CancellationToken.None);

    var mechanism = new SaslXOAuth2("chris@example.net", accessToken);
    await client.AuthenticateAsync(mechanism, CancellationToken.None);

    await client.DisconnectAsync(CancellationToken.None);
}

PowerShell

$mechanism = New-Object Bastion.Mail.Sasl.SaslXOAuth2 'chris@example.net', $accessToken
$client.AuthenticateAsync($mechanism, $token).GetAwaiter().GetResult()

VB.NET

' Rejections as they happen. This is the only place an individual
' address is ever named - the final reply covers the whole
' transaction and names nobody.
AddHandler client.RecipientRejected,
    Sub(s, e)
        ' Transient is a 4xx: mailbox full, greylisting, rate limit.
        ' Retry later, the address is fine. Permanent is a 5xx: no
        ' such user, or a policy refusal. Retrying is pointless, and
        ' repeated attempts at a dead address harm your sending
        ' reputation - take it off the list.
        Console.WriteLine("{0} rejected ({1}): {2}",
                          e.Status.Address,
                          If(e.Status.IsTransient, "temporary", "PERMANENT"),
                          e.Status.ResponseText)
    End Sub

Dim result = Await client.SendAsync(message, CancellationToken.None)

' A send to five people where two are rejected still ends in a
' success reply. Compare the counts, or a partial delivery reads as
' a complete one.
If Not result.AllRecipientsAccepted Then
    Return String.Format("PARTIAL: {0} of {1} accepted.",
                         result.AcceptedRecipients.Count,
                         result.Recipients.Count)
End If

' Worth recording: it is what a server operator needs to trace this
' message in their logs when a customer asks where it went.
Return "Sent. Queue identifier: " & If(result.QueueIdentifier, "(none given)")

C#

// Rejections as they happen. This is the only place an individual
// address is ever named - the final reply covers the whole
// transaction and names nobody.
client.RecipientRejected += (s, e) =>
{
    // Transient is a 4xx: mailbox full, greylisting, rate limit.
    // Retry later, the address is fine. Permanent is a 5xx: no such
    // user, or a policy refusal. Retrying is pointless, and repeated
    // attempts at a dead address harm your sending reputation - take
    // it off the list.
    Console.WriteLine("{0} rejected ({1}): {2}",
                      e.Status.Address,
                      e.Status.IsTransient ? "temporary" : "PERMANENT",
                      e.Status.ResponseText);
};

var result = await client.SendAsync(message, CancellationToken.None);

// A send to five people where two are rejected still ends in a
// success reply. Compare the counts, or a partial delivery reads as
// a complete one.
if (!result.AllRecipientsAccepted)
{
    return string.Format("PARTIAL: {0} of {1} accepted.",
                         result.AcceptedRecipients.Count,
                         result.Recipients.Count);
}

// Worth recording: it is what a server operator needs to trace this
// message in their logs when a customer asks where it went.
return "Sent. Queue identifier: " + (result.QueueIdentifier ?? "(none given)");

PowerShell

# Register for rejections before sending. Without this the only signal is the
# count comparison after the fact.
Register-ObjectEvent -InputObject $client -EventName RecipientRejected -Action {
    $status = $EventArgs.Status
    $kind = if ($status.IsTransient) { 'temporary' } else { 'PERMANENT' }
    Write-Warning "$($status.Address) rejected ($kind): $($status.ResponseText)"
} | Out-Null

$result = $client.SendAsync($message, $token).GetAwaiter().GetResult()

# The final reply says nothing about individual addresses.
if (-not $result.AllRecipientsAccepted) {
    Write-Warning "PARTIAL: $($result.AcceptedRecipients.Count) of $($result.Recipients.Count) accepted."
}

if ($result.QueueIdentifier) {
    # What a server operator needs to trace the message in their logs.
    Write-Host "Queue identifier: $($result.QueueIdentifier)"
}

VB.NET

Try
    Await client.SendAsync(message, CancellationToken.None)
    Return False

Catch ex As SmtpSendException When ex.IsInDoubt
    ' The message was fully transmitted but no verdict arrived - the
    ' connection died between the last byte and the server's reply.
    ' It may already be queued for delivery. Retrying now sends
    ' every recipient a second copy.
    '
    ' This is a case for human judgement, or for a receiver that can
    ' deduplicate on Message-ID. It is never a case for an automatic
    ' retry.
    Console.Error.WriteLine("OUTCOME UNKNOWN - do not resend automatically.")
    Return False

Catch ex As SmtpSendException
    ' A definite failure. Nothing was accepted, so a retry is safe.
    For Each recipient In ex.Recipients
        If Not recipient.Accepted Then
            Console.Error.WriteLine("  {0}: {1} {2}",
                                    recipient.Address,
                                    recipient.ReplyCode,
                                    recipient.ResponseText)
        End If
    Next
    Return True
End Try

C#

try
{
    await client.SendAsync(message, CancellationToken.None);
    return false;
}
catch (SmtpSendException ex) when (ex.IsInDoubt)
{
    // The message was fully transmitted but no verdict arrived - the
    // connection died between the last byte and the server's reply.
    // It may already be queued for delivery. Retrying now sends
    // every recipient a second copy.
    //
    // This is a case for human judgement, or for a receiver that can
    // deduplicate on Message-ID. It is never a case for an automatic
    // retry.
    Console.Error.WriteLine("OUTCOME UNKNOWN - do not resend automatically.");
    return false;
}
catch (SmtpSendException ex)
{
    // A definite failure. Nothing was accepted, so a retry is safe.
    foreach (var recipient in ex.Recipients)
    {
        if (!recipient.Accepted)
        {
            Console.Error.WriteLine("  {0}: {1} {2}",
                                    recipient.Address,
                                    recipient.ReplyCode,
                                    recipient.ResponseText);
        }
    }
    return true;
}

PowerShell

try {
    $client.SendAsync($message, $token).GetAwaiter().GetResult()
}
catch [Bastion.SMTP.SmtpSendException] {
    if ($_.Exception.IsInDoubt) {
        # Fully transmitted, no verdict. Do NOT resend automatically.
        Write-Error 'OUTCOME UNKNOWN - the server may already have accepted it.'
    }
    else {
        # A definite failure. Nothing was accepted, so a retry is safe.
        foreach ($r in $_.Exception.Recipients | Where-Object { -not $_.Accepted }) {
            Write-Error "  $($r.Address): $($r.ReplyCode) $($r.ResponseText)"
        }
    }
}

VB.NET

' A message saved by the core library - or by any other mail program,
' since a .eml file is just RFC 5322 text - can be submitted
' unchanged. This is how a queued-mail folder or a retry spool works.
Dim message = MailMessage.Parse(File.ReadAllBytes(path))

Await client.SendAsync(message, CancellationToken.None)

C#

// A message saved by the core library - or by any other mail program,
// since a .eml file is just RFC 5322 text - can be submitted
// unchanged. This is how a queued-mail folder or a retry spool works.
var message = MailMessage.Parse(File.ReadAllBytes(path));

await client.SendAsync(message, CancellationToken.None);

PowerShell

$message = [Bastion.Mail.MailMessage]::Parse(
    [System.IO.File]::ReadAllBytes('C:\mail\queue\pending.eml'))

$client.SendAsync($message, $token).GetAwaiter().GetResult()

VB.NET

' Unlike a download, the total is known exactly here - the message
' has already been built - so PercentComplete is reliable.
AddHandler client.Progress,
    Sub(s, e)
        If e.PercentComplete.HasValue Then
            Console.WriteLine("{0}% ({1} of {2} bytes)",
                              e.PercentComplete.Value,
                              e.BytesTransferred, e.TotalBytes)
        End If
    End Sub

' A very large message can take longer to acknowledge than an
' ordinary command, because the server may scan it before replying.
' This timeout covers the wait after the final dot, separately from
' the general one.
client.DataCompletionTimeout = 600000

VB.NET

' The file is created on first use. OpenAsync creates the schema if
' it is missing and is safe to call every time the application
' starts - and safe to call from several processes at once.
Dim store As IMailStore = New SqliteMailStore("mail.db")

Using store
    Await store.OpenAsync(CancellationToken.None)

    Dim held = Await store.CountAsync("chris@example.net", CancellationToken.None)
    Console.WriteLine("The store holds " & held.ToString() & " message(s).")
End Using

C#

// The file is created on first use. OpenAsync creates the schema if
// it is missing and is safe to call every time the application
// starts - and safe to call from several processes at once.
using (IMailStore store = new SqliteMailStore("mail.db"))
{
    await store.OpenAsync(CancellationToken.None);

    long held = await store.CountAsync("chris@example.net", CancellationToken.None);
    Console.WriteLine("The store holds " + held + " message(s).");
}

VB.NET

Dim accountId = "chris@example.net at pop.example.net"
Dim store As IMailStore = New SqliteMailStore("mail.db")

Using store
    Await store.OpenAsync(CancellationToken.None)

    Using client As New Pop3Client()
        Await client.ConnectAsync("pop.example.net", 995,
                                  MailTransportSecurity.ImplicitTls,
                                  CancellationToken.None)
        Await client.AuthenticateAsync("chris@example.net", password,
                                       CancellationToken.None)

        ' UIDLs, never message numbers. A message number is
        ' POSITIONAL - delete message 2 and what was 3 becomes 2 -
        ' so a store keyed on it corrupts itself the first time
        ' anything is deleted. The UIDL is stable for the life of
        ' the maildrop.
        For Each entry In Await client.GetUniqueIdsAsync(CancellationToken.None)

            ' Asked BEFORE the body is fetched. This is what makes a
            ' second run cost almost nothing.
            If Await store.ExistsAsync(accountId, "INBOX", entry.UniqueId,
                                       CancellationToken.None) Then Continue For

            Dim raw = Await client.GetMessageBytesAsync(entry.MessageNumber,
                                                        CancellationToken.None)
            Dim parsed = MailMessage.Parse(raw)

            Await store.SaveAsync(New StoredMessage With {
                .AccountId = accountId,
                .Folder = "INBOX",
                .Uid = entry.UniqueId,
                .Raw = raw,
                .Subject = parsed.Subject,
                .SentOn = parsed.Date,
                .DownloadedOn = DateTimeOffset.UtcNow,
                .SearchText = parsed.Subject & " " & parsed.TextBody
            }, CancellationToken.None)
        Next

        Await client.DisconnectAsync(CancellationToken.None)
    End Using
End Using

C#

string accountId = "chris@example.net at pop.example.net";

using (IMailStore store = new SqliteMailStore("mail.db"))
{
    await store.OpenAsync(CancellationToken.None);

    using (var client = new Pop3Client())
    {
        await client.ConnectAsync("pop.example.net", 995,
                                  MailTransportSecurity.ImplicitTls,
                                  CancellationToken.None);
        await client.AuthenticateAsync("chris@example.net", password,
                                       CancellationToken.None);

        // UIDLs, never message numbers. A message number is
        // POSITIONAL - delete message 2 and what was 3 becomes 2 -
        // so a store keyed on it corrupts itself the first time
        // anything is deleted. The UIDL is stable for the life of
        // the maildrop.
        foreach (var entry in await client.GetUniqueIdsAsync(CancellationToken.None))
        {
            // Asked BEFORE the body is fetched. This is what makes a
            // second run cost almost nothing.
            if (await store.ExistsAsync(accountId, "INBOX", entry.UniqueId,
                                        CancellationToken.None)) continue;

            byte[] raw = await client.GetMessageBytesAsync(entry.MessageNumber,
                                                           CancellationToken.None);
            MailMessage parsed = MailMessage.Parse(raw);

            await store.SaveAsync(new StoredMessage
            {
                AccountId = accountId,
                Folder = "INBOX",
                Uid = entry.UniqueId,
                Raw = raw,
                Subject = parsed.Subject,
                SentOn = parsed.Date,
                DownloadedOn = DateTimeOffset.UtcNow,
                SearchText = parsed.Subject + " " + parsed.TextBody
            }, CancellationToken.None);
        }

        await client.DisconnectAsync(CancellationToken.None);
    }
}

VB.NET

Dim accountId = "chris@example.net at imap.example.net"
Dim store As IMailStore = New SqliteMailStore("mail.db")

Using store
    Await store.OpenAsync(CancellationToken.None)

    Using client As New ImapClient()
        Await client.ConnectAsync("imap.example.net", 993,
                                  MailTransportSecurity.ImplicitTls,
                                  CancellationToken.None)
        Await client.AuthenticateAsync("chris@example.net", password,
                                       CancellationToken.None)

        ' Read-only: a background download must not set \Seen on a
        ' mailbox the user is reading in another client.
        Dim status = Await client.SelectFolderAsync("INBOX", True,
                                                    CancellationToken.None)

        For Each uid In Await client.SearchAsync("ALL", CancellationToken.None)
            Dim key = uid.ToString()

            If Await store.ExistsAsync(accountId, "INBOX", key,
                                       CancellationToken.None) Then Continue For

            ' FetchMessageBytesAsync, not FetchMessageAsync. It
            ' returns the octets EXACTLY as the server holds them,
            ' and it never parses - so it is cheaper as well as
            ' faithful. A parse followed by a write is not
            ' guaranteed to reproduce the input, and for a
            ' DKIM-signed message that difference decides whether
            ' the signature still verifies.
            '
            ' False = peek, so the message is not marked read.
            Dim raw = Await client.FetchMessageBytesAsync(uid, False,
                                                          CancellationToken.None)
            If raw Is Nothing Then Continue For

            Dim parsed = MailMessage.Parse(raw)

            Await store.SaveAsync(New StoredMessage With {
                .AccountId = accountId,
                .Folder = "INBOX",
                .Uid = key,
                .Raw = raw,
                .Subject = parsed.Subject,
                .SentOn = parsed.Date,
                .DownloadedOn = DateTimeOffset.UtcNow,
                .SearchText = parsed.Subject & " " & parsed.TextBody
            }, CancellationToken.None)
        Next

        Await client.DisconnectAsync(CancellationToken.None)
    End Using
End Using

C#

string accountId = "chris@example.net at imap.example.net";

using (IMailStore store = new SqliteMailStore("mail.db"))
{
    await store.OpenAsync(CancellationToken.None);

    using (var client = new ImapClient())
    {
        await client.ConnectAsync("imap.example.net", 993,
                                  MailTransportSecurity.ImplicitTls,
                                  CancellationToken.None);
        await client.AuthenticateAsync("chris@example.net", password,
                                       CancellationToken.None);

        // Read-only: a background download must not set \Seen on a
        // mailbox the user is reading in another client.
        var status = await client.SelectFolderAsync("INBOX", true,
                                                    CancellationToken.None);

        foreach (long uid in await client.SearchAsync("ALL", CancellationToken.None))
        {
            string key = uid.ToString();

            if (await store.ExistsAsync(accountId, "INBOX", key,
                                        CancellationToken.None)) continue;

            // FetchMessageBytesAsync, not FetchMessageAsync. It
            // returns the octets EXACTLY as the server holds them,
            // and it never parses - so it is cheaper as well as
            // faithful. A parse followed by a write is not
            // guaranteed to reproduce the input, and for a
            // DKIM-signed message that difference decides whether
            // the signature still verifies.
            //
            // false = peek, so the message is not marked read.
            byte[] raw = await client.FetchMessageBytesAsync(uid, false,
                                                             CancellationToken.None);
            if (raw == null) continue;

            MailMessage parsed = MailMessage.Parse(raw);

            await store.SaveAsync(new StoredMessage
            {
                AccountId = accountId,
                Folder = "INBOX",
                Uid = key,
                Raw = raw,
                Subject = parsed.Subject,
                SentOn = parsed.Date,
                DownloadedOn = DateTimeOffset.UtcNow,
                SearchText = parsed.Subject + " " + parsed.TextBody
            }, CancellationToken.None);
        }

        await client.DisconnectAsync(CancellationToken.None);
    }
}

VB.NET

Dim accountId = "chris@example.net at smtp.example.net"
Dim store As IMailStore = New SqliteMailStore("mail.db")

Using store
    Await store.OpenAsync(CancellationToken.None)

    Dim message As New MailMessage()
    message.From.Add(New MailAddress("chris@example.net"))
    message.To.Add(New MailAddress("someone@example.org"))
    message.Subject = "Quarterly figures"

    Dim body As New MimePart("text", "plain")
    body.SetText("Attached.")
    message.Body = body

    ' Serialised ONCE and used for both the identity and the stored
    ' bytes. MailMessage.MessageId is empty until the message is
    ' written, so the identifier is read back from the octets - not
    ' from the object, which would store nothing at all.
    Dim raw = message.ToByteArray()
    Dim sentId = MailMessage.Parse(raw).MessageId

    Using client As New SmtpClient()
        Await client.ConnectAsync("smtp.example.net", 465,
                                  MailTransportSecurity.ImplicitTls,
                                  CancellationToken.None)
        Await client.AuthenticateAsync("chris@example.net", password,
                                       CancellationToken.None)
        Await client.SendAsync(message, CancellationToken.None)
        Await client.DisconnectAsync(CancellationToken.None)
    End Using

    ' Recorded only after the server accepted it, and recorded as
    ' the bytes that were actually transmitted.
    Await store.SaveAsync(New StoredMessage With {
        .AccountId = accountId,
        .Folder = "Sent",
        .Uid = sentId,
        .Raw = raw,
        .Subject = message.Subject,
        .SentOn = DateTimeOffset.Now,
        .DownloadedOn = DateTimeOffset.UtcNow,
        .SearchText = message.Subject
    }, CancellationToken.None)
End Using

C#

string accountId = "chris@example.net at smtp.example.net";

using (IMailStore store = new SqliteMailStore("mail.db"))
{
    await store.OpenAsync(CancellationToken.None);

    var message = new MailMessage();
    message.From.Add(new MailAddress("chris@example.net"));
    message.To.Add(new MailAddress("someone@example.org"));
    message.Subject = "Quarterly figures";

    var body = new MimePart("text", "plain");
    body.SetText("Attached.");
    message.Body = body;

    // Serialised ONCE and used for both the identity and the stored
    // bytes. MailMessage.MessageId is empty until the message is
    // written, so the identifier is read back from the octets - not
    // from the object, which would store nothing at all.
    byte[] raw = message.ToByteArray();
    string sentId = MailMessage.Parse(raw).MessageId;

    using (var client = new SmtpClient())
    {
        await client.ConnectAsync("smtp.example.net", 465,
                                  MailTransportSecurity.ImplicitTls,
                                  CancellationToken.None);
        await client.AuthenticateAsync("chris@example.net", password,
                                       CancellationToken.None);
        await client.SendAsync(message, CancellationToken.None);
        await client.DisconnectAsync(CancellationToken.None);
    }

    // Recorded only after the server accepted it, and recorded as
    // the bytes that were actually transmitted.
    await store.SaveAsync(new StoredMessage
    {
        AccountId = accountId,
        Folder = "Sent",
        Uid = sentId,
        Raw = raw,
        Subject = message.Subject,
        SentOn = DateTimeOffset.Now,
        DownloadedOn = DateTimeOffset.UtcNow,
        SearchText = message.Subject
    }, CancellationToken.None);
}

VB.NET

Dim store As IMailStore = New SqliteMailStore("mail.db")

Using store
    Await store.OpenAsync(CancellationToken.None)

    ' Nothing for the account argument searches EVERY account at
    ' once. That is the reason the store keeps one table keyed by
    ' account rather than a table or a database file per account -
    ' partitioning would make this query impossible.
    Dim hits = Await store.SearchAsync(Nothing, "invoice", 20,
                                       CancellationToken.None)

    For Each hit In hits
        Console.WriteLine(hit.Folder & ": " & hit.Subject)
    Next
End Using

C#

using (IMailStore store = new SqliteMailStore("mail.db"))
{
    await store.OpenAsync(CancellationToken.None);

    // null for the account argument searches EVERY account at once.
    // That is the reason the store keeps one table keyed by account
    // rather than a table or a database file per account -
    // partitioning would make this query impossible.
    var hits = await store.SearchAsync(null, "invoice", 20,
                                       CancellationToken.None);

    foreach (var hit in hits)
    {
        Console.WriteLine(hit.Folder + ": " + hit.Subject);
    }
}

VB.NET

Dim store As IMailStore = New SqliteMailStore("mail.db")

Using store
    Await store.OpenAsync(CancellationToken.None)

    Dim raw = Await store.GetRawAsync("chris@example.net at pop.example.net",
                                      "INBOX", "UID-00001",
                                      CancellationToken.None)

    If raw IsNot Nothing Then
        ' The octets come back exactly as they were stored, so the
        ' message can be re-parsed, forwarded, or checked against a
        ' digest recorded when it was downloaded.
        Dim message = MailMessage.Parse(raw)
        Console.WriteLine(message.Subject)
    End If
End Using

C#

using (IMailStore store = new SqliteMailStore("mail.db"))
{
    await store.OpenAsync(CancellationToken.None);

    byte[] raw = await store.GetRawAsync("chris@example.net at pop.example.net",
                                         "INBOX", "UID-00001",
                                         CancellationToken.None);

    if (raw != null)
    {
        // The octets come back exactly as they were stored, so the
        // message can be re-parsed, forwarded, or checked against a
        // digest recorded when it was downloaded.
        MailMessage message = MailMessage.Parse(raw);
        Console.WriteLine(message.Subject);
    }
}

VB.NET

' SQLite locks the DATABASE FILE, not a table, so splitting messages
' across tables buys nothing for concurrency. What actually works is
' write-ahead logging - one writer alongside any number of readers -
' and a busy timeout so a blocked writer WAITS instead of failing
' immediately with SQLITE_BUSY. Both are applied to every connection
' this store opens; the timeout is settable.
Dim store As IMailStore = New SqliteMailStore("mail.db", TimeSpan.FromSeconds(10))

Using store
    Await store.OpenAsync(CancellationToken.None)

    ' Sixteen processes writing to one file concurrently was
    ' measured at 2,400 rows with no lock failures.
    Dim held = Await store.CountAsync(Nothing, CancellationToken.None)
    Console.WriteLine(held.ToString() & " message(s) across every account.")
End Using

C#

// SQLite locks the DATABASE FILE, not a table, so splitting messages
// across tables buys nothing for concurrency. What actually works is
// write-ahead logging - one writer alongside any number of readers -
// and a busy timeout so a blocked writer WAITS instead of failing
// immediately with SQLITE_BUSY. Both are applied to every connection
// this store opens; the timeout is settable.
using (IMailStore store = new SqliteMailStore("mail.db", TimeSpan.FromSeconds(10)))
{
    await store.OpenAsync(CancellationToken.None);

    // Sixteen processes writing to one file concurrently was
    // measured at 2,400 rows with no lock failures.
    long held = await store.CountAsync(null, CancellationToken.None);
    Console.WriteLine(held + " message(s) across every account.");
}

VB.NET

Dim type = ContentType.Parse("text/plain; charset=utf-8")
Console.WriteLine(type.MediaType)     ' text
Console.WriteLine(type.MediaSubtype)  ' plain
Console.WriteLine(type.Charset)       ' utf-8

VB.NET

Dim from = MailAddress.Parse("Alice Smith <alice@example.org>")
Console.WriteLine(from.DisplayName)  ' Alice Smith
Console.WriteLine(from.Address)      ' alice@example.org

VB.NET

AddHandler client.CertificateReceived,
    Sub(s, e)
        ' Pin one known self-signed certificate, and nothing else.
        e.Accept = e.Certificate.GetCertHashString() = KnownFingerprint
    End Sub

VB.NET

Try
    Await client.ConnectAsync(host, port, MailTransportSecurity.ImplicitTls)
    Await client.AuthenticateAsync(user, password)
Catch ex As MailException
    Select Case ex.Code
        Case MailErrorCode.AuthenticationFailed
            PromptForPassword()
        Case MailErrorCode.CertificateRejected
            OfferToPinTheFingerprint()
        Case MailErrorCode.SendOutcomeUnknown
            ' Do NOT resend. Nobody knows whether it arrived.
            FlagForManualCheck()
        Case Else
            Log(ex.Code, ex.Message)
    End Select
End Try

VB.NET

Try
    Await client.ConnectAsync("mail.example.net", 995)
Catch ex As MailException
    Console.Error.WriteLine(ex.Message)
End Try

VB.NET

' Parse a message retrieved from a server
Dim message = MailMessage.Parse(octets)
Console.WriteLine(message.Subject)
Console.WriteLine(message.From.ToString())
Console.WriteLine(message.TextBody)

For Each attachment In message.Attachments
    File.WriteAllBytes(attachment.FileName, attachment.GetContent())
Next

VB.NET

AddHandler client.MessageDownloading,
    Sub(s, e)
        ' Skip anything over ten megabytes.
        If e.ExpectedSize.HasValue AndAlso e.ExpectedSize.Value > 10 * 1024 * 1024 Then
            e.Cancel = True
        End If
    End Sub

VB.NET

AddHandler client.CommandSent, Sub(s, e) Debug.WriteLine("C: " & e.Line)
AddHandler client.ResponseReceived, Sub(s, e) Debug.WriteLine("S: " & e.Line)

VB.NET

Await client.AuthenticateAsync(New SaslPlain("chris@example.net", "hunter2"))

VB.NET

Dim token = Await AcquireTokenFromYourIdentityProvider()
Await client.AuthenticateAsync(New SaslXOAuth2("chris@example.net", token))

VB.NET

Using client As New Pop3Client()
    Await client.ConnectAsync("pop.example.net", 995)
    Await client.AuthenticateAsync("chris@example.net", "hunter2")

    For Each entry In Await client.GetUniqueIdsAsync()
        If Not alreadySeen.Contains(entry.UniqueId) Then
            Dim message = Await client.GetMessageAsync(entry.MessageNumber)
            Console.WriteLine(message.Subject)
        End If
    Next

    Await client.DisconnectAsync()
End Using

VB.NET

Using client As New ImapClient()
    Await client.ConnectAsync("imap.example.net", 993)
    Await client.AuthenticateAsync("chris@example.net", password)

    For Each folder In Await client.GetFoldersAsync()
        Console.WriteLine(folder.Name)
    Next

    Dim status = Await client.SelectFolderAsync("INBOX")
    Console.WriteLine("{0} messages", status.MessageCount)

    For Each uid In Await client.SearchAsync("UNSEEN")
        Dim summary = Await client.FetchSummaryAsync(uid)
        Console.WriteLine(summary.Envelope.Subject)
    Next

    Await client.DisconnectAsync()
End Using