SMTP Tutorial
Applies to:
Rebex Total Pack, Rebex Secure Mail
Table of content
#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:
C#
using Rebex.Net;
using Rebex.Mail;
using Rebex.Mime.Headers;
VB.NET
Imports Rebex.Net
Imports Rebex.Mail
Imports Rebex.Mime.Headers
back to top...
#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.
C#
// 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"
);
VB.NET
' 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")
back to top...
#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.
C#
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");
VB.NET
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")
back to top...
#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.
C#
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();
VB.NET
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()
back to top...
#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 component 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.
C#
Smtp.SendDirect
(
"from@example.org",
"to@example.org",
"Subject",
"Mail body"
);
VB.NET
Smtp.SendDirect( _
"from@example.org", _
"to@example.org", _
"Subject", _
"Mail body")
back to top...
#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 component 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.)
C#
// create client and connect
Smtp smtp = new Smtp();
smtp.Connect("smtp.example.org");
// authenticate - let the component 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");
VB.NET
'create client and connect
Dim smtp As New Smtp
smtp.Connect("smtp.example.org")
'authenticate - let the component 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")
back to top...
#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.
C#
// 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");
VB.NET
'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.
C#
// 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");
VB.NET
'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")
back to top...
#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:
Event name |
Description |
CommandSent |
Occurs when a command (e.g. EHLO or RCPT TO) is sent to the server. |
ResponseRead |
Occurs when response is received from the server. |
RejectedRecipient |
Occurs when a recipient is rejected by the server. |
StateChanged |
Occurs when the session state changes, such as from Disconnected to Ready, from
Ready to Sending or from Sending to Reading.
|
TransferProgress |
Occurs when a block of message data is sent to the server. |
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.
C#
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);
}
VB.NET
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 top...
Back to tutorial list...