SMTP Tutorial

Applies to: Rebex Total Pack, Rebex Secure Mail

Namespaces and assemblies 

There are several assemblies which have to be reference in your project to be able to use all features of Mail for .NET described here. Rebex.Smtp.dll is needed for any SMTP operations and contains the Smtp class and others in Rebex.Net namespace. Rebex.Mail.dll contains classes that make it possible to read, create and write e-mail messages in MIME format and contains the MailMessage class in Rebex.Mail namespace and a number of classes that represent mail message headers in Rebex.Mime.Headers namespace.Rebex.Common.dll and Rebex.Networking.dll need to be referenced too as assembly referenced by Rebex.Smtp.dll and Rebex.Mail.dll .

To gain access to all described functionality, reference the two assemblies from your project and import the following namespaces in your source files:

using Rebex.Net;
using Rebex.Mail;
using Rebex.Mime.Headers;

Imports Rebex.Net
Imports Rebex.Mail
Imports Rebex.Mime.Headers

Sending mail in a single line of code 

Let's start with the most simple code - send an e-mail using just a single line of code. All you have to know is sender (From), recipient (To), message subject and body and an address of your SMTP server.

// send mail in a single line of code
using Rebex.Net;
...

Smtp.Send
(
      "from@example.org",
      "to@example.org",
      "Mail subject",
      "Hello from Rebex!",
      "smtp.example.org"
);

' send mail in a single line of code
Imports Rebex.Net
...

Smtp.Send( _
        "from@example.org", _
        "to@example.org", _
        "Mail subject", _
        "Hello from Rebex!", _
        "smtp.example.org")

Sending mail with MailMessage class 

If your e-mail message is not as simple or you need a higher level of control over it, just create an instance of our MailMessage class, set its properties to desired values and then send it using the same method. Choose this approach when you want to set additional message fields such as CC, priority, or message ID, when you need to supply a HTML body instead of/in addition to the plain text one, or when you want to include some attachments. For more information about working with mail messages, check out the Mail message tutorial.

using Rebex.Net;
using Rebex.Mail; // contains the MailMessage and other classes
using Rebex.Mime.Headers; // contains classes that represent e-mail message headers
...

MailMessage mail = new MailMessage();
mail.From = "from@example.org";
mail.To = "to@example.org";
mail.Subject = "Mail subject";
mail.BodyText = "Hello from Rebex";
mail.Priority = MailPriority.High;

Smtp.Send(mail, "smtp.example.org");

Imports Rebex.Net
Imports Rebex.Mail 'contains the MailMessage and other classes
Imports Rebex.Mime.Headers 'contains classes that represent e-mail message headers
...

Dim mail As New MailMessage()
mail.From = New MailAddressCollection("from@example.org")
mail.To = New MailAddressCollection("to@example.org")
mail.Subject = "Mail subject"
mail.BodyText = "Hello from Rebex"
mail.Priority = MailPriority.High

Smtp.Send(mail, "smtp.example.org")

Sending multiple messages in a single connection 

Both Send methods mentioned above connect to the specified SMTP server, send the message and disconnect afterward. When sending multiple messages at one time it's better and faster to send them all in one connection. the following sample shows how to accomplish this.

using Rebex.Net;
using Rebex.Mail;
using Rebex.Mime.Headers;
...

MailMessage mailA = new MailMessage();
mailA.From = "from@example.org";
mailA.To = "first@example.org";
mailA.Subject = "First e-mail";
mailA.BodyText = "Hello from Rebex";

MailMessage mailB = new MailMessage();
mailB.From = "from@example.org";
mailB.To = "second@example.org";
mailB.Subject = "Second e-mail";
mailB.BodyText = "I've just send a mail message to first@example.org";

// create client and connect
Smtp smtp = new Smtp();
smtp.Connect("smtp.example.org");

// send mail
smtp.Send(mailA);
smtp.Send(mailB);

// and disconnect
smtp.Disconnect();

Imports Rebex.Net
Imports Rebex.Mail
Imports Rebex.Mime.Headers
...

Dim mailA As New MailMessage()
mailA.From = New MailAddressCollection("from@example.org")
mailA.To = New MailAddressCollection("first@example.org")
mailA.Subject = "First e-mail"
mailA.BodyText = "Hello from Rebex"

Dim mailB As New MailMessage()
mailB.From = New MailAddressCollection("from@example.org")
mailB.To = New MailAddressCollection("second@example.org")
mailB.Subject = "Second e-mail"
mailB.BodyText = "I've just send a mail message to first@example.org"

'create client and connect
Dim smtp As New Smtp
smtp.Connect("smtp.example.org")

'send mail
smtp.Send(mailA)
smtp.Send(mailB)

'and disconnect
smtp.Disconnect()

Sending mail directly without local SMTP server 

In some scenarios, a local SMTP server is either not available or its address is unknown. In this case, it is possible to send the e-mail directly to the SMTP server that is responsible for receiving mail for the recipient, bypassing any local SMTP servers. Technically speaking, the target SMTP server address is determined by asking the DNS system for MX records of the target domain. Anyway, you don't have to take care about it, because the library takes care about it automatically.

