MailKit Documentation

To replicate the behavior of .NET's SmtpDeliveryMethod.SpecifiedPickupDirectory in MailKit, you must manually save the MimeMessage to a directory using a random GUID-based filename.

Crucially, IIS pickup directories expect messages to be "byte-stuffed" (lines beginning with . must be escaped by adding an extra .). Use FilteredStream with SmtpDataFilter and set NewLineFormat.Dos to ensure compatibility.

public static void SaveToPickupDirectory (MimeMessage message, string pickupDirectory)
{
    do {
        // Generate a random file name to save the message to.
        var path = Path.Combine (pickupDirectory, Guid.NewGuid ().ToString () + ".eml");
        Stream stream;

        try {
            // Attempt to create the new file.
            stream = File.Open (path, FileMode.CreateNew);
        } catch (IOException) {
            // If the file already exists, try again with a new Guid.
            if (File.Exists (path))
                continue;

            // Otherwise, fail immediately since it probably means that there is
            // no graceful way to recover from this error.
            throw;
        }

        try {
            using (stream) {
                // IIS pickup directories expect the message to be "byte-stuffed"
                // which means that lines beginning with "." need to be escaped
                // by adding an extra "." to the beginning of the line.
                //
                // Use an SmtpDataFilter to "byte-stuff" the message as it is written
                // to the file stream. This is the same process that an SmtpClient
                // would use when sending the message in a `DATA` command.
                using (var filtered = new FilteredStream (stream)) {
                    filtered.Add (new SmtpDataFilter ());

                    // Make sure to write the message in DOS (<CR><LF>) format.
                    var options = FormatOptions.Default.Clone ();
                    options.NewLineFormat = NewLineFormat.Dos;

                    message.WriteTo (options, filtered);
                    filtered.Flush ();
                    return;
                }
            }
        } catch {
            // An exception here probably means that the disk is full.
            //
            // Delete the file that was created above so that incomplete files
            // are not left behind for IIS to send accidentally.
            File.Delete (path);
            throw;
        }
    } while (true);
}

In ASP.NET Core, configure Google Authentication in Program.cs and use the GoogleScopedAuthorizeAttribute to request the necessary scopes. Once the credential is retrieved, use SaslMechanismOAuthBearer to authenticate the MailKit client.

// 1. Configure Authentication in Program.cs
builder.Services.AddAuthentication (options => {
    options.DefaultChallengeScheme = GoogleOpenIdConnectDefaults.AuthenticationScheme;
    options.DefaultForbidScheme = GoogleOpenIdConnectDefaults.AuthenticationScheme;
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
})
.AddCookie (options => {
    options.ExpireTimeSpan = TimeSpan.FromMinutes (5);
})
.AddGoogleOpenIdConnect (options => {
    var secrets = GoogleClientSecrets.FromFile ("client_secret.json").Secrets;
    options.ClientId = secrets.ClientId;
    options.ClientSecret = secrets.ClientSecret;
});

// Ensure middleware is used
app.UseHttpsRedirection ();
app.UseStaticFiles ();
app.UseRouting ();
app.UseAuthentication ();
app.UseAuthorization ();

// 2. Use the credential in a controller/service
[GoogleScopedAuthorize(DriveService.ScopeConstants.DriveReadonly)]
public async Task AuthenticateAsync ([FromServices] IGoogleAuthProvider auth)
{
    GoogleCredential? googleCred = await auth.GetCredentialAsync ();
    string token = await googleCred.UnderlyingCredential.GetAccessTokenForRequestAsync ();
    
    var oauth2 = new SaslMechanismOAuthBearer ("UserEmail", token);
    
    using var emailClient = new ImapClient ();
    await emailClient.ConnectAsync ("imap.gmail.com", 993, SecureSocketOptions.SslOnConnect);
    await emailClient.AuthenticateAsync (oauth2);
    await emailClient.DisconnectAsync (true);
}

