View on GitHub

MailKit

MailKit: A cross-platform .NET mail-client library optimized for mobile.

Download this project as a .zip file Download this project as a tar.gz file

ImapClient Class

An IMAP client that can be used to retrieve messages from a server.

Syntax

public class ImapClient : MailKit.IMessageStore, IDisposable

Remarks

The MailKit.Net.Imap.ImapClient class supports both the "imap" and "imaps" protocols. The "imap" protocol makes a clear-text connection to the IMAP server and does not use SSL or TLS unless the IMAP server supports the STARTTLS extension (as defined by rfc3501). The "imaps" protocol, however, connects to the IMAP server using an SSL-wrapped connection.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Members

See Also: Inherited members from object.

Public Constructors

Initializes a new instance of the MailKit.Net.Imap.ImapClient class.
Initializes a new instance of the MailKit.Net.Imap.ImapClient class.

Public Properties

[read-only]
AuthenticationMechanisms HashSet<string> . Gets the authentication mechanisms supported by the IMAP server.
Capabilities ImapCapabilities . Gets the capabilities supported by the IMAP server.
ClientCertificates System.Security.Cryptography.X509Certificates.X509CertificateCollection . Gets or sets the client SSL certificates.
[read-only]
Inbox MailKit.IFolder . Gets the Inbox folder.
[read-only]
IsConnected bool . Gets whether or not the client is currently connected to an IMAP server.
[read-only]
OtherNamespaces MailKit.FolderNamespaceCollection . Gets the other namespaces.
[read-only]
PersonalNamespaces MailKit.FolderNamespaceCollection . Gets the personal namespaces.
[read-only]
SharedNamespaces MailKit.FolderNamespaceCollection . Gets the shared namespaces.
[read-only]
ThreadingAlgorithms HashSet<MailKit.ThreadingAlgorithm> . Gets the threading algorithms supported by the IMAP server.

Public Methods

Authenticate (System.Net.ICredentials)
Authenticates using the supplied credentials.
Authenticate (System.Net.ICredentials, System.Threading.CancellationToken)
Authenticates using the supplied credentials.
Connect (Uri)
Establishes a connection to the specified IMAP server.
Connect (Uri, System.Threading.CancellationToken)
Establishes a connection to the specified IMAP server.
Disconnect (bool)
Disconnect the service.
Disconnect (bool, System.Threading.CancellationToken)
Disconnect the service.
Dispose ()
Releases all resource used by the MailKit.Net.Imap.ImapClient object.
EnableQuickResync ()
Enables the QRESYNC feature.
EnableQuickResync (System.Threading.CancellationToken)
Enables the QRESYNC feature.
Finalize ()
Releases unmanaged resources and performs other cleanup operations before the MailKit.Net.Imap.ImapClient is reclaimed by garbage collection.
GetFolder (MailKit.FolderNamespace) : MailKit.IFolder
Gets the folder for the specified namespace.
GetFolder (MailKit.SpecialFolder) : MailKit.IFolder
Gets the specified special folder.
GetFolder (string) : MailKit.IFolder
Gets the folder for the specified path.
GetFolder (string, System.Threading.CancellationToken) : MailKit.IFolder
Gets the folder for the specified path.
NoOp ()
Pings the IMAP server to keep the connection alive.
NoOp (System.Threading.CancellationToken)
Pings the IMAP server to keep the connection alive.

Protected Methods

Dispose (bool)
Releases the unmanaged resources used by the MailKit.Net.Imap.ImapClient and optionally releases the managed resources.

Public Events

Alert Occurs when a remote message store receives an alert message from the server.

Member Details

ImapClient Constructor

Initializes a new instance of the MailKit.Net.Imap.ImapClient class.

Syntax

public ImapClient ()

Remarks

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

ImapClient Constructor

Initializes a new instance of the MailKit.Net.Imap.ImapClient class.

Syntax

public ImapClient (MailKit.IProtocolLogger protocolLogger)

Parameters

protocolLogger
The protocol logger.

Exceptions

Type Reason
ArgumentNullException protocolLogger is null.

Remarks

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Alert Event

Occurs when a remote message store receives an alert message from the server.

Syntax

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Authenticate Method

Authenticates using the supplied credentials.

Syntax

public void Authenticate (System.Net.ICredentials credentials)

Parameters

credentials
The user's credentials.

Exceptions

Type Reason
ArgumentNullException credentials is null.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException The MailKit.Net.Imap.ImapClient is not connected or is already authenticated.
MailKit.Security.AuthenticationException Authentication using the supplied credentials has failed.
MailKit.Security.SaslException A SASL authentication error occurred.
System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapProtocolException An IMAP protocol error occurred.

Remarks

