MailKit 4.4.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved

Requires NuGet 2.12 or higher.

dotnet add package MailKit --version 4.4.0
NuGet\Install-Package MailKit -Version 4.4.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MailKit" Version="4.4.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add MailKit --version 4.4.0
#r "nuget: MailKit, 4.4.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install MailKit as a Cake Addin
#addin nuget:?package=MailKit&version=4.4.0

// Install MailKit as a Cake Tool
#tool nuget:?package=MailKit&version=4.4.0

MailKit

Package Latest Release Latest Build
MimeKit NuGet Badge MimeKit MyGet Badge MimeKit
MailKit NuGet Badge MailKit MyGet Badge MailKit
Platform Build Status Code Coverage Static Analysis
Linux/Mac Build Status Code Coverage Static Analysis
Windows Build Status Code Coverage Static Analysis

What is MailKit?

MailKit is a cross-platform mail client library built on top of MimeKit.

MailKit is a personal open source project that I have put thousands of hours into perfecting with the goal of making it the very best email framework for .NET. I need your help to achieve this.

Donating helps pay for things such as web hosting, domain registration and licenses for developer tools such as a performance profiler, memory profiler, a static code analysis tool, and more. It also helps motivate me to continue working on the project.

<a href="https://github.com/sponsors/jstedfast" _target="blank"><img alt="Click here to lend your support to MailKit by making a donation!" src="https://www.paypal.com/en_US/i/btn/x-click-but21.gif"></a>

Features

Goals

The main goal of this project is to provide the .NET world with robust, fully featured and RFC-compliant SMTP, POP3, and IMAP client implementations.

All of the other .NET IMAP client implementations that I could find suffer from major architectural problems such as ignoring unexpected untagged responses, assuming that literal string tokens will never be used for anything other than message bodies (when in fact they could be used for pretty much any string token in a response), assuming that the way to find the end of a message body in a FETCH response is by scanning for ") UID", and not properly handling mailbox names with international characters to simply name a few.

IMAP requires a LOT of time spent laboriously reading and re-reading the IMAP specifications (as well as the MIME specifications) to understand all of the subtleties of the protocol and most (all?) of the other Open Source .NET IMAP libraries, at least, were written by developers that only cared enough that it worked for their simple needs. There's nothing necessarily wrong with doing that, but the web is full of half-working, non-RFC-compliant IMAP implementations out there that it was finally time for a carefully designed and implemented IMAP client library to be written.

For POP3, libraries such as OpenPOP.NET are actually fairly decent, although the MIME parser is far too strict - throwing exceptions any time it encounters a Content-Type or Content-Disposition parameter that it doesn't already know about, which, if you read over the mailing-list, is a problem that OpenPOP.NET users are constantly running into. MailKit's Pop3Client, of course, doesn't have this problem. It also parses messages directly from the socket instead of downloading the message into a large string buffer before parsing it, so you'll probably find that not only is MailKit faster (MailKit's MIME parser, MimeKit, parses messages from disk 25x faster than OpenPOP.NET's parser), but also uses far less memory.

For SMTP, most developers use System.Net.Mail.SmtpClient which suits their needs more-or-less satisfactorily and so is probably not high on their list of needs. However, the SmtpClient implementation included with MailKit is a much better option if cross-platform support is needed or if the developer wants to be able to save and re-load MIME messages before sending them via SMTP. MailKit's SmtpClient also supports PIPELINING which should improve performance of sending messages (although might not be very noticeable).

License Information

MIT License

Copyright (C) 2013-2024 .NET Foundation and Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Installing via NuGet

The easiest way to install MailKit is via NuGet.

In Visual Studio's Package Manager Console, enter the following command:

Install-Package MailKit

Getting the Source Code

First, you'll need to clone MailKit from my GitHub repository. To do this using the command-line version of Git, you'll need to issue the following command in your terminal:

git clone --recursive https://github.com/jstedfast/MailKit.git

If you are using TortoiseGit on Windows, you'll need to right-click in the directory where you'd like to clone MailKit and select Git Clone... in the menu. Once you do that, you'll get the following dialog:

Download the source code using TortoiseGit

