Class Pop3Client

Receives mail messages via POP3 (RFC 1939). One instance maintains a single connection. Not thread-safe; use one instance per thread.

Inheritance

object

Pop3Client

Implements

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Namespace: DRIT.Mail.Rfc.Pop3

Assembly: DRIT.Mail.dll

Syntax

public sealed class Pop3Client : IDisposable

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Constructors

Pop3Client(Pop3ClientOptions)

Initializes a new instance of the Pop3Client class with a real TCP transport.

Declaration

public Pop3Client(Pop3ClientOptions options)

Parameters

Type	Name	Description
Pop3ClientOptions	options	The client configuration.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Pop3Client(Pop3ClientOptions, ITextProtocolTransport)

Initializes a new instance of the Pop3Client class with a custom transport. Used for testing with an in-process transport.

Declaration

public Pop3Client(Pop3ClientOptions options, ITextProtocolTransport transport)

Parameters

Type	Name	Description
Pop3ClientOptions	options	The client configuration.
ITextProtocolTransport	transport	The transport to use.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Properties

Capabilities

Gets the server capabilities advertised in the CAPA response. Returns Empty before Connect() is called.

Declaration

public Pop3ServerCapabilities Capabilities { get; }

Property Value

Type	Description
Pop3ServerCapabilities

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

IsAuthenticated

Gets a value indicating whether the client has authenticated.

Declaration

public bool IsAuthenticated { get; }

Property Value

Type	Description
bool

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

IsConnected

Gets a value indicating whether the client is connected to the server.

Declaration

public bool IsConnected { get; }

Property Value

Type	Description
bool

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

IsEncrypted

Gets a value indicating whether the connection is encrypted (TLS).

Declaration

public bool IsEncrypted { get; }

Property Value

Type	Description
bool

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Methods

Authenticate()

Authenticates with the server using the credentials configured in Pop3ClientOptions.

Declaration

public void Authenticate()

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Exceptions

Type	Condition
Pop3AuthenticationException	Thrown if authentication fails or is refused.

Authenticate(SaslCredentials)

Authenticates with the specified credentials.

Declaration

public void Authenticate(SaslCredentials credentials)

Parameters

Type	Name	Description
SaslCredentials	credentials	The username/password credentials.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Authenticate(SaslOAuth2Token)

Authenticates with the specified OAuth 2.0 token.

Declaration

public void Authenticate(SaslOAuth2Token token)

Parameters

Type	Name	Description
SaslOAuth2Token	token	The OAuth 2.0 access token.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Connect()

Connects to the POP3 server, reads the greeting, and performs STLS or implicit TLS upgrade as configured.

Declaration

public void Connect()

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

DeleteMessage(int)

Marks a message as deleted (DELE, RFC 1939 §6). The deletion is committed when Disconnect() (QUIT) is called.

Declaration

public void DeleteMessage(int messageNumber)

Parameters

Type	Name	Description
int	messageNumber	The 1-based message number.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Disconnect()

Sends QUIT and closes the connection. Safe to call multiple times. QUIT commits any messages marked as deleted (DELE).

Declaration

public void Disconnect()

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Dispose()

Disposes the client, sending QUIT if still connected.

Declaration

public void Dispose()

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

GetMailboxStatus()

Gets the mailbox status (STAT, RFC 1939 §5).

Declaration

public Pop3MailboxStatus GetMailboxStatus()

Returns

Type	Description
Pop3MailboxStatus	The mailbox status with message count and total size.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

GetMessage(int)

Retrieves and parses a message (RETR + MimeReader).

Declaration

public MimeMessage GetMessage(int messageNumber)

Parameters

Type	Name	Description
int	messageNumber	The 1-based message number.

Returns

Type	Description
MimeMessage	The parsed MIME message.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

GetMessageHeaders(int)

Retrieves and parses message headers (TOP n 0).

Declaration

public MimeMessage GetMessageHeaders(int messageNumber)

Parameters

Type	Name	Description
int	messageNumber	The 1-based message number.

Returns

Type	Description
MimeMessage	The parsed MIME message (headers only).

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

GetMessageHeaders(int, int)

Retrieves message headers plus the first N lines of the body (TOP n lineCount, TOP extension).

Declaration

public string GetMessageHeaders(int messageNumber, int lineCount)

Parameters

Type	Name	Description
int	messageNumber	The 1-based message number.
int	lineCount	The number of body lines to retrieve. 0 = headers only.

Returns

Type	Description
string	The raw bytes of the headers and requested body lines.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

GetMessageRaw(int)

Retrieves a message as raw bytes (RETR, RFC 1939 §6). The bytes are de-dot-stuffed per RFC 1939 §3.

Declaration

public byte[] GetMessageRaw(int messageNumber)

Parameters

Type	Name	Description
int	messageNumber	The 1-based message number.

Returns

Type	Description
byte[]	The raw message bytes.

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

ListMessages()

Lists all messages with their sizes (LIST, RFC 1939 §5).

Declaration

public IReadOnlyList<Pop3MessageInfo> ListMessages()

Returns

Type	Description
IReadOnlyList<Pop3MessageInfo>	A list of message information (number and size).

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

ListMessagesWithUids()

Lists all messages with their UIDs (UIDL).

Declaration

public IReadOnlyList<Pop3MessageInfo> ListMessagesWithUids()

Returns

Type	Description
IReadOnlyList<Pop3MessageInfo>	A list of message information (number, size, and UID).

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Noop()

Sends a NOOP command to keep the connection alive.

Declaration

public void Noop()

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Reset()

Resets the mailbox — undeletes all messages marked as deleted (RSET, RFC 1939 §6).

Declaration

public void Reset()

Remarks

Connection lifecycle. A Pop3Client wraps a single TCP connection. Call Connect() to open it, Authenticate() to log in, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), operations connect automatically.

Timeouts. All read and write operations honor Timeout. A timeout throws Pop3TimeoutException and leaves the client disconnected.

Connection drops. If the server closes the connection unexpectedly (e.g. after an inactivity timeout or network interruption), the next read or write will throw Pop3ProtocolException or Pop3TimeoutException and the client will be left in the disconnected state. To recover, dispose the client and create a new one with Connect() + Authenticate(). POP3 has no stable message identifiers across sessions beyond UIDL; use ListMessagesWithUids() to map UIDs before and after reconnect.

Implements

IDisposable