If the server supports one or more SASL authentication mechanisms, then the SASL mechanisms that both the client and server support are tried in order of greatest security to weakest security. Once a SASL authentication mechanism is found that both client and server support, the credentials are used to authenticate.

If the server does not support SASL or if no common SASL mechanisms can be found, then LOGIN command is used as a fallback.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Authenticate Method

Authenticates using the supplied credentials.

Syntax

public void Authenticate (System.Net.ICredentials credentials, System.Threading.CancellationToken cancellationToken)

Parameters

credentials
The user's credentials.
cancellationToken
A cancellation token.

Exceptions

Type Reason
ArgumentNullException credentials is null.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException The MailKit.Net.Imap.ImapClient is not connected or is already authenticated.
OperationCanceledException The operation was canceled via the cancellation token.
System.Security.Authentication.AuthenticationException Authentication using the supplied credentials has failed.
MailKit.Security.SaslException A SASL authentication error occurred.
System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapProtocolException An IMAP protocol error occurred.
MailKit.Security.AuthenticationException Authentication using the supplied credentials has failed.

Remarks

If the server supports one or more SASL authentication mechanisms, then the SASL mechanisms that both the client and server support are tried in order of greatest security to weakest security. Once a SASL authentication mechanism is found that both client and server support, the credentials are used to authenticate.

If the server does not support SASL or if no common SASL mechanisms can be found, then LOGIN command is used as a fallback.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

AuthenticationMechanisms Property

Gets the authentication mechanisms supported by the IMAP server.

Syntax

public HashSet<string> AuthenticationMechanisms { get; }

Value

The authentication mechanisms.

Remarks

The authentication mechanisms are queried as part of the ImapClient.Connect(Uri, System.Threading.CancellationToken) method.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Capabilities Property

Gets the capabilities supported by the IMAP server.

Syntax

public ImapCapabilities Capabilities { get; set; }

Value

The capabilities.

Exceptions

Type Reason
ArgumentException Capabilities cannot be enabled, they may only be disabled.

Remarks

The capabilities will not be known until a successful connection has been made via the ImapClient.Connect(Uri, System.Threading.CancellationToken) method and may change as a side-effect of the ImapClient.Authenticate(System.Net.ICredentials, System.Threading.CancellationToken) method.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

ClientCertificates Property

Gets or sets the client SSL certificates.

Syntax

Value

The client SSL certificates.

Remarks

Some servers may require the client SSL certificates in order to allow the user to connect.

This property should be set before calling ImapClient.Connect(Uri, System.Threading.CancellationToken).

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Connect Method

Establishes a connection to the specified IMAP server.

Syntax

public void Connect (Uri uri)

Parameters

uri
The server URI. The Uri.Scheme should either be "imap" to make a clear-text connection or "imaps" to make an SSL connection.

Exceptions

Type Reason
ArgumentNullException The uri is null.
ArgumentException The uri is not an absolute URI.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException The MailKit.Net.Imap.ImapClient is already connected.
System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapProtocolException An IMAP protocol error occurred.

Remarks

Establishes a connection to an IMAP or IMAP/S server. If the schema in the uri is "imap", a clear-text connection is made and defaults to using port 143 if no port is specified in the URI. However, if the schema in the uri is "imaps", an SSL connection is made using the ImapClient.ClientCertificates and defaults to port 993 unless a port is specified in the URI.

It should be noted that when using a clear-text IMAP connection, if the server advertizes support for the STARTTLS extension, the client will automatically switch into TLS mode before authenticating unless the uri contains a query string to disable it.

If the IMAP server advertizes the COMPRESS extension and either does not support the STARTTLS extension or the uri explicitly disabled the use of the STARTTLS extension, then the client will automatically opt into using a compressed data connection to optimize bandwidth usage unless the uri contains a query string to explicitly disable it.

If a successful connection is made, the ImapClient.AuthenticationMechanisms and ImapClient.Capabilities properties will be populated.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Connect Method

Establishes a connection to the specified IMAP server.

Syntax

public void Connect (Uri uri, System.Threading.CancellationToken cancellationToken)

Parameters

uri
The server URI. The Uri.Scheme should either be "imap" to make a clear-text connection or "imaps" to make an SSL connection.
cancellationToken
A cancellation token.

Exceptions

Type Reason
ArgumentNullException The uri is null.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException The MailKit.Net.Imap.ImapClient is already connected.
OperationCanceledException The operation was canceled via the cancellation token.
System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapProtocolException An IMAP protocol error occurred.
ArgumentException The uri is not an absolute URI.

Remarks

Establishes a connection to an IMAP or IMAP/S server. If the schema in the uri is "imap", a clear-text connection is made and defaults to using port 143 if no port is specified in the URI. However, if the schema in the uri is "imaps", an SSL connection is made using the ImapClient.ClientCertificates and defaults to port 993 unless a port is specified in the URI.

