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

SmtpClient Class

An SMTP client that can be used to send email messages.

Syntax

public class SmtpClient : MailKit.IMessageTransport, IDisposable

Remarks

The MailKit.Net.Smtp.SmtpClient class supports both the "smtp" and "smtps" protocols. The "smtp" protocol makes a clear-text connection to the SMTP server and does not use SSL or TLS unless the SMTP server supports the STARTTLS extension (as defined by rfc3207). The "smtps" protocol, however, connects to the SMTP server using an SSL-wrapped connection.

Requirements

Namespace: MailKit.Net.Smtp
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.Smtp.SmtpClient class.
Initializes a new instance of the MailKit.Net.Smtp.SmtpClient class.

Public Properties

[read-only]
AuthenticationMechanisms HashSet<string> . Gets the authentication mechanisms supported by the SMTP server.
Capabilities SmtpCapabilities . Gets the capabilities supported by the SMTP server.
ClientCertificates System.Security.Cryptography.X509Certificates.X509CertificateCollection . Gets or sets the client SSL certificates.
[read-only]
IsConnected bool . Gets whether or not the client is currently connected to an SMTP server.
[read-only]
MaxSize uint . Gets the maximum message size supported by the 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 SMTP server.
Connect (Uri, System.Threading.CancellationToken)
Establishes a connection to the specified SMTP server.
Disconnect (bool)
Disconnect the service.
Disconnect (bool, System.Threading.CancellationToken)
Disconnect the service.
Dispose ()
Releases all resource used by the MailKit.Net.Smtp.SmtpClient object.
Finalize ()
Releases unmanaged resources and performs other cleanup operations before the MailKit.Net.Smtp.SmtpClient is reclaimed by garbage collection.
NoOp ()
Pings the SMTP server to keep the connection alive.
NoOp (System.Threading.CancellationToken)
Pings the SMTP server to keep the connection alive.
Send (MimeKit.MimeMessage)
Send the specified message.
Send (MimeKit.MimeMessage, System.Threading.CancellationToken)
Send the specified message.
Send (MimeKit.MimeMessage, MimeKit.MailboxAddress, IEnumerable<MimeKit.MailboxAddress>)
Send the specified message using the supplied sender and recipients.
Send (MimeKit.MimeMessage, MimeKit.MailboxAddress, IEnumerable<MimeKit.MailboxAddress>, System.Threading.CancellationToken)
Send the specified message using the supplied sender and recipients.

Protected Methods

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

Member Details

SmtpClient Constructor

Initializes a new instance of the MailKit.Net.Smtp.SmtpClient class.

Syntax

public SmtpClient ()

Remarks

Before you can send messages with the MailKit.Net.Smtp.SmtpClient, you must first call the SmtpClient.Connect(Uri, System.Threading.CancellationToken) method. Depending on the server, you may also need to authenticate using the SmtpClient.Authenticate(System.Net.ICredentials, System.Threading.CancellationToken) method.

Requirements

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

SmtpClient Constructor

Initializes a new instance of the MailKit.Net.Smtp.SmtpClient class.

Syntax

public SmtpClient (MailKit.IProtocolLogger protocolLogger)

Parameters

protocolLogger
The protocol logger.

Exceptions

Type Reason
ArgumentNullException protocolLogger is null.

Remarks

Before you can send messages with the MailKit.Net.Smtp.SmtpClient, you must first call the SmtpClient.Connect(Uri, System.Threading.CancellationToken) method. Depending on the server, you may also need to authenticate using the SmtpClient.Authenticate(System.Net.ICredentials, System.Threading.CancellationToken) method.

Requirements

Namespace: MailKit.Net.Smtp
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.
InvalidOperationException The MailKit.Net.Smtp.SmtpClient is not connected or is already authenticated.
NotSupportedException The SMTP server does not support authentication.
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.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol error occurred.

Remarks

If the SMTP server supports authentication, 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, on the other hand, authentication is not supported, then this method simply returns without attempting to authenticate.

Requirements

