SmtpClient Class

Namespace:
GemBox.Email.Smtp
Assembly:
GemBox.Email.dll

Represents mail client that can be used for sending messages using Simple Mail Transfer Protocol (SMTP).

public sealed class SmtpClient : IDisposable
Public NotInheritable Class SmtpClient
    Implements IDisposable
Inheritance:
System.Object
SmtpClient
Implements
System.IDisposable
Remarks

SmtpClient is implemented according to RFC 5321.

Constructors

SmtpClient(String)

Initializes new instance of SmtpClient class with specified host address.

public SmtpClient(string host)
Public Sub New(host As String)
Parameters
host
System.String

The address of the server.

SmtpClient(String, ConnectionSecurity, Boolean)

Initializes new instance of SmtpClient class with specified host address, ConnectionSecurity option and option to ignore SSL certificate errors.

public SmtpClient(string host, ConnectionSecurity security, bool acceptAnyCertificate)
Public Sub New(host As String, security As ConnectionSecurity, acceptAnyCertificate As Boolean)
Parameters
host
System.String

The address of the server.

security
ConnectionSecurity

A constant that determines connection security level.

acceptAnyCertificate
System.Boolean

True to ignore any SSL certificate errors; otherwise, false.

SmtpClient(String, Boolean)

Initializes new instance of SmtpClient class with specified host address, ConnectionSecurity option and option to ignore SSL certificate errors.

public SmtpClient(string host, bool acceptAnyCertificate)
Public Sub New(host As String, acceptAnyCertificate As Boolean)
Parameters
host
System.String

The address of the server.

acceptAnyCertificate
System.Boolean

True to ignore any SSL certificate errors; otherwise, false.

SmtpClient(String, Int32)

Initializes new instance of SmtpClient class with specified host address and port number.

public SmtpClient(string host, int port)
Public Sub New(host As String, port As Integer)
Parameters
host
System.String

The address of the server.

port
System.Int32

An integer value between 1 and 65535 indicating remote server IP port. Value 0 indicates that client will use default port value for specified connection security level.

SmtpClient(String, Int32, ConnectionSecurity)

Initializes new instance of SmtpClient class with specified host address, port number and ConnectionSecurity option.

public SmtpClient(string host, int port, ConnectionSecurity security)
Public Sub New(host As String, port As Integer, security As ConnectionSecurity)
Parameters
host
System.String

The address of the server.

port
System.Int32

An integer value between 1 and 65535 indicating remote server IP port. Value 0 indicates that client will use default port value for specified connection security level.

security
ConnectionSecurity

A constant that determines connection security level.

SmtpClient(String, Int32, ConnectionSecurity, RemoteCertificateValidationCallback)

Initializes new instance of SmtpClient class with specified host address, port number, ConnectionSecurity option and host certificate validation delegate method.

public SmtpClient(string host, int port, ConnectionSecurity security, RemoteCertificateValidationCallback certificateValidationCallback)
Public Sub New(host As String, port As Integer, security As ConnectionSecurity, certificateValidationCallback As RemoteCertificateValidationCallback)
Parameters
host
System.String

The address of the server.

port
System.Int32

An integer value between 1 and 65535 indicating remote server IP port. Value 0 indicates that client will use default port value for specified connection security level.

security
ConnectionSecurity

A constant that determines connection security level.

certificateValidationCallback
System.Net.Security.RemoteCertificateValidationCallback

A delegate method for validating server SSL certificate on successful connection.

Properties

ConnectTimeout

Gets or sets the connect timeout.

public TimeSpan ConnectTimeout { get; set; }
Public Property ConnectTimeout As TimeSpan
Property Value
System.TimeSpan

The connect timeout.

Exceptions
System.InvalidOperationException

Timeout cannot be set while client is connected.

Host

Gets the server address.

public string Host { get; }
Public ReadOnly Property Host As String
Property Value
System.String

The server address.

IsAuthenticated

Gets whether or not client is authenticated.

public bool IsAuthenticated { get; }
Public ReadOnly Property IsAuthenticated As Boolean
Property Value
System.Boolean

True if client is authenticated; otherwise, false.

Remarks

Property indicates whether or not client is currently authenticated with server using Authenticate(String, String) or Authenticate(String, String, SmtpAuthentication) method.

IsConnected

Gets whether or not client is connected to the server.

public bool IsConnected { get; }
Public ReadOnly Property IsConnected As Boolean
Property Value
System.Boolean

True if client is connected; otherwise, false.

LocalDomain

Gets or sets the local domain.

public string LocalDomain { get; set; }
Public Property LocalDomain As String
Property Value
System.String

The local domain.

LocalEndPoint

Gets or sets the local IP address and port.

public IPEndPoint LocalEndPoint { get; set; }
Public Property LocalEndPoint As IPEndPoint
Property Value
System.Net.IPEndPoint

The local IP address and port.

Remarks

Use this property to force the client to use a specific local IP address and port for server connection. If not specified or null, the system will automatically select the values. Value must be set before calling the Connect() method.

Exceptions
System.InvalidOperationException

Local IP address and port cannot be set while client is connected.

LogOutput

Gets or sets the log output writer.

public TextWriter LogOutput { get; set; }
Public Property LogOutput As TextWriter
Property Value
System.IO.TextWriter

The log output writer.

Remarks

Setting this property to a non-null value, enables communication logging. All commands and responses between the client and server will be written to the provided System.IO.TextWriter. Logging is disabled by setting this property to null.