It should be noted that when using a clear-text IMAP connection, if the server advertizes support for the STARTTLS extension, the client will automatically switch into TLS mode before authenticating unless the uri contains a query string to disable it.

If the IMAP server advertizes the COMPRESS extension and either does not support the STARTTLS extension or the uri explicitly disabled the use of the STARTTLS extension, then the client will automatically opt into using a compressed data connection to optimize bandwidth usage unless the uri contains a query string to explicitly disable it.

If a successful connection is made, the ImapClient.AuthenticationMechanisms and ImapClient.Capabilities properties will be populated.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Disconnect Method

Disconnect the service.

Syntax

public void Disconnect (bool quit)

Parameters

quit
If set to true, a "LOGOUT" command will be issued in order to disconnect cleanly.

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.

Remarks

If quit is true, a "LOGOUT" command will be issued in order to disconnect cleanly.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Disconnect Method

Disconnect the service.

Syntax

public void Disconnect (bool quit, System.Threading.CancellationToken cancellationToken)

Parameters

quit
If set to true, a "LOGOUT" command will be issued in order to disconnect cleanly.
cancellationToken
A cancellation token.

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.

Remarks

If quit is true, a "LOGOUT" command will be issued in order to disconnect cleanly.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Dispose Method

Releases all resource used by the MailKit.Net.Imap.ImapClient object.

Syntax

public void Dispose ()

Remarks

Call ImapClient.Dispose when you are finished using the MailKit.Net.Imap.ImapClient. The ImapClient.Dispose method leaves the MailKit.Net.Imap.ImapClient in an unusable state. After calling ImapClient.Dispose, you must release all references to the MailKit.Net.Imap.ImapClient so the garbage collector can reclaim the memory that the MailKit.Net.Imap.ImapClient was occupying.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Dispose Method

Releases the unmanaged resources used by the MailKit.Net.Imap.ImapClient and optionally releases the managed resources.

Syntax

protected virtual void Dispose (bool disposing)

Parameters

disposing
true to release both managed and unmanaged resources; false to release only the unmanaged resources.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

EnableQuickResync Method

Enables the QRESYNC feature.

Syntax

public void EnableQuickResync ()

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException The MailKit.Net.Imap.ImapClient is not connected, not authenticated, or a folder has been selected.
NotSupportedException The IMAP server does not support the QRESYNC extension.
System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapProtocolException An IMAP protocol error occurred.

Remarks

The QRESYNC extension improves resynchronization performance of folders by querying the IMAP server for a list of changes when the folder is opened using the ImapFolder.Open(MailKit.FolderAccess, MailKit.UniqueId, ulong, MailKit.UniqueId[], System.Threading.CancellationToken) method.

If this feature is enabled, the ImapFolder.Expunged event is replaced with the ImapFolder.Vanished event.

This method needs to be called immediately after ImapClient.Authenticate(System.Net.ICredentials, System.Threading.CancellationToken), before the opening of any folders.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

EnableQuickResync Method

Enables the QRESYNC feature.

Syntax

public void EnableQuickResync (System.Threading.CancellationToken cancellationToken)

Parameters

cancellationToken
Cancellation token.

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException The MailKit.Net.Imap.ImapClient is not connected, not authenticated, or a folder has been selected.
NotSupportedException The IMAP server does not support the QRESYNC extension.
OperationCanceledException The operation was canceled via the cancellation token.
System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapProtocolException An IMAP protocol error occurred.

Remarks

The QRESYNC extension improves resynchronization performance of folders by querying the IMAP server for a list of changes when the folder is opened using the ImapFolder.Open(MailKit.FolderAccess, MailKit.UniqueId, ulong, MailKit.UniqueId[], System.Threading.CancellationToken) method.

If this feature is enabled, the ImapFolder.Expunged event is replaced with the ImapFolder.Vanished event.

This method needs to be called immediately after ImapClient.Authenticate(System.Net.ICredentials, System.Threading.CancellationToken), before the opening of any folders.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Finalize Method

Releases unmanaged resources and performs other cleanup operations before the MailKit.Net.Imap.ImapClient is reclaimed by garbage collection.

Syntax

void Finalize ()

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

GetFolder Method

Gets the folder for the specified namespace.

Syntax

public MailKit.IFolder GetFolder (MailKit.FolderNamespace namespace)

Parameters

namespace
The namespace.

Returns

The folder.

Exceptions

Type Reason
ArgumentNullException namespace is null.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException

The MailKit.Net.Imap.ImapClient is not connected.

-or-

The MailKit.Net.Imap.ImapClient is not authenticated.