Fill in the areas outlined in red and then click OK. This will recursively clone MailKit onto your local machine.

Updating the Source Code

Occasionally you might want to update your local copy of the source code if I have made changes to MailKit since you downloaded the source code in the step above. To do this using the command-line version of Git, you'll need to issue the following commands in your terminal within the MailKit directory:

git pull
git submodule update

If you are using TortoiseGit on Windows, you'll need to right-click on the MailKit directory and select Git Sync... in the menu. Once you do that, you'll need to click the Pull and Submodule Update buttons in the following dialog:

Update the source code using TortoiseGit

Building

In the top-level MailKit directory, there are a number of solution files; they are:

  • MailKit.sln - includes the projects for .NET Framework 4.6.2/4.7/4.8, .NETStandard 2.0/2.1, .NET6.0 as well as the unit tests.
  • MailKit.Coverity.sln - this is used to generate Coverity static analysis builds and is not generally useful.
  • MailKit.Documentation.sln - this is used to generate the documentation found at https://mimekit.net/docs

Once you've opened the appropriate MailKit solution file in Visual Studio, you can choose the Debug or Release build configuration and then build.

Both Visual Studio 2017 and Visual Studio 2019 should be able to build MailKit without any issues, but older versions such as Visual Studio 2015 will require modifications to the projects in order to build correctly. It has been reported that adding NuGet package references to Microsoft.Net.Compilers >= 3.6.0 and System.ValueTuple >= 4.5.0 to the MimeKit and MailKit projects will allow them to build successfully.

Note: The Release build will generate the xml API documentation, but the Debug build will not.

Using MailKit

Sending Messages

One of the more common operations that MailKit is meant for is sending email messages.

using System;

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

namespace TestClient {
    class Program
    {
        public static void Main (string[] args)
        {
            var message = new MimeMessage ();
            message.From.Add (new MailboxAddress ("Joey Tribbiani", "joey@friends.com"));
            message.To.Add (new MailboxAddress ("Mrs. Chanandler Bong", "chandler@friends.com"));
            message.Subject = "How you doin'?";

            message.Body = new TextPart ("plain") {
                Text = @"Hey Chandler,

I just wanted to let you know that Monica and I were going to go play some paintball, you in?

-- Joey"
            };

            using (var client = new SmtpClient ()) {
                client.Connect ("smtp.friends.com", 587, false);

                // Note: only needed if the SMTP server requires authentication
                client.Authenticate ("joey", "password");

                client.Send (message);
                client.Disconnect (true);
            }
        }
    }
}

Retrieving Messages (via Pop3)

One of the other main uses of MailKit is retrieving messages from pop3 servers.

using System;

using MailKit.Net.Pop3;
using MailKit;
using MimeKit;

namespace TestClient {
    class Program
    {
        public static void Main (string[] args)
        {
            using (var client = new Pop3Client ()) {
                client.Connect ("pop.friends.com", 110, false);

                client.Authenticate ("joey", "password");

                for (int i = 0; i < client.Count; i++) {
                    var message = client.GetMessage (i);
                    Console.WriteLine ("Subject: {0}", message.Subject);
                }

                client.Disconnect (true);
            }
        }
    }
}

Using IMAP

More important than POP3 support is the IMAP support. Here's a simple use-case of retrieving messages from an IMAP server:

using System;

using MimeKit;
using MailKit;
using MailKit.Search;
using MailKit.Net.Imap;

namespace TestClient {
    class Program
    {
        public static void Main (string[] args)
        {
            using (var client = new ImapClient ()) {
                client.Connect ("imap.friends.com", 993, true);

                client.Authenticate ("joey", "password");

                // The Inbox folder is always available on all IMAP servers...
                var inbox = client.Inbox;
                inbox.Open (FolderAccess.ReadOnly);

                Console.WriteLine ("Total messages: {0}", inbox.Count);
                Console.WriteLine ("Recent messages: {0}", inbox.Recent);

                for (int i = 0; i < inbox.Count; i++) {
                    var message = inbox.GetMessage (i);
                    Console.WriteLine ("Subject: {0}", message.Subject);
                }

                client.Disconnect (true);
            }
        }
    }
}

Fetching Information About the Messages in an IMAP Folder

