PopClient Class

Namespace:
GemBox.Email.Pop
Assembly:
GemBox.Email.dll

Represents mail client that can be used for retrieving messages using Post Office Protocol (POP).

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

PopClient is implemented according to RFC 1939.

Constructors

PopClient(String)

Initializes new instance of PopClient class with specified host address.

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

The address of the server.

PopClient(String, ConnectionSecurity, Boolean)

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

public PopClient(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.

PopClient(String, Boolean)

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

public PopClient(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.

PopClient(String, Int32)

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

public PopClient(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.

PopClient(String, Int32, ConnectionSecurity)

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

public PopClient(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.

PopClient(String, Int32, ConnectionSecurity, RemoteCertificateValidationCallback)

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

public PopClient(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, PopAuthentication) 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.

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<PopAuthentication> SupportedAuthentications { get; }
Public ReadOnly Property SupportedAuthentications As ReadOnlyCollection(Of PopAuthentication)
Property Value
System.Collections.ObjectModel.ReadOnlyCollection<PopAuthentication>

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<PopCapability> SupportedCapabilities { get; }
Public ReadOnly Property SupportedCapabilities As ReadOnlyCollection(Of PopCapability)
Property Value
System.Collections.ObjectModel.ReadOnlyCollection<PopCapability>

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(Boolean) first.

Exceptions
System.InvalidOperationException

Client is not connected or Client is already authenticated.

System.ArgumentException

Specified user name is null or empty or Specified password is null or empty.

System.NotSupportedException

Remote host doesn't support authentication.

Authenticate(String, String, PopAuthentication)

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

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

The user name.

passwordOrToken
System.String

The password or access token for the user name.

authentication
PopAuthentication

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(Boolean) 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 empty or Specified password or access token is null or empty.

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.

DeleteMessage(Int32)

Deletes the specified message.

public void DeleteMessage(int messageNumber)
Public Sub DeleteMessage(messageNumber As Integer)
Parameters
messageNumber
System.Int32

The message number.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

DeleteMessage(String)

Deletes the specified message.

public void DeleteMessage(string uid)
Public Sub DeleteMessage(uid As String)
Parameters
uid
System.String

The message id.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

System.NotSupportedException

Server doesn't support UIDL capability.

System.ArgumentException

Message id is null or empty.

Disconnect(Boolean)

Disconnects client from the server.

public void Disconnect(bool update)
Public Sub Disconnect(update As Boolean)
Parameters
update
System.Boolean

True to update server state; otherwise, false.

Dispose()

Disconnects client from the server and disposes all used resources.

public void Dispose()
Public Sub Dispose
Remarks

Method disconnects from the server with update parameter set to true.

GetCount()

Gets the count of messages available on the server.

public int GetCount()
Public Function GetCount As Integer
Returns
System.Int32

The count of messages available on the server.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

GetHeaders(Int32)

Gets the headers for the specified message.

public HeaderCollection GetHeaders(int messageNumber)
Public Function GetHeaders(messageNumber As Integer) As HeaderCollection
Parameters
messageNumber
System.Int32

The message number.

Returns
HeaderCollection

A collection of message headers.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

System.NotSupportedException

Server doesn't support TOP capability.

GetHeaders(String)

Gets the headers for the specified message.

public HeaderCollection GetHeaders(string uid)
Public Function GetHeaders(uid As String) As HeaderCollection
Parameters
uid
System.String

The message id.

Returns
HeaderCollection

A collection of message headers.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

System.NotSupportedException

Server doesn't support UIDL capability. or Server doesn't support TOP capability.

System.ArgumentException

Message id is null or empty.

GetMessage(Int32)

Gets the specified message.

public MailMessage GetMessage(int messageNumber)
Public Function GetMessage(messageNumber As Integer) As MailMessage
Parameters
messageNumber
System.Int32

The message number.

Returns
MailMessage

The specified message.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

FreeLimitReachedException

Free license limitation exceeded.

GetMessage(String)

Gets the specified message.

public MailMessage GetMessage(string uid)
Public Function GetMessage(uid As String) As MailMessage
Parameters
uid
System.String

The message id.

Returns
MailMessage

The specified message.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

System.NotSupportedException

Server doesn't support UIDL capability.

System.ArgumentException

Message id is null or empty.

FreeLimitReachedException

Free license limitation exceeded.

GetSize()

Gets the size of all message available on the server.

public int GetSize()
Public Function GetSize As Integer
Returns
System.Int32

The size of all message available on the server.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

GetSizeLong()

Gets a 64-bit integer that represents the size of all message available on the server.

public long GetSizeLong()
Public Function GetSizeLong As Long
Returns
System.Int64

A 64-bit integer that represents size of all message available on the server.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

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.

ListMessages()

Lists all available messages on the server.

public ReadOnlyCollection<PopMessageInfo> ListMessages()
Public Function ListMessages As ReadOnlyCollection(Of PopMessageInfo)
Returns
System.Collections.ObjectModel.ReadOnlyCollection<PopMessageInfo>

A read-only collection of all available messages on the server.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

ListMessages(Boolean)

Lists all available messages on the server.

public ReadOnlyCollection<PopMessageInfo> ListMessages(bool includeUid)
Public Function ListMessages(includeUid As Boolean) As ReadOnlyCollection(Of PopMessageInfo)
Parameters
includeUid
System.Boolean

True to fetch message ids along with message numbers; otherwise, false.

Returns
System.Collections.ObjectModel.ReadOnlyCollection<PopMessageInfo>

A read-only collection of all available messages on the server.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

System.NotSupportedException

Server doesn't support UIDL capability.

SaveMessage(Int32, Stream)

Saves the specified message to a stream.

public void SaveMessage(int messageNumber, Stream output)
Public Sub SaveMessage(messageNumber As Integer, output As Stream)
Parameters
messageNumber
System.Int32

The message number.

output
System.IO.Stream

The stream to save the message to.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

FreeLimitReachedException

Free license limitation exceeded.

System.ArgumentException

Output stream is not writable.

System.ArgumentNullException

Output stream is null.

SaveMessage(Int32, String)

Saves the specified message to a file.

public void SaveMessage(int messageNumber, string filePath)
Public Sub SaveMessage(messageNumber As Integer, filePath As String)
Parameters
messageNumber
System.Int32

The message number.

filePath
System.String

A relative or absolute path for the file where message will be saved.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

FreeLimitReachedException

Free license limitation exceeded.

SaveMessage(String, Stream)

Saves the specified message to a stream.

public void SaveMessage(string uid, Stream output)
Public Sub SaveMessage(uid As String, output As Stream)
Parameters
uid
System.String

The message id.

output
System.IO.Stream

The stream to save the message to.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

System.NotSupportedException

Server doesn't support UIDL capability.

System.ArgumentException

Message id is null or empty. or Output stream is not writable.

System.ArgumentNullException

Output stream is null.

FreeLimitReachedException

Free license limitation exceeded.

SaveMessage(String, String)

Saves the specified message to a file.

public void SaveMessage(string uid, string filePath)
Public Sub SaveMessage(uid As String, filePath As String)
Parameters
uid
System.String

The message id.

filePath
System.String

A relative or absolute path for the file where message will be saved.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

System.NotSupportedException

Server doesn't support UIDL capability.

System.ArgumentException

Message id is null or empty.

FreeLimitReachedException

Free license limitation exceeded.

UndeleteMessages()

Undeletes all messages.

public void UndeleteMessages()
Public Sub UndeleteMessages
Remarks

Method undeletes all messages marked for deletion in current session. If connection is closed with update parameter set to true messages are deleted from the server permanently.

Exceptions
System.InvalidOperationException

Client is not connected or Server error.

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(Boolean) method.

Implements

System.IDisposable

Examples