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.MailTransport

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.26.0.0

Members

See Also: Inherited members from MailKit.MailTransport.

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]
override
AuthenticationMechanisms HashSet<string> . Get the authentication mechanisms supported by the SMTP server.
[read-only]
abstract
AuthenticationMechanisms HashSet<string> . Gets the authentication mechanisms supported by the mail server. (Inherited from MailKit.MailService.)
Capabilities SmtpCapabilities . Get the capabilities supported by the SMTP server.
ClientCertificates System.Security.Cryptography.X509Certificates.X509CertificateCollection . Gets or sets the client SSL certificates. (Inherited from MailKit.MailService.)
[read-only]
override
IsConnected bool . Get whether or not the client is currently connected to an SMTP server.
[read-only]
abstract
IsConnected bool . Gets whether or not the client is currently connected to an mail server. (Inherited from MailKit.MailService.)
LocalDomain string . Gets or sets the local domain.
[read-only]
MaxSize uint . Get the maximum message size supported by the server.
[read-only]
override
SyncRoot object . Gets an object that can be used to synchronize access to the folder.
[read-only]
abstract
SyncRoot object . Gets an object that can be used to synchronize access to the folder. (Inherited from MailKit.MailService.)
override
Timeout int . Get or set the timeout for network streaming operations, in milliseconds.
abstract
Timeout int . Gets or sets the timeout for network streaming operations, in milliseconds. (Inherited from MailKit.MailService.)

Protected Properties

[read-only]
override
Protocol string . Get the protocol supported by the message service.
[read-only]
abstract
Protocol string . Gets the protocol supported by the message service. (Inherited from MailKit.MailService.)

Public Methods