One of the advantages of IMAP over POP3 is that the IMAP protocol allows clients to retrieve information about the messages in a folder without having to first download all of them.

Using the Fetch and FetchAsync method overloads (or the convenient extension methods), it's possible to obtain any subset of summary information for any range of messages in a given folder.

foreach (var summary in inbox.Fetch (0, -1, MessageSummaryItems.Envelope)) {
    Console.WriteLine ("[summary] {0:D2}: {1}", summary.Index, summary.Envelope.Subject);

It's also possible to use Fetch/FetchAsync APIs that take an IFetchRequest argument to get even more control over what to fetch:

// Let's Fetch non-Received headers:
var request = new FetchRequest {
    Headers = new HeaderSet (new HeaderId[] { HeaderId.Received }) {
        Exclude = true
    }
};

foreach (var summary in inbox.Fetch (0, -1, request)) {
    Console.WriteLine ("[summary] {0:D2}: {1}", summary.Index, summary.Headers[HeaderId.Subject]);

The results of a Fetch method can also be used to download individual MIME parts rather than downloading the entire message. For example:

foreach (var summary in inbox.Fetch (0, -1, MessageSummaryItems.UniqueId | MessageSummaryItems.BodyStructure)) {
    if (summary.TextBody != null) {
        // this will download *just* the text/plain part
        var text = inbox.GetBodyPart (summary.UniqueId, summary.TextBody);
    }

    if (summary.HtmlBody != null) {
        // this will download *just* the text/html part
        var html = inbox.GetBodyPart (summary.UniqueId, summary.HtmlBody);
    }

    // if you'd rather grab, say, an image attachment... it might look something like this:
    if (summary.Body is BodyPartMultipart) {
        var multipart = (BodyPartMultipart) summary.Body;

        var attachment = multipart.BodyParts.OfType<BodyPartBasic> ().FirstOrDefault (x => x.FileName == "logo.jpg");
        if (attachment != null) {
            // this will download *just* the attachment
            var part = inbox.GetBodyPart (summary.UniqueId, attachment);
        }
    }
}

Setting Message Flags in IMAP

In order to set or update the flags on a particular message, what is actually needed is the UID or index of the message and the folder that it belongs to.

An obvious reason to want to update message flags is to mark a message as "read" (aka "seen") after a user has opened a message and read it.

folder.Store (uid, new StoreFlagsRequest (StoreAction.Add, MessageFlags.Seen) { Silent = true });

Deleting Messages in IMAP

Deleting messages in IMAP involves setting a \Deleted flag on a message and, optionally, expunging it from the folder.

The way to mark a message as \Deleted works the same way as marking a message as \Seen.

folder.Store (uid, new StoreFlagsRequest (StoreAction.Add, MessageFlags.Deleted) { Silent = true });
folder.Expunge ();

Searching an IMAP Folder

You may also be interested in sorting and searching...

// let's search for all messages received after Jan 12, 2013 with "MailKit" in the subject...
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);
}

// let's do the same search, but this time sort them in reverse arrival order
var orderBy = new [] { OrderBy.ReverseArrival };
foreach (var uid in inbox.Sort (query, orderBy)) {
    var message = inbox.GetMessage (uid);
    Console.WriteLine ("[match] {0}: {1}", uid, message.Subject);
}

// you'll notice that the orderBy argument is an array... this is because you
// can actually sort the search results based on multiple columns:
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);
}

Of course, instead of downloading the message, you could also fetch the summary information for the matching messages or do any of a number of other things with the UIDs that are returned.

How about navigating folders? MailKit can do that, too:

// Get the first personal namespace and list the toplevel folders under it.
var personal = client.GetFolder (client.PersonalNamespaces[0]);
foreach (var folder in personal.GetSubfolders (false))
    Console.WriteLine ("[folder] {0}", folder.Name);

If the IMAP server supports the SPECIAL-USE or the XLIST (GMail) extension, you can get ahold of the pre-defined All, Drafts, Flagged (aka Important), Junk, Sent, Trash, etc folders like this:

if ((client.Capabilities & (ImapCapabilities.SpecialUse | ImapCapabilities.XList)) != 0) {
    var drafts = client.GetFolder (SpecialFolder.Drafts);
} else {
    // maybe check the user's preferences for the Drafts folder?
}

In cases where the IMAP server does not support the SPECIAL-USE or XLIST extensions, you'll have to come up with your own heuristics for getting the Sent, Drafts, Trash, etc folders. For example, you might use logic similar to this:

static string[] CommonSentFolderNames = { "Sent Items", "Sent Mail", "Sent Messages", /* maybe add some translated names */ };

static IFolder GetSentFolder (ImapClient client, CancellationToken cancellationToken)
{
    var personal = client.GetFolder (client.PersonalNamespaces[0]);

    foreach (var folder in personal.GetSubfolders (false, cancellationToken)) {
        foreach (var name in CommonSentFolderNames) {
            if (folder.Name == name)
                return folder;
        }
    }

    return null;
}

Using LINQ, you could simplify this down to something more like this:

static string[] CommonSentFolderNames = { "Sent Items", "Sent Mail", "Sent Messages", /* maybe add some translated names */ };

static IFolder GetSentFolder (ImapClient client, CancellationToken cancellationToken)
{
    var personal = client.GetFolder (client.PersonalNamespaces[0]);

    return personal.GetSubfolders (false, cancellationToken).FirstOrDefault (x => CommonSentFolderNames.Contains (x.Name));
}

Another option might be to allow the user of your application to configure which folder he or she wants to use as their Sent folder, Drafts folder, Trash folder, etc.

How you handle this is up to you.

Contributing

The first thing you'll need to do is fork MailKit to your own GitHub repository. For instructions on how to do that, see the section titled Getting the Source Code.

If you use Visual Studio for Mac or MonoDevelop, all of the solution files are configured with the coding style used by MailKit. If you use Visual Studio on Windows or some other editor, please try to maintain the existing coding style as best as you can.

Once you've got some changes that you'd like to submit upstream to the official MailKit repository, send me a Pull Request and I will try to review your changes in a timely manner.

If you'd like to contribute but don't have any particular features in mind to work on, check out the issue tracker and look for something that might pique your interest!

Reporting Bugs

Have a bug or a feature request? Please open a new bug report or feature request.

Before opening a new issue, please search through any existing issues to avoid submitting duplicates. It may also be worth checking the FAQ for common questions that other developers have had.

If MailKit does not work with your mail server, please include a protocol log in your bug report, otherwise there is nothing I can do to fix the problem.

If you are getting an exception from somewhere within MailKit, don't just provide the Exception.Message string. Please include the Exception.StackTrace as well. The Message, by itself, is often useless.

Documentation

API documentation can be found at https://www.mimekit.net/docs.

Some example snippets can be found in the Documentation/Examples directory.

Sample applications can be found in the samples directory.

A copy of the XML-formatted API reference documentation is also included in the NuGet package.

.NET Foundation

MailKit is a .NET Foundation project.

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the .NET Foundation Code of Conduct.

General .NET OSS discussions: .NET Foundation forums

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 is compatible.  net471 was computed.  net472 was computed.  net48 is compatible.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (838)

Showing the top 5 NuGet packages that depend on MailKit:

Package Downloads
Umbraco.Cms.Infrastructure The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Contains the infrastructure assembly needed to run Umbraco CMS.

NETCore.MailKit

MailKit extension for asp.net core. Easy send email in asp.net core project.

Serilog.Sinks.Email The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Send Serilog events as SMTP email using MailKit.

Abp.MailKit The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Abp.MailKit

NET6CustomLibrary

open source custom dotnet extension library

GitHub repositories (112)

Showing the top 5 popular GitHub repositories that depend on MailKit:

Repository Stars
ardalis/CleanArchitecture
Clean Architecture Solution Template: A starting point for Clean Architecture with ASP.NET Core
bitwarden/server
The core infrastructure backend (API, database, Docker, etc).
abpframework/abp
Open Source Web Application Framework for ASP.NET Core. Offers an opinionated architecture to build enterprise software solutions with best practices on top of the .NET and the ASP.NET Core platforms. Provides the fundamental infrastructure, production-ready startup templates, application modules, UI themes, tooling, guides and documentation.
aspnetboilerplate/aspnetboilerplate
ASP.NET Boilerplate - Web Application Framework
duplicati/duplicati
Store securely encrypted backups in the cloud!
Version Downloads Last updated
4.4.0 158,026 3/2/2024
4.3.0 2,422,346 11/11/2023
4.2.0 1,864,316 9/2/2023
4.1.0 2,590,637 6/17/2023
4.0.0 1,841,785 4/15/2023
3.6.0 1,922,567 3/4/2023
3.5.0 1,790,706 1/28/2023
3.4.3 2,616,244 11/25/2022
3.4.2 1,800,569 10/24/2022
3.4.1 1,709,086 9/12/2022
3.4.0 250,532 9/5/2022
3.3.0 4,263,353 6/12/2022
3.2.0 7,662,475 3/26/2022
3.1.1 3,042,667 1/30/2022
3.1.0 695,499 1/15/2022
3.0.0 1,975,928 12/11/2021
2.15.0 9,588,805 8/19/2021
2.14.0 737,460 7/28/2021
2.13.0 2,429,383 6/12/2021
2.12.0 1,244,336 5/12/2021
2.11.1 2,126,607 3/16/2021
2.11.0 140,019 3/12/2021
2.10.1 3,959,238 1/2/2021
2.10.0 2,771,691 11/21/2020
2.9.0 2,999,937 9/12/2020
2.8.0 3,080,893 7/11/2020
2.7.0 2,605,748 5/30/2020
2.6.0 6,700,346 4/4/2020
2.5.2 1,102,410 3/14/2020
2.5.1 1,174,928 2/15/2020
2.5.0 1,046,659 1/18/2020
2.4.1 2,083,883 11/10/2019
2.4.0.1 112,053 11/5/2019
2.4.0 21,958 11/3/2019
2.3.2 470,709 10/12/2019
2.3.1.6 1,078,211 9/9/2019
2.3.1 94,641 9/8/2019
2.3.0 661,634 8/24/2019
2.2.0 2,192,700 6/11/2019
2.1.5.1 853,377 5/13/2019
2.1.4 589,533 4/13/2019
2.1.3 1,163,658 2/24/2019
2.1.2 1,262,164 12/30/2018
2.1.1 193,194 12/17/2018
2.1.0.3 190,897 12/7/2018
2.0.7 881,369 10/28/2018
2.0.6 2,878,379 8/4/2018
2.0.5 470,478 7/7/2018
2.0.4 631,556 5/25/2018
2.0.3 580,274 4/15/2018
2.0.2 218,760 3/18/2018
2.0.1 1,611,143 1/6/2018
2.0.0 164,691 12/22/2017
1.22.0 614,975 11/24/2017
1.20.0 555,671 10/28/2017
1.18.1.1 679,940 9/4/2017
1.18.1 19,825 9/3/2017
1.18.0 212,556 8/7/2017
1.16.2 503,299 7/1/2017
1.16.1 620,166 5/5/2017
1.16.0 88,709 4/21/2017
1.14.2 45,448 4/12/2017
1.12.0 195,905 3/12/2017
1.10.2 207,005 1/28/2017
1.10.1 185,155 12/4/2016
1.10.0 467,291 10/31/2016

* Added net8.0 targets
* Split more sync/async logic to reduce allocations made by async state machines when calling the synchronous public APIs instead of the async APIs. (issue #1335)
* Fixed logic for formatting IMAP FETCH HEADER.FIELDS.NOT corner case that was exposed by newly added unit tests.
* Fixed SmtpClient to disconnect during Authenticate/Async on socket errors.
* Fixed SmtpClient's re-EHLO logic to disconnect on errors.
* Added workaround for Zoho IMAP servers returning MODSEQ -1. (issue #1686)
* Added workaround for some IMAP servers that use () instead of NIL for an unset Content-Location header in the BODYSTRUCTURE response. (issue #1700)
* Fixed an issue in the Socket.ConnectAsync logic that could result in unhandled exceptions on the async thread if the ConnectAsync was cancelled. (issue #1703)
* Added work-around for Yandex IMAP GetBodyPart() response not including content. (issue #1708)