When sending an e-mail without local SMTP server, make sure that direct connections to remote SMTP servers are possible - a firewall must allow outgoing connections to port 25 for this to work, and the DNS subsystem must be working.

Smtp.SendDirect
(
  "from@example.org",
  "to@example.org",
  "Subject",
  "Mail body"
);

Smtp.SendDirect( _
   "from@example.org", _
   "to@example.org", _
   "Subject", _
   "Mail body")

Authenticating to an SMTP server 

Many SMTP servers require authentication for outgoing mail. This is necessary to prevent unauthorised users from sending unsolicited e-mail using the SMTP server as a proxy. Unless some other authentication method is in place (such as limitation to a range of IP addresses), it is almost certain that some form of authentication will be required by a SMTP server before it is willing to accept your outgoing mail.

There are several authentication methods available. Normally, you just have to supply your credentials to the Login method. The library will automatically choose the best (most secure) authentication method available and log you in.

Additionally, you can retrieve the list of supported authentication methods using the Smtp object's GetSupportedAuthenticationMethods method, and specify which one to use for authentication. (Or specify SmtpAuthentication.Auto that will do this automatically for you.)

// create client and connect
Smtp smtp = new Smtp();
smtp.Connect("smtp.example.org");

// authenticate - let the library choose the best method
smtp.Login("username", "password");

// or choose one yourself instead
// smtp.Login("username", "password", SmtpAuthentication.DigestMD5);

// send mail
smtp.Send("from@example.com", "to@example.com", "subject", "body");

'create client and connect
Dim smtp As New Smtp
smtp.Connect("smtp.example.org")

'authenticate - let the library choose the best method
smtp.Login("username", "password")

'or choose one yourself instead
'smtp.Login("username", "password", SmtpAuthentication.DigestMD5)

'send mail
smtp.Send("from@example.com", "to@example.com", "subject", "body")

Authentication using NTLM 

By default, the Login method won't try NTLM authentication, because it might not work correctly in some situations. However, if NTLM does work with your server, nothing stops you from using it.

// create client and connect
Smtp smtp = new Smtp();
smtp.Connect("smtp.example.org");

// authenticate using NTLM
smtp.Login("domain\\username", "password", SmtpAuthentication.Ntlm);

// send mail
smtp.Send("from@example.com", "to@example.com", "subject", "body");

'create client and connect
Dim smtp As New Smtp
smtp.Connect("smtp.example.org")

'authenticate using NTLM
smtp.Login("domain\username", "password", SmtpAuthentication.Ntlm)

'send mail
smtp.Send("from@example.com", "to@example.com", "subject", "body")

NTLM also makes it possible to authenticate as the user under whose context your application is running. This makes it possible for the user to log in without the need to specify his or her password.

// create client and connect
Smtp smtp = new Smtp();
smtp.Connect("smtp.example.org");

// authenticate using NTLM's single-sign-on feature
smtp.Login(SmtpAuthentication.Ntlm);

// send mail
smtp.Send("from@example.com", "to@example.com", "subject", "body");

'create client and connect
Dim smtp As New Smtp
smtp.Connect("smtp.example.org")

' authenticate using NTLM's single-sign-on feature
smtp.Login(SmtpAuthentication.Ntlm)

'send mail
smtp.Send("from@example.com", "to@example.com", "subject", "body")

Using events and logging communication 

In case something goes wrong, it is very useful to have a log of commands sent to the server and responses received from it for diagnostics purposes. To make this possible, the Smtp class declares the following events:

The CommandSent or ResponseRead events are particularly useful for the purpose of generating a communication log, the TransferProgress event can be used by a GUI application to display amount of transfered data or a progress bar, and RejectedRecipient event can be used to override default behaviour of not transmitting the message at all if a single recipient is rejected.

Smtp smtp = new Smtp();
smtp.CommandSent += smtp_CommandSent;
smtp.ResponseRead += smtp_ResponseRead;
smtp.Connect("smtp.example.org");
private void smtp_CommandSent(object sender, SmtpCommandSentEventArgs e)
{
    Console.WriteLine("Command: {0}", e.Command);
}

private void smtp_ResponseRead(object sender, SmtpResponseReadEventArgs e)
{
    Console.WriteLine("Response: {0}", e.Response);
}

Dim smtp As New Smtp
AddHandler smtp.CommandSent, AddressOf smtp_CommandSent
AddHandler smtp.ResponseRead, AddressOf smtp_ResponseRead
smtp.Connect("smtp.example.org")
Public Sub smtp_CommandSent(ByVal sender As Object, ByVal e As SmtpCommandSentEventArgs)
    Console.WriteLine("Command: {0}", e.Command)
End Sub

Public Sub smtp_ResponseRead(ByVal sender As Object, ByVal e As SmtpResponseReadEventArgs)
    Console.WriteLine("Response: {0}", e.Response)
End Sub

Back to tutorial list...