override
Authenticate (System.Net.ICredentials, System.Threading.CancellationToken)
Authenticates using the supplied credentials.
abstract
Authenticate (System.Net.ICredentials, System.Threading.CancellationToken)
Authenticates using the supplied credentials. (Inherited from MailKit.MailService.)
Authenticate (string, string, System.Threading.CancellationToken)
Authenticates using the specified user name and password. (Inherited from MailKit.MailService.)
AuthenticateAsync (System.Net.ICredentials, System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously authenticates using the supplied credentials. (Inherited from MailKit.MailService.)
AuthenticateAsync (string, string, System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously authenticates using the specified user name and password. (Inherited from MailKit.MailService.)
override
Connect (Uri, System.Threading.CancellationToken)
Establishes a connection to the specified SMTP server.
abstract
Connect (Uri, System.Threading.CancellationToken)
Establishes a connection to the specified mail server. (Inherited from MailKit.MailService.)
Connect (string, int, bool, System.Threading.CancellationToken)
Establishes a connection to the specified mail server. (Inherited from MailKit.MailService.)
ConnectAsync (Uri, System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously establishes a connection to the specified mail server. (Inherited from MailKit.MailService.)
ConnectAsync (string, int, bool, System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously establishes a connection to the specified mail server. (Inherited from MailKit.MailService.)
override
Disconnect (bool, System.Threading.CancellationToken)
Disconnect the service.
abstract
Disconnect (bool, System.Threading.CancellationToken)
Disconnects the service. (Inherited from MailKit.MailService.)
DisconnectAsync (bool, System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously disconnects the service. (Inherited from MailKit.MailService.)
Dispose ()
Releases all resource used by the MailKit.MailService object. (Inherited from MailKit.MailService.)
Finalize ()
Releases unmanaged resources and performs other cleanup operations before the MailKit.MailService is reclaimed by garbage collection. (Inherited from MailKit.MailService.)
override
NoOp (System.Threading.CancellationToken)
Ping the SMTP server to keep the connection alive.
abstract
NoOp (System.Threading.CancellationToken)
Pings the mail server to keep the connection alive. (Inherited from MailKit.MailService.)
NoOpAsync (System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously pings the mail server to keep the connection alive. (Inherited from MailKit.MailService.)
override
Send (MimeKit.MimeMessage, System.Threading.CancellationToken)
Send the specified message.
abstract
Send (MimeKit.MimeMessage, System.Threading.CancellationToken)
Sends the specified message. (Inherited from MailKit.MailTransport.)
override
Send (MimeKit.MimeMessage, MimeKit.MailboxAddress, IEnumerable<MimeKit.MailboxAddress>, System.Threading.CancellationToken)
Send the specified message using the supplied sender and recipients.
abstract
Send (MimeKit.MimeMessage, MimeKit.MailboxAddress, IEnumerable<MimeKit.MailboxAddress>, System.Threading.CancellationToken)
Sends the specified message using the supplied sender and recipients. (Inherited from MailKit.MailTransport.)
SendAsync (MimeKit.MimeMessage, System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously sends the specified message. (Inherited from MailKit.MailTransport.)
SendAsync (MimeKit.MimeMessage, MimeKit.MailboxAddress, IEnumerable<MimeKit.MailboxAddress>, System.Threading.CancellationToken) : System.Threading.Tasks.Task
Asynchronously sends the specified message using the supplied sender and recipients. (Inherited from MailKit.MailTransport.)

Protected Methods

override
Dispose (bool)
Releases the unmanaged resources used by the MailKit.Net.Smtp.SmtpClient and optionally releases the managed resources.
Dispose (bool)
Releases the unmanaged resources used by the MailKit.MailService and optionally releases the managed resources. (Inherited from MailKit.MailService.)
OnAuthenticated (string)
Raise the authenticated event. (Inherited from MailKit.MailService.)
OnConnected ()
Raise the connected event. (Inherited from MailKit.MailService.)
OnDisconnected ()
Raise the disconnected event. (Inherited from MailKit.MailService.)

Public Events

Authenticated Occurs when the client has been successfully authenticated. (Inherited from MailKit.MailService.)
Connected Occurs when the client has been successfully connected. (Inherited from MailKit.MailService.)
Disconnected Occurs when the client gets disconnected. (Inherited from MailKit.MailService.)

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.26.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.26.0.0

Authenticate Method

Authenticates using the supplied credentials.

Syntax

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

Parameters

credentials
The user's credentials.
cancellationToken
The 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.26.0.0

AuthenticationMechanisms Property

Get the authentication mechanisms supported by the SMTP server.

Syntax

public override 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.26.0.0

Capabilities Property

Get 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.26.0.0

Connect Method

Establishes a connection to the specified SMTP server.

Syntax

public override 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
The 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 MailKit.MailService.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.26.0.0

Disconnect Method

Disconnect the service.

Syntax

public override 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
The 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.26.0.0

Dispose Method

Releases the unmanaged resources used by the MailKit.Net.Smtp.SmtpClient and optionally releases the managed resources.

Syntax

protected override void Dispose (bool disposing)

Parameters

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

Remarks

Releases the unmanaged resources used by the MailKit.Net.Smtp.SmtpClient and optionally releases the managed resources.

Requirements

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

IsConnected Property

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

Syntax

public override 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.26.0.0

LocalDomain Property

Gets or sets the local domain.

Syntax

public string LocalDomain { get; set; }

Value

The local domain.

Remarks

The local domain is used in the HELO or EHLO commands sent to the SMTP server. If left unset, the local IP address will be used instead.

Requirements

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

MaxSize Property

Get 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.26.0.0

NoOp Method

Ping the SMTP server to keep the connection alive.

Syntax

public override void NoOp (System.Threading.CancellationToken cancellationToken)

Parameters

cancellationToken
The 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.26.0.0

Protocol Property

Get the protocol supported by the message service.

Syntax

protected override string Protocol { get; }

Value

The protocol.

Remarks

Gets the protocol supported by the message service.

Requirements

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

Send Method

Send the specified message.

Syntax

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

Parameters

message
The message.
cancellationToken
The 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.26.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
The 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.26.0.0

SyncRoot Property

Gets an object that can be used to synchronize access to the folder.

Syntax

public override object SyncRoot { get; }

Value

The sync root.

Remarks

Gets an object that can be used to synchronize access to the folder.

Requirements

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

Timeout Property

Get or set the timeout for network streaming operations, in milliseconds.

Syntax

public override int Timeout { get; set; }

Value

The timeout in milliseconds.

Remarks

Gets or sets the underlying socket stream's System.IO.Stream.ReadTimeout and System.IO.Stream.WriteTimeout values.

Requirements

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