MailKit.FolderNotFoundException The folder could not be found.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

GetFolder Method

Gets the specified special folder.

Syntax

public MailKit.IFolder GetFolder (MailKit.SpecialFolder folder)

Parameters

folder
The type of special folder.

Returns

The folder if available; otherwise null.

Exceptions

Type Reason
ArgumentOutOfRangeException folder is out of range.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException

The MailKit.Net.Imap.ImapClient is not connected.

-or-

The MailKit.Net.Imap.ImapClient is not authenticated.

Remarks

Not all IMAP servers support special folders. Only IMAP servers supporting the ImapCapabilities.SpecialUse or ImapCapabilities.XList extensions may have special folders.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

GetFolder Method

Gets the folder for the specified path.

Syntax

public MailKit.IFolder GetFolder (string path)

Parameters

path
The folder path.

Returns

The folder.

Exceptions

Type Reason
ArgumentNullException path is null.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException

The MailKit.Net.Imap.ImapClient is not connected.

-or-

The MailKit.Net.Imap.ImapClient is not authenticated.

MailKit.FolderNotFoundException The folder could not be found.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

GetFolder Method

Gets the folder for the specified path.

Syntax

public MailKit.IFolder GetFolder (string path, System.Threading.CancellationToken cancellationToken)

Parameters

path
The folder path.
cancellationToken
The cancellation token.

Returns

The folder.

Exceptions

Type Reason
ArgumentNullException path is null.
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException

The MailKit.Net.Imap.ImapClient is not connected.

-or-

The MailKit.Net.Imap.ImapClient is not authenticated.

MailKit.FolderNotFoundException The folder could not be found.
OperationCanceledException The operation was canceled via the cancellation token.

Remarks

Documentation for this section has not yet been entered.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

Inbox Property

Gets the Inbox folder.

Syntax

public MailKit.IFolder Inbox { get; }

Value

The Inbox folder.

Remarks

The Inbox folder is the default folder and always exists.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

IsConnected Property

Gets whether or not the client is currently connected to an IMAP server.

Syntax

public bool IsConnected { get; }

Value

true if the client is connected; otherwise, false.

Remarks

When an MailKit.Net.Imap.ImapProtocolException is caught, the connection state of the MailKit.Net.Imap.ImapClient should be checked before continuing.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

NoOp Method

Pings the IMAP server to keep the connection alive.

Syntax

public void NoOp ()

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException

The MailKit.Net.Imap.ImapClient is not connected.

-or-

The MailKit.Net.Imap.ImapClient is not authenticated.

System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapCommandException The server replied to the NOOP command with a NO or BAD response.
MailKit.Net.Imap.ImapProtocolException The server responded with an unexpected token.

Remarks

Mail servers, if left idle for too long, will automatically drop the connection.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

NoOp Method

Pings the IMAP server to keep the connection alive.

Syntax

public void NoOp (System.Threading.CancellationToken cancellationToken)

Parameters

cancellationToken
A cancellation token.

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Imap.ImapClient has been disposed.
InvalidOperationException

The MailKit.Net.Imap.ImapClient is not connected.

-or-

The MailKit.Net.Imap.ImapClient is not authenticated.

OperationCanceledException The operation was canceled via the cancellation token.
System.IO.IOException An I/O error occurred.
MailKit.Net.Imap.ImapCommandException The server replied to the NOOP command with a NO or BAD response.
MailKit.Net.Imap.ImapProtocolException The server responded with an unexpected token.

Remarks

Mail servers, if left idle for too long, will automatically drop the connection.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

OtherNamespaces Property

Gets the other namespaces.

Syntax

public MailKit.FolderNamespaceCollection OtherNamespaces { get; }

Value

The other namespaces.

Remarks

The other folder namespaces contain other mailbox folders.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

PersonalNamespaces Property

Gets the personal namespaces.

Syntax

public MailKit.FolderNamespaceCollection PersonalNamespaces { get; }

Value

The personal namespaces.

Remarks

The personal folder namespaces contain a user's personal mailbox folders.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

SharedNamespaces Property

Gets the shared namespaces.

Syntax

public MailKit.FolderNamespaceCollection SharedNamespaces { get; }

Value

The shared namespaces.

Remarks

The shared folder namespaces contain mailbox folders that are shared with the user.

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0

ThreadingAlgorithms Property

Gets the threading algorithms supported by the IMAP server.

Syntax

public HashSet<MailKit.ThreadingAlgorithm> ThreadingAlgorithms { get; }

Value

The authentication mechanisms.

Remarks

Requirements

Namespace: MailKit.Net.Imap
Assembly: MailKit (in MailKit.dll)
Assembly Versions: 0.11.0.0