Port

Gets the server IP port.

public int Port { get; }
Public ReadOnly Property Port As Integer
Property Value
System.Int32

The server IP port.

ReadTimeout

Gets or sets the read timeout.

public TimeSpan ReadTimeout { get; set; }
Public Property ReadTimeout As TimeSpan
Property Value
System.TimeSpan

The read timeout.

Exceptions
System.InvalidOperationException

Timeout cannot be set while client is connected.

Security

Gets the current connection security mode.

public ConnectionSecurity Security { get; }
Public ReadOnly Property Security As ConnectionSecurity
Property Value
ConnectionSecurity

The current connection security mode.

SupportedAuthentications

Gets collection of supported authentication mechanisms.

public ReadOnlyCollection<SmtpAuthentication> SupportedAuthentications { get; }
Public ReadOnly Property SupportedAuthentications As ReadOnlyCollection(Of SmtpAuthentication)
Property Value
System.Collections.ObjectModel.ReadOnlyCollection<SmtpAuthentication>

A read-only collection of supported authentication mechanisms.

Remarks

Collection is populated on successful connect. Values are sorted from strongest to weakest mechanism.

SupportedCapabilities

Gets the collection of supported capabilities.

public ReadOnlyCollection<SmtpCapability> SupportedCapabilities { get; }
Public ReadOnly Property SupportedCapabilities As ReadOnlyCollection(Of SmtpCapability)
Property Value
System.Collections.ObjectModel.ReadOnlyCollection<SmtpCapability>

A read-only collection of supported capabilities.

Remarks

Collection is populated on successful connect, and refreshed after successful authentication.

WriteTimeout

Gets or sets the write timeout.

public TimeSpan WriteTimeout { get; set; }
Public Property WriteTimeout As TimeSpan
Property Value
System.TimeSpan

The write timeout.

Exceptions
System.InvalidOperationException

Timeout cannot be set while client is connected.

Methods

Authenticate(String, String)

Authenticates client with specified user name and password.

public void Authenticate(string userName, string password)
Public Sub Authenticate(userName As String, password As String)
Parameters
userName
System.String

The user name.

password
System.String

The password for the user name.

Remarks

When calling the Authenticate(String, String) method, the strongest possible password-based authentication mechanism will be used from the SupportedAuthentications collection.

Method authenticates connected client with remote host. Connected client cannot be reauthenticated. You have to call Disconnect() first.

Exceptions
System.InvalidOperationException

Client is not connected or Client is already authenticated.

System.ArgumentException

Specified user name is null or Specified password is null.

System.NotSupportedException

Remote host doesn't support authentication.

Authenticate(String, String, SmtpAuthentication)

Authenticates client with specified user name, password or access token, and SmtpAuthentication mechanism.

public void Authenticate(string userName, string passwordOrToken, SmtpAuthentication authentication)
Public Sub Authenticate(userName As String, passwordOrToken As String, authentication As SmtpAuthentication)
Parameters
userName
System.String

The user name.

passwordOrToken
System.String

The password or access token for the user name.

authentication
SmtpAuthentication

A constant that specifies which authentication mechanism to use.

Remarks

Method authenticates connected client with remote host. Connected client cannot be reauthenticated. You have to call Disconnect() first.

Exceptions
System.InvalidOperationException

Client is not connected or Client is already authenticated.

System.ArgumentException

Specified authentication mechanism is not supported or Specified user name is null or Specified password or access token is null.

Connect()

Connects to the server.

public void Connect()
Public Sub Connect
Exceptions
System.InvalidOperationException

Using StartTls for the server which doesn't support it or Client is already connected.

System.TimeoutException

The server failed to respond in given time.

Connect(SslProtocols)

Connects to the server using specified SSL protocols.

public void Connect(SslProtocols sslProtocols)
Public Sub Connect(sslProtocols As SslProtocols)
Parameters
sslProtocols
System.Security.Authentication.SslProtocols
Remarks

The client connects to the server using the most secure protocol out of the specified protocols. This method is provided for .NET Framework 4.5 and older since they don’t support TLS 1.2 and greater by default. To specify them, use the following numeric values: 3072 for TLS 1.2, and 12288 for TLS 1.3.

Exceptions
System.InvalidOperationException

Using StartTls for the server which doesn't support it or Client is already connected.

System.TimeoutException

The server failed to respond in given time.

Disconnect()

Disconnects client from the server.

public void Disconnect()
Public Sub Disconnect

Dispose()

Disconnects client from the server and disposes all used resources.

public void Dispose()
Public Sub Dispose

KeepAlive()

Executes NOOP command.

public void KeepAlive()
Public Sub KeepAlive
Remarks

Executing NOOP command prevents server from terminating connection due to client inactivity.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

SendMessage(MailMessage)

Sends the message.

public void SendMessage(MailMessage message)
Public Sub SendMessage(message As MailMessage)
Parameters
message
MailMessage

The message.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

FreeLimitReachedException

Free license limitation exceeded.

Events

Terminated

Occurs when connection with server is terminated.

public event EventHandler<TerminatedEventArgs> Terminated
Public Event Terminated As EventHandler(Of TerminatedEventArgs)
Event Type
System.EventHandler<TerminatedEventArgs>
Remarks

This event is raised when connection with server is improperly terminated due to inactivity or some other reason. Client will close and dispose its internal stream so there is no need for calling Disconnect() method.

Implements

System.IDisposable

Examples