Class SmtpClient

Sends mail messages via SMTP (RFC 5321). One instance maintains a single connection; use Send(MimeMessage) for one message. Not thread-safe; use one instance per thread.

Inheritance

object

SmtpClient

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

Assembly: DRIT.Mail.dll

Syntax

public sealed class SmtpClient : IDisposable

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Constructors

SmtpClient(SmtpClientOptions)

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

Declaration

public SmtpClient(SmtpClientOptions options)

Parameters

Type	Name	Description
SmtpClientOptions	options	The client configuration.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

SmtpClient(SmtpClientOptions, ISmtpTransport)

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

Declaration

public SmtpClient(SmtpClientOptions options, ISmtpTransport transport)

Parameters

Type	Name	Description
SmtpClientOptions	options	The client configuration.
ISmtpTransport	transport	The transport to use.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Properties

Capabilities

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

Declaration

public SmtpServerCapabilities Capabilities { get; }

Property Value

Type	Description
SmtpServerCapabilities

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

IsAuthenticated

Gets a value indicating whether the client has authenticated.

Declaration

public bool IsAuthenticated { get; }

Property Value

Type	Description
bool

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

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 SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

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 SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Methods

Authenticate()

Authenticates with the server using the credentials configured in SmtpClientOptions. The mechanism is selected automatically based on the server's advertised mechanisms and the PreferredAuth setting.

Declaration

public void Authenticate()

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Exceptions

Type	Condition
SmtpAuthenticationException	Thrown if authentication fails, no common mechanism exists, or a plaintext mechanism would be used over an unencrypted connection with RequireEncryption.

Authenticate(SmtpCredentials)

Authenticates with the server using the specified credentials.

Declaration

public void Authenticate(SmtpCredentials credentials)

Parameters

Type	Name	Description
SmtpCredentials	credentials	The username/password credentials.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Authenticate(SmtpOAuth2Token)

Authenticates with the server using the specified OAuth 2.0 token.

Declaration

public void Authenticate(SmtpOAuth2Token token)

Parameters

Type	Name	Description
SmtpOAuth2Token	token	The OAuth 2.0 access token.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Connect()

Connects to the SMTP server, reads the greeting, sends EHLO (or HELO fallback) to negotiate capabilities, and performs STARTTLS or implicit TLS upgrade as configured.

Declaration

public void Connect()

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Disconnect()

Sends QUIT and closes the connection. Safe to call multiple times.

Declaration

public void Disconnect()

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Dispose()

Disposes the client, sending QUIT if still connected.

Declaration

public void Dispose()

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Noop()

Sends a NOOP command to keep the connection alive or verify the server is responsive.

Declaration

public void Noop()

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Reset()

Sends a RSET command to abort the current transaction.

Declaration

public void Reset()

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Send(MimeMessage)

Sends a single message via SMTP. Uses pipelining (RFC 2920) when both the client and server support it; otherwise falls back to sequential command/response. Automatically selects 8BITMIME (RFC 1652) and SMTPUTF8 (RFC 6531) envelope parameters based on message content and server capabilities.

Declaration

public SmtpDeliveryResult Send(MimeMessage message)

Parameters

Type	Name	Description
MimeMessage	message	The message to send.

Returns

Type	Description
SmtpDeliveryResult	The delivery result.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Send(MimeMessage, DkimSigner?)

Sends a single message via SMTP, optionally applying a DKIM signature before transmission. When dkimSigner is non-null, the message is serialized, signed, and the signed bytes are sent verbatim — guaranteeing that the DKIM signature validates at the receiver because the bytes on the wire are identical to the signed bytes.

Declaration

public SmtpDeliveryResult Send(MimeMessage message, DkimSigner? dkimSigner)

Parameters

Type	Name	Description
MimeMessage	message	The message to send.
DkimSigner	dkimSigner	The DKIM signer to apply, or null to send unsigned.

Returns

Type	Description
SmtpDeliveryResult	The delivery result.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Send(byte[])

Sends pre-serialized message bytes via SMTP. This is the DKIM-safe primitive: the caller produces the exact bytes to transmit (e.g. by signing with DkimSigner), and the client sends them verbatim. The envelope (MAIL FROM, RCPT TO) is extracted by parsing the raw bytes.

Declaration

public SmtpDeliveryResult Send(byte[] rawMessageBytes)

Parameters

Type	Name	Description
byte[]	rawMessageBytes	The raw RFC 5322/2045 message bytes.

Returns

Type	Description
SmtpDeliveryResult	The delivery result.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Send(IEnumerable<MimeMessage>)

Sends multiple messages over a single connection. Each message is sent as a separate MAIL FROM / RCPT TO / DATA transaction, reusing the connection. Per-message failures are recorded and the batch continues; fatal transport errors or 421 responses abort the batch.

Declaration

public SmtpBatchResult Send(IEnumerable<MimeMessage> messages)

Parameters

Type	Name	Description
IEnumerable<MimeMessage>	messages	The messages to send.

Returns

Type	Description
SmtpBatchResult	The batch result with per-message delivery results.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Send(IEnumerable<MimeMessage>, DkimSigner?)

Sends multiple messages over a single connection, optionally applying a DKIM signature to each message before transmission.

Declaration

public SmtpBatchResult Send(IEnumerable<MimeMessage> messages, DkimSigner? dkimSigner)

Parameters

Type	Name	Description
IEnumerable<MimeMessage>	messages	The messages to send.
DkimSigner	dkimSigner	The DKIM signer to apply to each message, or null to send unsigned.

Returns

Type	Description
SmtpBatchResult	The batch result with per-message delivery results.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Verify(string)

Sends a VRFY command (RFC 5321 §4.1.1.6) to verify a mailbox address. Many servers disable VRFY for security reasons; in that case the server returns a 252 (cannot verify) or 502 (not implemented) response, which this method surfaces as the return value rather than throwing.

Declaration

public SmtpResponse Verify(string address)

Parameters

Type	Name	Description
string	address	The email address or user name to verify.

Returns

Type	Description
SmtpResponse	The server response. A 2xx response indicates the address was verified; 252 means the server cannot verify but will accept; 5xx means the address is invalid or VRFY is disabled.

Remarks

Connection lifecycle. A SmtpClient wraps a single TCP connection. Call Connect() to open it, Send(MimeMessage) to send messages, and Disconnect() (or Dispose()) to close it. If AutoConnect is true (the default), Send(MimeMessage) connects automatically on the first call.

Error recovery. If the server returns 421 (service not available) or the connection drops, the client marks itself as disconnected. Subsequent Send(MimeMessage) calls throw InvalidOperationException unless AutoConnect is true, in which case a new connection is established. For batch sends, a 421 or transport error aborts the batch (Aborted is true); the caller should create a new SmtpClient to resume.

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

Implements

IDisposable