Posts Tagged ‘Email component’

Logging in Mail.dll

Monday, August 1st, 2016

To enable logging for Mail.dll clients (Imap, Pop3, Smtp) you only need to add the following line before you connect:

// C# version:

Limilabs.Mail.Log.Enabled = true;

' VB.NET version:

Limilabs.Mail.Log.Enabled = True

You can observe the log output by:

  • looking at the Visual Studio’s output window (View/Output/’Show output from’: Debug)
  • subscribing to Log.WriteLine event
  • defining custom listeners using your application’s config file (App.config or Web.config)
  • using log4net

This is how the log looks like in the Visual Studio’s output window:

You can also enable logging using your application’s config file (App.config, Web.config):

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.diagnostics>

      <switches>
        <add name="Mail.dll" value="Verbose" />
      </switches>

    </system.diagnostics>
</configuration>

log4net

If you are using the latest version of log4net.dll, Mail.dll is going to use log4net instead of standard .NET System.Net.TraceSource class. Please refer to log4net manual on how to capture log entries.

Mail.dll uses logger called “Mail.dll” (_logger = LogManager.GetLogger(“Mail.dll”)) and level Info (_logger.Info(message)) to log information.

Please remember that even when using log4net, you need to enable logging by setting “Limilabs.Mail.Log.Enabled = True” or by setting Mail.dll trace switch in the config file (App.config, Web.config) to Verbose as shown above.

Log to file

You’ll need to define a TextWriterTraceListener that writes to a file and connect it with Mail.dll trace source. The easiest solution is to modify your application’s config file (App.config, Web.config) accordingly:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.diagnostics>

        <trace autoflush="true"/>
   
        <switches>
            <add name="Mail.dll" value="Verbose"/>
        </switches>
   
        <sources>
            <source name="Mail.dll">
                <listeners>
                    <add name="MailLogFile"/>
                </listeners>
            </source>
        </sources>
   
        <sharedListeners>
            <add 
                name="MailLogFile" 
                type="System.Diagnostics.TextWriterTraceListener" 
                initializeData="c:\mail.log"/>
        </sharedListeners>

    </system.diagnostics>
</configuration>

Log.WriteLine

Log class exposes WriteLine event. You can use that event to subscribe your own logging library.

// C#

Log.WriteLine += Console.WriteLine;
' VB.NET

Log.WriteLine += Console.WriteLine

Joining message/partial emails

Friday, January 2nd, 2015

With Mail.dll you can join a message split across multiple message/partial emails.

“Message/partial” emails allow large objects to be delivered as several mail messages and automatically joined by the receiving client. This mechanism can be used when intermediate transport agents, such as SMTP servers, are limiting the size of individual mails that can be sent. Content-Type “message/partial” indicates that the body contains a fragment of a larger email.

// C#

IMail part1 = ...
IMail part2 = ...

PartialMailJoiner joiner = new PartialMailJoiner();
joiner.Add(part1);
joiner.Add(part2);

IMail email = joiner.Join();
var attachments = email.Attachments;
' VB.NET

Dim part1 As IMail = "..."
Dim part2 As IMail = "..."

Dim joiner As New PartialMailJoiner()
joiner.Add(part1)
joiner.Add(part2)

Dim email As IMail = joiner.Join()
Dim attachments = email.Attachments

PartialMailJoiner.Add method checks if all parts of message/partial email are present and you can use PartialMailJoiner.Join method:

// C#

IMail part1 = ...
IMail part2 = ...

List<IMail> parts = new List<IMail>{part1, part2};

PartialMailJoiner joiner = new PartialMailJoiner();

foreach (IMail part in parts)
{
    if (part.IsPartial)
    {
        bool allPartsPresent = joiner.Add(part);

        if (allPartsPresent)
        {
            IMail email = joiner.Join();
            var attachments = email.Attachments;
        }
    }
}

' VB.NET

Dim part1 As IMail = ...
Dim part2 As IMail = ...

Dim parts As New List(Of IMail)() From { _
	part1, _
	part2 _
}

Dim joiner As New PartialMailJoiner()

For Each part As IMail In parts
    If part.IsPartial Then
        Dim allPartsPresent As Boolean = joiner.Add(part)

	If allPartsPresent Then
            Dim email As IMail = joiner.Join()
	    Dim attachments = email.Attachments
        End If
    End If
Next