Namespace: MailKit.Net.Smtp
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.
InvalidOperationException The MailKit.Net.Smtp.SmtpClient is not connected or is already authenticated.
NotSupportedException The SMTP server does not support authentication.
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.Smtp.SmtpException An SMTP protocol error occurred.
MailKit.Net.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol error occurred.
MailKit.Security.AuthenticationException Authentication using the supplied credentials has failed.

Remarks

If the SMTP server supports authentication, 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, on the other hand, authentication is not supported, then this method simply returns without attempting to authenticate.

Requirements

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

AuthenticationMechanisms Property

Gets the authentication mechanisms supported by the SMTP server.

Syntax

public HashSet<string> AuthenticationMechanisms { get; }

Value

The authentication mechanisms.

Remarks

The authentication mechanisms are queried durring the SmtpClient.Connect(Uri, System.Threading.CancellationToken) method.

Requirements

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

Capabilities Property

Gets the capabilities supported by the SMTP server.

Syntax

public SmtpCapabilities 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 SmtpClient.Connect(Uri, System.Threading.CancellationToken) method and may change as a side-effect of the SmtpClient.Authenticate(System.Net.ICredentials, System.Threading.CancellationToken) method.

Requirements

Namespace: MailKit.Net.Smtp
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 SmtpClient.Connect(Uri, System.Threading.CancellationToken).

Requirements

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

Connect Method

Establishes a connection to the specified SMTP server.

Syntax

public void Connect (Uri uri)

Parameters

uri
The server URI. The Uri.Scheme should either be "smtp" to make a clear-text connection or "smtps" 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.Smtp.SmtpClient has been disposed.
InvalidOperationException The MailKit.Net.Smtp.SmtpClient is already connected.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpCommandException An SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol error occurred.

Remarks

Establishes a connection to an SMTP or SMTP/S server. If the schema in the uri is "smtp", a clear-text connection is made and defaults to using port 25 if no port is specified in the URI. However, if the schema in the uri is "smtps", an SSL connection is made using the SmtpClient.ClientCertificates and defaults to port 465 unless a port is specified in the URI.

It should be noted that when using a clear-text SMTP 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 a successful connection is made, the SmtpClient.AuthenticationMechanisms and SmtpClient.Capabilities properties will be populated.

Requirements

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

Connect Method

Establishes a connection to the specified SMTP server.

Syntax

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

Parameters

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

Exceptions

Type Reason
ArgumentNullException The uri is null.
ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.
OperationCanceledException The operation was canceled.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpException An SMTP protocol error occurred.
InvalidOperationException The MailKit.Net.Smtp.SmtpClient is already connected.
MailKit.Net.Smtp.SmtpCommandException An SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol error occurred.
ArgumentException The uri is not an absolute URI.

Remarks

Establishes a connection to an SMTP or SMTP/S server. If the schema in the uri is "smtp", a clear-text connection is made and defaults to using port 25 if no port is specified in the URI. However, if the schema in the uri is "smtps", an SSL connection is made using the SmtpClient.ClientCertificates and defaults to port 465 unless a port is specified in the URI.

It should be noted that when using a clear-text SMTP 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 a successful connection is made, the SmtpClient.AuthenticationMechanisms and SmtpClient.Capabilities properties will be populated.

Requirements

Namespace: MailKit.Net.Smtp
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 "QUIT" command will be issued in order to disconnect cleanly.

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.

Remarks

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

Requirements

Namespace: MailKit.Net.Smtp
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 "QUIT" command will be issued in order to disconnect cleanly.
cancellationToken
A cancellation token.

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.
OperationCanceledException The operation was canceled.

Remarks

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

Requirements

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

Dispose Method

Releases all resource used by the MailKit.Net.Smtp.SmtpClient object.

Syntax

public void Dispose ()

Remarks

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

Requirements

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

Dispose Method

Releases the unmanaged resources used by the MailKit.Net.Smtp.SmtpClient 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.Smtp
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.Smtp.SmtpClient is reclaimed by garbage collection.

Syntax

void Finalize ()

Remarks

Documentation for this section has not yet been entered.

Requirements

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

IsConnected Property

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

Syntax

public bool IsConnected { get; }

