Receive emails in .NET

December 8th, 2018

This article describes how to receive email messages using Mail.dll .NET email library.

Sending email is built into .NET, so there’s no need for 3rd party library, however Mail.dll is much easier to use than SmtpClient,
and much more powerful. Receiving is a bit more complicated. It does require a 3rd party library.

There are two standard protocols for receiving emails IMAP (Internet Message Access Protocol) and POP3 (Post Office Protocol).
Without getting in to much details IMAP is better and offers more features when receiving emails (you can find a detailed IMAP vs POP3 comparison here). We’ll use Imap class to work with this protocol.

As a prerequisite you need to add reference to Mail.dll to your project and import following namespaces:

// C#

using Limilabs.Mail;
using Limilabs.Client.IMAP;
' VB

Imports Limilabs.Mail
Imports Limilabs.Client.IMAP

First thing you need to do is to connect to your IMAP email server. Most servers today require SSL or TLS. We’ll use ConnectSSL(string host) to connect and establish secure channel. This method makes sure correct SSL/TLS versions are used and server certificate are valid:

// C#

using (Imap imap = new Imap ())
{
    imap.ConnectSSL("imap.example.com");  
    imap.UseBestLogin("user@example.com", "password");

' VB

Using imap As New Imap()
    imap.ConnectSSL("imap.example.com")
    imap.UseBestLogin("user@example.com", "password")

Next step is to select a folder which we want to access and download unique ids (UIDs) of email messages. In this example we’ll search and receive unseen emails from INBOX folder.

// C#

imap.SelectInbox();
List<long> uids = imap.Search(Flag.Unseen);
' VB

imap.SelectInbox()
Dim uids As List(Of Long) = imap.Search(Flag.Unseen)

Finally we need to receive and process those emails. On the server emails are stored in MIME format. GetMessageByUID method receives emails as a raw byte array and MailBuilder class can be used to parse it:

// C#

foreach (long uid in uids)
{
    var eml = imap.GetMessageByUID(uid)
    IMail email = new MailBuilder().CreateFromEml(eml);

    Console.WriteLine(email.Subject);
    Console.WriteLine(email.Text);
}
' VB

For Each uid As Long In uids
{
    Dim eml = imap.GetMessageByUID(uid)
    Dim email As IMail = builder.CreateFromEml(eml)

    Console.WriteLine(email.Subject)
    Console.WriteLine(email.Text)
}

At that point you can also access attachments or From and To fields.

Here are the full samples that receive emails in both C# and VB .NET:

// C#

using Limilabs.Mail;
using Limilabs.Client.IMAP;

class Program
{
    static void Main(string[] args)
    {
        using(Imap imap = new Imap())
        {
            imap.ConnectSSL("imap.example.com"); 
            imap.UseBestLogin("user", "password");

            imap.SelectInbox();
            List<long> uids = imap.Search(Flag.Unseen);

            foreach (long uid in uids)
            {
                var eml = imap.GetMessageByUID(uid);
                IMail email = new MailBuilder()
                    .CreateFromEml(eml);

                Console.WriteLine(email.Subject);
                Console.WriteLine(email.Text);
            }
            imap.Close();
        }
    }
};
' VB.NET

Imports Limilabs.Mail
Imports Limilabs.Client.IMAP

Public Module Module1
    Public Sub Main(ByVal args As String())
        Using imap As New Imap()
            imap.ConnectSSL("imap.example.com")
            imap.UseBestLogin("user", "password")

            imap.SelectInbox()
            Dim uids As List(Of Long) = imap.Search(Flag.Unseen)

            For Each uid As Long In uids
                Dim eml = imap.GetMessageByUID(uid)
                Dim email As IMail = New MailBuilder() _
                    .CreateFromEml(eml)

                Console.WriteLine(email.Subject)
                Console.WriteLine(email.Text)
            Next
            imap.Close()
        End Using
    End Sub
End Module

NavigateToTest VS2017 extension

January 24th, 2018

You can download the extension here:
NavigateToTest Visual Studio 2017 extension

Here’s the latest version that supports Visual Studio 2017 and Visual Studio 2015.

Extension is convention based. It matches ClassName file with ClassNameTest or ClassNameTests and vice-versa, so you can easily navigate to the test file and back.

Here are some screenshots:

Here’s the toolbar and two opened files:

You can download the extension here:
NavigateToTest Visual Studio 2017 extension

Mail.dll is not affected by Mailsploit

December 5th, 2017

The Mailsploit vulnerability stems from how email servers/clients interpret email addresses containing encoded words. Incorrectly handling those, could allow an attacker to spoof email identities.

Recent specs (RFC-2822 and RFC-5322) don’t allow using encoded-words for email addresses (addr-spec):

3.4. Address Specification:
address = mailbox / group
mailbox = name-addr / addr-spec
name-addr = [display-name] angle-addr
angle-addr = [CFWS] “<" addr-spec ">” [CFWS] / obs-angle-addr
display-name = phrase

Here are the unit test that show how Mail.dll behaves when such malicious emails are parsed. Please note that encoded-words are not decoded when part of email address.

[Test]
public void Test1()
{
    string eml = @"From: =?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=@example.com

Body";

    IMail mail = new MailBuilder().CreateFromEmlASCII(eml);

    Assert.AreEqual(
        "=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=@example.com", 
        mail.Headers["From"]);

    Assert.AreEqual(
        "=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=@example.com", 
        mail.From[0].Address);                                      // Correct

    Assert.AreEqual(
        null, 
        mail.From[0].Name);                                         // Correct
}
[Test]
public void Test2()
{
    string eml = @"From: =?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=

Body";

    IMail mail = new MailBuilder().CreateFromEmlASCII(eml);

    Assert.AreEqual(
        "=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=", 
        mail.Headers["From"]);

    Assert.AreEqual(
        null, 
        mail.From[0].Address);                // Correct

    Assert.AreEqual(
        "potus@whitehouse.gov", 
        mail.From[0].Name);      // Correct - this is correct behavior, 
                                 // sender can put anything in the name field.
}
[Test]
public void Test3()
{
    string eml = @"From: =?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=" 
        + @"=?utf-8?Q?=00?=" 
        + @"=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=@example.com

Body";

    IMail mail = new MailBuilder().CreateFromEmlASCII(eml);

    Assert.AreEqual(
        @"=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=" 
        + @"=?utf-8?Q?=00?=" 
        + @"=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=@example.com", 
        mail.Headers["From"]);

    Assert.AreEqual(
        @"=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=" 
        + @"=?utf-8?Q?=00?=" 
        + @"=?utf-8?b?cG90dXNAd2hpdGVob3VzZS5nb3Y=?=@example.com", 
        mail.From[0].Address);            // Correct

    Assert.AreEqual(
        null, 
        mail.From[0].Name);               // Correct
}

Mail.dll allows anything in the name part of the address headers:

[Test]

public void Test4()
{
    string eml = @"From: =?utf-8?Q?=42=45=47=49=4E=20=2F"
        + @"=20=20=2F=20=00=20=50=41=53=53=45=44" 
        + @"=20=4E=55=4C=4C=20=42=59=54=45=20=2F=20=0D=0A" 
        + @"=20=50=41=53=53=45=44=20=43=52" 
        + @"=4C=46=20=2F=20=45=4E=44?= <test@example.com>

Body";

    IMail mail = new MailBuilder().CreateFromEmlASCII(eml);

    Assert.AreEqual(
        "test@example.com", 
        mail.From[0].Address);

    Assert.AreEqual(
        "BEGIN /  / \0 PASSED NULL BYTE / \r\n PASSED CRLF / END", 
        mail.From[0].Name); 

    // Note the \r\n (new line) and \0 (null) characters
}

Specification allow using encoded-words in the name (RFC2047 – 5. Use of encoded-words in message headers. (3) )
Encoded words are used to encode non-ASCII characters, for example national characters like umlauts (ä, ö, ü).

RFC2047 imposes no restrictions what characters can be encoded, which means that zero byte (\0) and new lines (\r\n) are valid characters.

Client applications must ensure that such special charters don’t ‘push’ the actual email address (“”test@example.com”) outside of control, in such way, that it becomes not visible.
It is crucial for them to display the email address (test@example.com) no matter what is in the name field.

Order process maintenance scheduled for May 16, 2017

May 10th, 2017

As part of our ongoing commitment to invest in and provide a scalable ecommerce platform that meets the advancing needs of our client base, we will be conducting planned maintenance to our system next week:

CEST: Tuesday, May 16, 2017 from 1 p.m. to 9 p.m.
CDT: Tuesday, May 16, 2017 from 6 a.m. to 2 p.m.
PDT: Tuesday, May 16, 2017 from 4 a.m. to noon
AEST: Tuesday, May 16, 2017 from 9 p.m. to Wednesday, May 17, 2017, 5 a.m.

During the planned maintenance, the system will continue to take orders. However customers will see temporary delays in fulfillment and order confirmation emails.

Once the maintenance is finished, we expect all functionality to resume; orders will be processed and order confirmation emails will be sent to customers.

OAuth 2.0 with Gmail over IMAP for installed applications

March 13th, 2017

OAuth is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.

This article describes using OAuth 2.0 to access Gmail IMAP and SMTP servers using .NET IMAP component in installed applications scenario. You can also use OAuth 2.0 for web applications.

Google.Apis

Use Nuget to download “Google.Apis.Auth” package.

Import namespaces:

// c#

using Google.Apis.Auth.OAuth2;
using Google.Apis.Auth.OAuth2.Flows;
using Google.Apis.Auth.OAuth2.Requests;
using Google.Apis.Auth.OAuth2.Responses;

using Limilabs.Client.Authentication.Google;

using Limilabs.Client.IMAP;
' VB.NET 

Imports Google.Apis.Auth.OAuth2
Imports Google.Apis.Auth.OAuth2.Flows
Imports Google.Apis.Auth.OAuth2.Requests
Imports Google.Apis.Auth.OAuth2.Responses

Imports Limilabs.Client.Authentication.Google

Imports Limilabs.Client.IMAP

Register Application

Before you can use OAuth 2.0, you must register your application using the Google Developers Console.

At least product name must be specified:

Now create credentials:

After you’ve registered, copy the “Client ID” and “Client secret” values, which you’ll need later:

Now we can define clientID, clientSecret and scope variables, as well as Google OAuth 2.0 server addresses. Scope basically specifies what services we want to have access to. In our case it is user’s email address and IMAP/SMTP access:

// c#

string clientID = "XXX.apps.googleusercontent.com";
string clientSecret = "IxBs0g5sdaSDUz4Ea7Ix-Ua";

var clientSecrets = new ClientSecrets
{
    ClientId = clientID,
    ClientSecret = clientSecret
};

var credential = new GoogleAuthorizationCodeFlow(new GoogleAuthorizationCodeFlow.Initializer
{
    ClientSecrets = clientSecrets,
    Scopes = new[] { GoogleScope.ImapAndSmtp.Name, GoogleScope.UserInfoEmailScope.Name}
});
' VB.NET 

Dim clientID As String = "XXX.apps.googleusercontent.com"
Dim clientSecret As String = "IxBs0g5sdaSDUz4Ea7Ix-Ua"

Dim clientSecrets = New ClientSecrets With { _
	.ClientId = clientID, _
	.ClientSecret = clientSecret _
}

Dim credential = New GoogleAuthorizationCodeFlow(New GoogleAuthorizationCodeFlow.Initializer With { _
	.ClientSecrets = clientSecrets, _
	.Scopes = {GoogleScope.ImapAndSmtp.Name, GoogleScope.UserInfoEmailScope.Name} _
})

Obtain an OAuth 2.0 access token

Now we’ll create authorization url:


AuthorizationCodeRequestUrl url = credential.CreateAuthorizationCodeRequest("urn:ietf:wg:oauth:2.0:oob");

Process.Start(url.Build().ToString());
' VB.NET 

Dim url As AuthorizationCodeRequestUrl = credential.CreateAuthorizationCodeRequest("urn:ietf:wg:oauth:2.0:oob")

Process.Start(url.Build().ToString())

We are using Process.Start here, but you can also embed WebBrowser control in your application.

At this point user is redirected to Google to authorize the access:

After this step user is presented a code that needs to be pasted to your application:

Please note that this code also appears in the title of the browser:

  • It is possible to monitor processes on your machine and act automatically when it is there.
  • If you use embedded WebBrowser control in your application, you can monitor the HTML document title after any redirect.

Following is a code that reads this code and contacts Google to exchange it for a refresh-token and an access-token:

string authCode = Console.ReadLine();

TokenResponse token = await credential.ExchangeCodeForTokenAsync("", authCode, "urn:ietf:wg:oauth:2.0:oob", CancellationToken.None);

string accessToken = token.AccessToken;
' VB.NET 

Dim authCode As String = Console.ReadLine()

Dim token As TokenResponse = Await credential.ExchangeCodeForTokenAsync("", authCode, "urn:ietf:wg:oauth:2.0:oob", CancellationToken.None)

Dim accessToken As String = token.AccessToken

An access token is usually valid for a maximum of one hour, and allows you to access the user’s data. You also received a refresh token. A refresh token can be used to request a new access token once the previous expired.

Access IMAP/SMTP server

Finally we’ll ask Google for user’s email and use LoginOAUTH2 method to access Gmail’s IMAP server:

// c#

GoogleApi api = new GoogleApi(accessToken);
string user = api.GetEmail();

using (Imap imap = new Imap())
{
    imap.ConnectSSL("imap.gmail.com");
    imap.LoginOAUTH2(user, accessToken);

    imap.SelectInbox();
    List<long> uids = imap.Search(Flag.Unseen);

    foreach (long uid in uids)
    {
        var eml = imap.GetMessageByUID(uid);
        IMail email = new MailBuilder().CreateFromEml(eml);
        Console.WriteLine(email.Subject);
    }
    imap.Close();
}
' VB.NET 

Dim api As New GoogleApi(accessToken)
Dim user As String = api.GetEmail()

Using imap As New Imap()
	imap.ConnectSSL("imap.gmail.com")
	imap.LoginOAUTH2(user, accessToken)

	imap.SelectInbox()
	Dim uids As List(Of Long) = imap.Search(Flag.Unseen)

	For Each uid As Long In uids
		Dim eml = imap.GetMessageByUID(uid)
		Dim email As IMail = New MailBuilder().CreateFromEml(eml)
		Console.WriteLine(email.Subject)
	Next
	imap.Close()
End Using

Refreshing access token

An access token is usually short lived and valid for a maximum of one hour. The main reason behind this is security and prevention of replay attacks. This means that for long-lived applications you need to refresh the access token.

Your refresh token will be sent only once – don’t loose it!

We recommend storing entire TokenResponse object received from GoogleAuthorizationCodeFlow.ExchangeCodeForTokenAsync method call. This object contains both: refresh token and access token, along with its expiration time.

The process of refreshing access token is simple:

// c#

TokenResponse refreshed = await credential.RefreshTokenAsync("", token.RefreshToken, CancellationToken.None);

' VB.NET 

Dim refreshed As TokenResponse = Await credential.RefreshTokenAsync("", token.RefreshToken, CancellationToken.None)