Joining fragmented message is a bit tricky. Messages filtered using Content-Type’s id property and then sorted by Content-Type’s number property. Note that part numbering begins with 1, not 0.

The headers of the encapsulated message must be merged with the headers of the enclosing entities. Following rules must be used:

  • All of the header fields from the initial enclosing message, except those that start with “Content-” and the specific header fields” “Subject”, “Message-ID”, “Encrypted”, and “MIME-Version”, must be copied, in order, to the new message.
  • The header fields in the enclosed message which start with “Content-“, plus the “Subject”, “Message-ID”, “Encrypted”, and “MIME-Version” fields, must be appended, in order, to the header fields of the new message. all others will be ignored and dropped.
  • All of the header fields from the second and any subsequent enclosing messages are ignored.

Processing applesingle and appledouble email attachments

Wednesday, October 1st, 2014

Mail.dll now supports applesingle and appledouble email attachments.

AppleSingle and AppleDouble are file formats developed to store Mac OS “dual-forked” files (data fork and resource fork)

AppleSingle combines both file forks and the related Finder meta-file information into a single file MIME entity, usually with application/applesingle content-type email header. Applesingle files are parsed by Mail.dll and data fork is extracted as a standard email attachment available through IMail.Attachments collection.

AppleDouble stores both forks as two separate files. Thus it uses multipart mime type – inside two MIME entities are stored: application/applefile, which contains resource fork only, and regular MIME attachment e.g. application/octet-stream content-type.

In both cases you simply use IMail.Attachments collection to access attachments.

byte[] eml = ...;

IMail mail = new MailBuilder().CreateFromEml(eml);
Assert.AreEqual(1, mail.Attachments.Count);
MimeData att = (MimeData) mail.Attachments[0];

byte[] data = att.Data; // data fork

You can control, if apple attachments should be processed using MailBuilder.ProcessAppleAutomatically property. When it is set to false applesingle files are not parsed and data fork is not extracted.

byte[] eml = ...;

MailBuilder builder = new MailBuilder();
builder.ProcessBinHexAutomatically = false;
IMail mail = builder.CreateFromEml(eml);

MimeAppleSingle appleSingle = (MimeAppleSingle) mail.Attachments[0];

Assert.AreEqual(ContentType.ApplicationAppleSingle, appleSingle.ContentType);

byte[] resource = appleSingle.AppleSingle.Resources;
string name = appleSingle.AppleSingle.RealName;

OAuth 2.0 with Gmail over IMAP for service account

Thursday, September 11th, 2014

In this article I’ll show how to access Gmail account of any domain user, using OAuth 2.0, .NET IMAP component and service accounts. The basic idea is that domain administrator can use this method to access user email without knowing user’s password.

This scenario is very similar to 2-legged OAuth, which uses OAuth 1.0a. Although it still works, it has been deprecated by Google and OAuth 2.0 service accounts were introduced.

The following describes how to use XOAUTH2 and OAuth 2.0 to achieve the equivalent of 2-legged OAuth.

Google APIs console

First you need to visit the Google Developers Console and create a service account:

console_0

console_1

console_2

Download and save this private key (XYZ.p12), you’ll need that later:

console_3

Go to “Service accounts” and click “View Client ID”:

console_4

Make a note of the Client ID and Email address (Service account).

Google Apps Dashboard

Next step is to authorize access for newly created service account.

Visit your domain administration panel:
https://www.google.com/a/cpanel/yourdomain.com/ManageOauthClients

Then click “Advanced tools”, “Authentication” and “Manage third party OAuth Client access”.

On this screen you can authorize service account to access email scope:

cpanel_1

Use previously remembered Client ID and “https://mail.google.com/”, which is IMAP/SMTP API scope:

Client Name: 1234567890
One or More API Scopes: https://mail.google.com/

Google.Apis

Use Nuget to download “Google.Apis.Auth.Mvc” and “Google.Apis.Auth” packages.

Access IMAP/SMTP server

// C#

using System.Security.Cryptography.X509Certificates;
using System;
using System.Threading;
using Limilabs.Client.IMAP;
using Limilabs.Test.Constants;
using Google.Apis.Auth.OAuth2;
using Limilabs.Client.Authentication.Google;


const string serviceAccountEmail = "name@xxxxxxxxxx.gserviceaccount.com";
const string serviceAccountCertPath = @"c:\XYZ.p12";
const string serviceAccountCertPassword = "notasecret";
const string userEmail = "user@your-domain.com";