Value

true if the client is connected; otherwise, false.

Remarks

When a MailKit.Net.Smtp.SmtpProtocolException is caught, the connection state of the MailKit.Net.Smtp.SmtpClient should be checked before continuing.

Requirements

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

MaxSize Property

Gets the maximum message size supported by the server.

Syntax

public uint MaxSize { get; }

Value

The maximum message size supported by the server.

Remarks

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

Note: This value is only relevant if the SmtpClient.Capabilities includes the SmtpCapabilities.Size flag.

Requirements

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

NoOp Method

Pings the SMTP server to keep the connection alive.

Syntax

public void NoOp ()

Exceptions

Type Reason
ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.
InvalidOperationException The MailKit.Net.Smtp.SmtpClient is not connected.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol error occurred.

Remarks

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

Requirements

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

NoOp Method

Pings the SMTP 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.Smtp.SmtpClient has been disposed.
InvalidOperationException The MailKit.Net.Smtp.SmtpClient is not connected.
OperationCanceledException The operation was canceled.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpException The SMTP server returned an unexpected status code.
MailKit.Net.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol error occurred.

Remarks

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

Requirements

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

Send Method

Send the specified message.

Syntax

public void Send (MimeKit.MimeMessage message)

Parameters

message
The message.

Exceptions

Type Reason
ArgumentNullException message is null.
ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.
InvalidOperationException

The MailKit.Net.Smtp.SmtpClient is not connected.

-or-

A sender has not been specified.

-or-

No recipients have been specified.

UnauthorizedAccessException Authentication is required before sending a message.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol exception occurred.

Remarks

Sends the message by uploading it to an SMTP server.

Requirements

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

Send Method

Send the specified message.

Syntax

public void Send (MimeKit.MimeMessage message, System.Threading.CancellationToken cancellationToken)

Parameters

message
The message.
cancellationToken
A cancellation token.

Exceptions

Type Reason
ArgumentNullException message is null.
ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.
InvalidOperationException

The MailKit.Net.Smtp.SmtpClient is not connected.

-or-

A sender has not been specified.

-or-

No recipients have been specified.

OperationCanceledException The operation has been canceled.
UnauthorizedAccessException Authentication is required before sending a message.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpException An SMTP protocol exception occurred.
MailKit.Net.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol exception occurred.

Remarks

Sends the message by uploading it to an SMTP server.

Requirements

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

Send Method

Send the specified message using the supplied sender and recipients.

Syntax

Parameters

message
The message.
sender
The mailbox address to use for sending the message.
recipients
The mailbox addresses that should receive the message.

Exceptions

Type Reason
ArgumentNullException

message is null.

-or-

sender is null.

-or-

recipients is null.

ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.
InvalidOperationException

The MailKit.Net.Smtp.SmtpClient is not connected.

-or-

A sender has not been specified.

-or-

No recipients have been specified.

UnauthorizedAccessException Authentication is required before sending a message.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol exception occurred.

Remarks

Sends the message by uploading it to an SMTP server using the supplied sender and recipients.

Requirements

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

Send Method

Send the specified message using the supplied sender and recipients.

Syntax

Parameters

message
The message.
sender
The mailbox address to use for sending the message.
recipients
The mailbox addresses that should receive the message.
cancellationToken
A cancellation token.

Exceptions

Type Reason
ArgumentNullException

message is null.

-or-

sender is null.

-or-

recipients is null.

ObjectDisposedException The MailKit.Net.Smtp.SmtpClient has been disposed.
InvalidOperationException

The MailKit.Net.Smtp.SmtpClient is not connected.

-or-

A sender has not been specified.

-or-

No recipients have been specified.

OperationCanceledException The operation has been canceled.
UnauthorizedAccessException Authentication is required before sending a message.
System.IO.IOException An I/O error occurred.
MailKit.Net.Smtp.SmtpCommandException The SMTP command failed.
MailKit.Net.Smtp.SmtpProtocolException An SMTP protocol exception occurred.

Remarks

Sends the message by uploading it to an SMTP server using the supplied sender and recipients.

Requirements

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