Send email with custom header

In this article we’ll show how to create and send email message with custom header added.

As a prerequisite you need to add reference to Mail.dll .NET email component to your project.

In contrast to System.Net.Mail, Mail.dll allows almost any manipulation to email message’s MIME tree. This includes adding custom headers on the root level. The easiest way to achieve this, is to use MailBuilder class and AddCustomHeader method:

MailBuilder builder = new MailBuilder();
builder.AddCustomHeader("x-spam-value", "90%");

As you can see this method operates on higher level of abstraction than MIME document, but when the email is created, you can observe that the custom header was actually added to the MIME document root:

IMail email = builder.Create();
string header = email.Document.Root.Headers["x-spam-value"];

Custom headers (those that are not defined by email standards like Date or Subject) should be prefixed with “X-” string (header names case is not important).

Following is the entire sample, that creates new email message, adds custom header. Than it connects to specified SMTP server and sends the message. Please note that some error handling is missing for simplicity and you should examine SendMessageResult result object returned by SendMessage to be sure that email sending was successful.

// C# version

using System;
using Limilabs.Mail;
using Limilabs.Mail.Headers;
using Limilabs.Client.SMTP;

class Program
{
    static void Main(string[] args)
    {
        // Use builder object to create new email message
        MailBuilder builder = new MailBuilder();
        builder.Subject = "Test";
        builder.Text = "This is plain text message.";
        builder.From.Add(new MailBox("alice@mail.com", "Alice"));
        builder.To.Add(new MailBox("bob@mail.com", "Bob"));

        builder.AddCustomHeader("x-spam-value", "90%");

        IMail email = builder.Create();

        // Send the message
        using (Smtp smtp = new Smtp())
        {
            smtp.Connect("server.example.com");    // or ConnectSSL
            smtp.UseBestLogin("user", "password");

            smtp.SendMessage(email);

            smtp.Close();
        }
    }
};

' VB.NET version

Imports System;
Imports Limilabs.Mail
Imports Limilabs.Mail.Headers
Imports Limilabs.Client.SMTP

Public Module Module1
    Public Sub Main(ByVal args As String())

        ' Use builder object to create new email message
        Dim builder As New MailBuilder()
        builder.Subject = "Test"
        builder.Text = "This is plain text message."
        builder.From.Add(New MailBox("alice@mail.com", "Alice"))
        builder.[To].Add(New MailBox("bob@mail.com", "Bob"))

        builder.AddCustomHeader("x-spam-value", "90%")

        Dim email As IMail = builder.Create()

        ' Send the message
        Using smtp As New Smtp()
            smtp.Connect("server.example.com")    ' or ConnectSSL
            smtp.UseBestLogin("user", "password")

            smtp.SendMessage(email)

            smtp.Close()
        End Using

    End Sub
End Module

Fluent interface version:

// C# version

IMail email = Mail.Text("This is plain text message.")
    .Subject("Test")
    .From(New MailBox("alice@mail.com", "Alice"))
    .To("to@mail.com")
    .AddCustomHeader("X-Header", "x header value")
    .Create();

// Send the message
using (Smtp smtp = new Smtp())
{
    smtp.Connect("server.example.com");
    smtp.UseBestLogin("user", "password");
    smtp.SendMessage(email);
    smtp.Close();
}

' VB.NET version

Dim email As IMail = Mail.Text("This is plain text message.") _
  .Subject("Test") _
  .From(New MailBox("alice@mail.com", "Alice")) _
  .[To](New MailBox("bob@mail.com", "Bob")) _
  .AddCustomHeader("X-Header", "x header value") _
  .Create()

' Send the message
Using smtp As New Smtp()
    smtp.Connect("server.example.com")
    smtp.UseBestLogin("user", "password")
    smtp.SendMessage(email)
    smtp.Close()
End Using