The SMTP protocol does not automatically save sent messages to a 'Sent Mail' folder. To ensure messages appear there, you must manually append the message to the appropriate folder using an ImapClient.

If the server supports ImapCapabilities.SpecialUse, you can use client.GetFolder(SpecialFolder.Sent). Otherwise, you may need to navigate to the personal namespace and find the subfolder by name (e.g., "Sent Mail").

using (var client = new ImapClient ()) {
    client.Connect ("imap.server.com", 993, SecureSocketOptions.SslOnConnect);
    client.Authenticate ("username", "password");
    
    IMailFolder sentMail;
    
    if (client.Capabilities.HasFlag (ImapCapabilities.SpecialUse)) {
        sentMail = client.GetFolder (SpecialFolder.Sent);
    } else {
        var personal = client.GetFolder (client.PersonalNamespaces[0]);
        
        // Note: This assumes that the "Sent Mail" folder lives at the root of the folder hierarchy
        // and is named "Sent Mail" as opposed to "Sent" or "Sent Items" or any other variation.
        sentMail = personal.GetSubfolder ("Sent Mail");
    }
    
    sentMail.Append (message, MessageFlags.Seen);
    
    client.Disconnect (true);
}

To use OAuth 2.0 with GMail, obtain credentials from Google and use the Google.Apis.Auth library to acquire an access token. Then, use the SaslMechanismOAuthBearer class to authenticate the MailKit client.

const string GMailAccount = "username@gmail.com";

var clientSecrets = new ClientSecrets {
    ClientId = "XXX.apps.googleusercontent.com",
    ClientSecret = "XXX"
};

var codeFlow = new GoogleAuthorizationCodeFlow (new GoogleAuthorizationCodeFlow.Initializer {
    // Cache tokens on Linux/Mac in ~/.local/share/google-filedatastore/CredentialCacheFolder
    DataStore = new FileDataStore ("CredentialCacheFolder", false),
    Scopes = new [] { "https://mail.google.com/" },
    ClientSecrets = clientSecrets,
    LoginHint = GMailAccount
});

// For a web app, use AuthorizationCodeWebApp instead.
var codeReceiver = new LocalServerCodeReceiver ();
var authCode = new AuthorizationCodeInstalledApp (codeFlow, codeReceiver);

var credential = await authCode.AuthorizeAsync (GMailAccount, CancellationToken.None);

if (credential.Token.IsStale)
    await credential.RefreshTokenAsync (CancellationToken.None);

var oauth2 = new SaslMechanismOAuthBearer (credential.UserId, credential.Token.AccessToken);

using (var client = new ImapClient ()) {
    await client.ConnectAsync ("imap.gmail.com", 993, SecureSocketOptions.SslOnConnect);
    await client.AuthenticateAsync (oauth2);
    await client.DisconnectAsync (true);
}

Use SearchQuery to build complex queries (e.g., DeliveredAfter, SubjectContains, Seen) and combine them with .And(). Use inbox.Search(query) to get matching UIDs. To sort results, use inbox.Sort(query, orderBy) where orderBy is an array of OrderBy values (e.g., OrderBy.ReverseArrival, OrderBy.Subject).

// Search for messages
var query = SearchQuery.DeliveredAfter (DateTime.Parse ("2013-01-12"))
    .And (SearchQuery.SubjectContains ("MailKit")).And (SearchQuery.Seen);

foreach (var uid in inbox.Search (query)) {
	var message = inbox.GetMessage (uid);
	Console.WriteLine ("[match] {0}: {1}", uid, message.Subject);
}

// Sort search results
var orderBy = new [] { OrderBy.ReverseArrival, OrderBy.Subject };
foreach (var uid in inbox.Sort (query, orderBy)) {
	var message = inbox.GetMessage (uid);
	Console.WriteLine ("[match] {0}: {1}", uid, message.Subject);
}