X509Certificate2 certificate = new X509Certificate2(
    serviceAccountCertPath, 
    serviceAccountCertPassword, 
    X509KeyStorageFlags.Exportable);

ServiceAccountCredential credential = new ServiceAccountCredential(
    new ServiceAccountCredential.Initializer(serviceAccountEmail)
    {
        Scopes = new[] { GoogleScope.ImapAndSmtp.Name },
        User = userEmail
    }.FromCertificate(certificate));

bool success = credential.RequestAccessTokenAsync(CancellationToken.None).Result;
Assert.IsTrue(success);

using (Imap imap = new Imap())
{
    imap.ConnectSSL("imap.gmail.com");
    imap.LoginOAUTH2(userEmail, credential.Token.AccessToken);

    imap.SelectInbox();

    foreach (long uid in uids)
    {
        var eml = client.GetMessageByUID(uid);
        IMail email = new MailBuilder().CreateFromEml(eml);
        Console.WriteLine(email.Subject);
    }

    imap.Close();
}
' VB.NET

Imports System.Security.Cryptography.X509Certificates
Imports System.Threading
Imports Limilabs.Client.IMAP
Imports Limilabs.Test.Constants
Imports Google.Apis.Auth.OAuth2
Imports Limilabs.Client.Authentication.Google


Const  serviceAccountEmail As String = "name@xxxxxxxxxx.gserviceaccount.com"
Const  serviceAccountCertPath As String = "c:\XYZ.p12"
Const  serviceAccountCertPassword As String = "notasecret"
Const  userEmail As String = "user@your-domain.com"

Dim certificate As New X509Certificate2(serviceAccountCertPath, serviceAccountCertPassword, X509KeyStorageFlags.Exportable)

Dim credential As New ServiceAccountCredential(New ServiceAccountCredential.Initializer(serviceAccountEmail) With { _
	Key .Scopes = New () {GoogleScope.ImapAndSmtp.Name}, _
	Key .User = userEmail _
}.FromCertificate(certificate))

Dim success As Boolean = credential.RequestAccessTokenAsync(CancellationToken.None).Result
Assert.IsTrue(success)

Using imap As New Imap()
	imap.ConnectSSL("imap.gmail.com")
	imap.LoginOAUTH2(userEmail, credential.Token.AccessToken)

	imap.SelectInbox()

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

	imap.Close()
End Using

Process BinHex email attachments

Tuesday, September 9th, 2014

One of the recent Mail.dll email component updates brings the ability to process BinHex encoded email attachments.

BinHex is short for “binary-to-hexadecimal”. It is a binary to 7bit ASCII text encoding, that was used on the Mac OS for sending binary files through email. It is similar to Uuencode and Base64 encodings (both supported by Mail.dll), but it combines both “forks” (data and resources) of the Mac file.

As with all other data-to-ASCII encodings, BinHex files usually take more space than the original files, however as BinHex includes very simple run-length compression, encoded files may be smaller under some circumstances.

Below you can see such file inside a MIME entity:

Content-type: application/mac-binhex40; name="binhex.test.sit"
Content-disposition: attachment; filename="binhex.test.sit"

(This file must be converted with BinHex 4.0)

:$f*TEQKPH#jdCA0d,R0TG!"6594%8dP8)3#3"!&m!*!%EMa6593K!!%!!!&mFNa
[...]
Z"`#3!fKi!!!:

Mail.dll is going to extract data fork from such entity and put it in the IMail.Attachments collection, just like it was attached using standard MIME-way.

byte[] eml = ...;

IMail mail = new MailBuilder().CreateFromEml(eml);
Assert.AreEqual(1, mail.Attachments.Count);
MimeData att = (MimeData) mail.Attachments[0];

byte[] data = att.Data; // data fork

You can control, if BinHex attachments should be processed using MailBuilder.ProcessBinHexAutomatically property:

byte[] eml = ...;

MailBuilder builder = new MailBuilder();
builder.ProcessBinHexAutomatically = false;
IMail mail = builder.CreateFromEml(eml);
Assert.AreEqual(1, mail.Attachments.Count);
MimeBinHex binHex = (MimeBinHex) mail.Attachments[0];

byte[] data = binHex.BinHex.Data;
byte[] resource = binHex.BinHex.Resource;

string name = binHex.BinHex.Name;

As you can see, data fork is not extracted automatically and you can use MimeBinHex instance to access both data and resource forks and other information stored inside the BinHex encoded attachment.