System 2.0.0.0 4.0.0.0 System.Object System.IDisposable

The class is used to send e-mail to an SMTP server for delivery. The SMTP protocol is defined in RFC 2821, which is available at http://www.ietf.org.

The classes shown in the following table are used to construct e-mail messages that can be sent using .

Class

Description

Represents file attachments. This class allows you to attach files, streams, or text to an e-mail message.

Represents the e-mail address of the sender and recipients.

Represents an e-mail message.

To construct and send an e-mail message by using , you must specify the following information:

The SMTP host server that you use to send e-mail. See the and properties.

Credentials for authentication, if required by the SMTP server. See the property.

The e-mail address of the sender. See the and methods that take a parameter. Also see the property.

The e-mail address or addresses of the recipients. See the and methods that take a parameter. Also see the property.

The message content. See the and methods that take a parameter. Also see the property.

To include an attachment with an e-mail message, first create the attachment by using the class, and then add it to the message by using the property. Depending on the e-mail reader used by the recipients and the file type of the attachment, some recipients might not be able to read the attachment. For clients that cannot display the attachment in its original form, you can specify alternate views by using the property.

You can use the application or machine configuration files to specify default host, port, and credentials values for all objects. For more information, see mailSettings for system.net.

To send the e-mail message and block while waiting for the e-mail to be transmitted to the SMTP server, use one of the synchronous methods. To allow your program's main thread to continue executing while the e-mail is transmitted, use one of the asynchronous methods. The event is raised when a operation completes. To receive this event, you must add a delegate to . The delegate must reference a callback method that handles notification of events. To cancel an asynchronous e-mail transmission, use the method.

If there is an e-mail transmission in progress and you call or again, you will receive an .

The connection established by the current instance of the class to the SMTP server may be re-used if an application wishes to send multiple messages to the same SMTP server. This is particularly useful when authentication or encryption are used establish a connection to the SMTP server. The process of authenticating and establishing a TLS session can be expensive operations. A requirement to re-establish a connection for each message when sending a large quantity of email to the same SMTP server could have a significant impact on performance. There are a number of high-volume email applications that send email status updates, newsletter distributions, or email alerts. Also many email client applications support an off-line mode where users can compose many email messages that are sent later when a connection to the SMTP server is established. It is typical for an email client to send all SMTP messages to a specific SMTP server (provided by the Internet service provider) that then forwards this email to other SMTP servers.

The class implementation pools SMTP connections so that it can avoid the overhead of re-establishing a connection for every message to the same server. An application may re-use the same object to send many different emails to the same SMTP server and to many different SMTP servers. As a result, there is no way to determine when an application is finished using the object and it should be cleaned up.

When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client.

The class has no Finalize method, so an application must call to explicitly free up resources. The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources.

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

Allows applications to send e-mail by using the Simple Mail Transfer Protocol (SMTP).

- Constructor
  2.0.0.0
  4.0.0.0

  This constructor initializes the , , and properties for the new by using the settings in the application or machine configuration files. For more information, see mailSettings for system.net.

  Initializes a new instance of the class by using configuration file settings.

- Constructor
  2.0.0.0
  4.0.0.0

  The parameter is used to initialize the value of the property. The and properties are initialized by using the settings in the application or machine configuration files. If is null or equal to , is initialized using the settings in the application or machine configuration files.

  For more information about using the application and machine configuration files, see mailSettings for system.net. If information is specified using constructors or properties, this information overrides the configuration file settings.

  Initializes a new instance of the class that sends e-mail by using the specified SMTP server.

  A that contains the name or IP address of the host computer used for SMTP transactions.
- Constructor
  2.0.0.0
  4.0.0.0

  The and parameters set the value of the and properties, respectively. If is null or equal to , is initialized using the settings in the application or machine configuration files. If is zero, is initialized using the settings in the application or machine configuration files. The property is initialized using the settings in the application or machine configuration files.

  For more information about using the application and machine configuration files, see mailSettings for system.net. If information is specified using constructors or properties, this information overrides the configuration file settings.

  Initializes a new instance of the class that sends e-mail by using the specified SMTP server and port.

  A that contains the name or IP address of the host used for SMTP transactions.
  An greater than zero that contains the port to be used on .
- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO("Client certificates not used")
  System.Security.Cryptography.X509Certificates.X509CertificateCollection To be added.

  Client certificates are, by default, optional; however, the server configuration might require that the client present a valid certificate as part of the initial connection negotiation.

  The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty.

  Specify which certificates should be used to establish the Secure Sockets Layer (SSL) connection.

- Property
  2.0.0.0
  4.0.0.0
  System.Net.ICredentialsByHost To be added.

  Some SMTP servers require that the client be authenticated before the server will send e-mail on its behalf. To use your default network credentials, you can set the to true instead of setting this property. If the property is set to false, then the value set in the property will be used for the credentials when connecting to the server. If the property is set to false and the property has not been set, then mail is sent to the server anonymously.

  Credentials information can also be specified using the application and machine configuration files. For more information, see mailSettings for system.net. If information is specified using the property, this information overrides the configuration file settings.

  If you provide credentials for basic authentication, they are sent to the server in clear text. This can present a security issue because your credentials can be seen, and then used by others.

  Gets or sets the credentials used to authenticate the sender.

- Property
  2.0.0.0
  4.0.0.0
  System.Net.Mail.SmtpDeliveryMethod To be added.

  Delivery methods include:

  An SMTP server.

  Moving the email into the pickup directory for IIS, which then delivers the message.

  Moving the email to a directory specified by for later delivery by another application.

  The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings.

  Specifies how outgoing email messages will be handled.

- Method
  4.0.0.0
  System.Void

  The connection established by the current instance of the class to the SMTP server may be re-used if an application wishes to send multiple messages to the same SMTP server. This is particularly useful when authentication or encryption are used establish a connection to the SMTP server. The process of authenticating and establishing a TLS session can be expensive operations. A requirement to re-establish a connection for each message when sending a large quantity of email to the same SMTP server could have a significant impact on performance. There are a number of high-volume email applications that send email status updates, newsletter distributions, or email alerts. Also many email client applications support an off-line mode where users can compose many email messages that are sent later when a connection to the SMTP server is established. It is typical for an email client to send all SMTP messages to a specific SMTP server (provided by the Internet service provider) that then forwards this email to other SMTP servers.

  The class implementation pools SMTP connections so that it can avoid the overhead of re-establishing a connection for every message to the same server. An application may re-use the same object to send many different emails to the same SMTP server and to many different SMTP servers. As a result, there is no way to determine when an application is finished using the object and it should be cleaned up.

  When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client.

  Calling the method on a object that is executing an asynchronous operation will cancel the send operation as though the method had been called.

  The class has no Finalize method. So an application must call to explicitly free up resources.

  The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the underlying .

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

  For more information, see Cleaning Up Unmanaged Resources and Implementing a Dispose Method.

  Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed so the garbage collector can reclaim the memory.

  Sends a QUIT message to the SMTP server, gracefully ends the TCP connection, and releases all resources used by the current instance of the class.

- Method
  4.0.0.0
  System.MonoTODO("Does nothing at the moment.")
  System.Void ``

  The connection established by the current instance of the class to the SMTP server may be re-used if an application wishes to send multiple messages to the same SMTP server. This is particularly useful when authentication or encryption are used establish a connection to the SMTP server. The process of authenticating and establishing a TLS session can be expensive operations. A requirement to re-establish a connection for each message when sending a large quantity of email to the same SMTP server could have a significant impact on performance. There are a number of high-volume email applications that send email status updates, newsletter distributions, or email alerts. Also many email client applications support an off-line mode where users can compose many email messages that are sent later when a connection to the SMTP server is established. It is typical for an email client to send all SMTP messages to a specific SMTP server (provided by the Internet service provider) that then forwards this email to other SMTP servers.

  The class implementation pools SMTP connections so that it can avoid the overhead of re-establishing a connection for every message to the same server. An application may re-use the same object to send many different emails to the same SMTP server and to many different SMTP servers. As a result, there is no way to determine when an application is finished using the object and it should be cleaned up.

  When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client.

  Calling the method on a object that is executing an asynchronous operation will cancel the send operation as though the method had been called.

  The class has no Finalize method. So an application must call to explicitly free up resources.

  The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources.

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

  For more information, see Cleaning Up Unmanaged Resources and Implementing a Dispose Method.

  Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed so the garbage collector can reclaim the memory.

  Sends a QUIT message to the SMTP server, gracefully ends the TCP connection, releases all resources used by the current instance of the class, and optionally disposes of the managed resources.

  true to release both managed and unmanaged resources; false to releases only unmanaged resources.
- Property
  2.0.0.0
  4.0.0.0
  System.Boolean To be added.

  The property specifies whether SSL is used to access the specified SMTP mail server.

  The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings.

  The class only supports the SMTP Service Extension for Secure SMTP over Transport Layer Security as defined in RFC 3207. In this mode, the SMTP session begins on an unencrypted channel, then a STARTTLS command is issued by the client to the server to switch to secure communication using SSL. See RFC 3207 published by the Internet Engineering Task Force (IETF) for more information.

  An alternate connection method is where an SSL session is established up front before any protocol commands are sent. This connection method is sometimes called SMTP/SSL, SMTP over SSL, or SMTPS and by default uses port 465. This alternate connection method using SSL is not currently supported.

  You can use to specify which client certificates should be used to establish the SSL connection. The allows you to reject the certificate provided by the SMTP server. The property allows you to specify the version of the SSL protocol to use.

  If the property is set to true, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an .

  Specify whether the uses Secure Sockets Layer (SSL) to encrypt the connection.

- Property
  2.0.0.0
  4.0.0.0
  System.String To be added.

  The value of the property can also be set using constructors or the application or machine configuration file. For more information, see mailSettings for system.net.

  If information is specified using this property, this information overrides the configuration file settings.

  Gets or sets the name or IP address of the host used for SMTP transactions.

- Method
  2.0.0.0
  4.0.0.0
  System.Void ``

  Classes that inherit from the class can override the method to perform additional tasks when the event occurs.

  also allows derived classes to handle without attaching a delegate. This is the preferred technique for handling in a derived class.

  Raises the event.

  An that contains event data.
- Property
  2.0.0.0
  4.0.0.0
  System.String To be added.

  Mail messages in the pickup directory are automatically sent by a local SMTP server (if present), such as IIS.

  The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings.

  Gets or sets the folder where applications save mail messages to be processed by the local SMTP server.

- Property
  2.0.0.0
  4.0.0.0
  System.Int32 To be added.

  The value of the property can also be set using constructors or the application or machine configuration file. For more information about using configuration files, see mailSettings for system.net. If information is specified using this property, this information overrides the configuration file settings.

  Gets or sets the port used for SMTP transactions.

- Method
  2.0.0.0
  4.0.0.0
  System.Void ``

  This method blocks while the e-mail is transmitted. You can specify a time-out value using the property to ensure that the method returns after a specified amount of time elapses.

  Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor.

  You cannot call this method if there is a message being sent asynchronously.

  If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties.

  If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed.

  When sending e-mail using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends e-mail to the accepted recipients and then a is thrown. The exception will contain a listing of the recipients that were rejected.

  If the property is set to true, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an .

  Sends the specified message to an SMTP server for delivery.

  A that contains the message to send.
- Method
  2.0.0.0
  4.0.0.0
  System.Void `` `` `` `` To be added.

  This method blocks while the e-mail is transmitted. You can specify a time-out value using the property to ensure that the method returns after a specified amount of time elapses.

  Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor.

  You cannot call this method if there is a message being sent asynchronously.

  If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties.

  If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed.

  When sending e-mail using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends e-mail to the accepted recipients and then a is thrown. The exception will contain a listing of the recipients that were rejected.

  If the property is set to true, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an .

  Sends the specified e-mail message to an SMTP server for delivery. The message sender, recipients, subject, and message body are specified using objects.

  A that contains the address information of the message sender. A that contains the subject line for the message. A that contains the message body.
- Method
  2.0.0.0
  4.0.0.0
  System.Void `` ``

  To receive notification when the e-mail has been sent or the operation has been canceled, add an event handler to the event. You can cancel a operation by calling the method.

  After calling , you must wait for the e-mail transmission to complete before attempting to send another e-mail message using or .

  Before calling this method, the and must be set through the configuration files by setting the relevant properties, or by passing this information into the constructor.

  If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties.

  If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed.

  When sending e-mail using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send e-mail to any of the recipients.

  Your application can detect a server certificate validation error by examining the property passed into the delegate.

  The property does not have any effect on a call.

  To send mail and block while it is transmitted to the SMTP server, use one of the methods.

  If the property is set to true, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an .

  Sends the specified e-mail message to an SMTP server for delivery. This method does not block the calling thread and allows the caller to pass an object to the method that is invoked when the operation completes.

  A that contains the message to send. A user-defined object that is passed to the method invoked when the asynchronous operation completes.
- Method
  2.0.0.0
  4.0.0.0
  System.Void `` `` `` `` `` To be added.

  To receive notification when the e-mail has been sent or the operation has been canceled, add an event handler to the event. You can cancel a operation by calling the method.

  After calling , you must wait for the e-mail transmission to complete before attempting to send another e-mail message using or .

  Before calling this method, the and properties must be set either through the configuration files or by setting the properties or passing this information into the constructor.

  If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or property.

  If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed.

  When sending e-mail using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send e-mail to any of the recipients.

  Your application can detect a server certificate validation error by examining the property passed into the delegate.

  The property does not have any effect on a call.

  To send mail and block while it is transmitted to the SMTP server, use one of the methods.

  If the property is set to true, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an .

  Sends an e-mail message to an SMTP server for delivery. The message sender, recipients, subject, and message body are specified using objects. This method does not block the calling thread and allows the caller to pass an object to the method that is invoked when the operation completes.

  A that contains the address information of the message sender. A that contains the subject line for the message. A that contains the message body. A user-defined object that is passed to the method invoked when the asynchronous operation completes.
- Method
  2.0.0.0
  4.0.0.0
  System.Void

  Use the method to cancel a pending operation. If there is mail waiting to be sent, this method releases resources used to store the mail. If there is no mail waiting to be sent, this method does nothing.

  Cancels an asynchronous operation to send an e-mail message.

- Event
  2.0.0.0
  4.0.0.0
  System.Net.Mail.SendCompletedEventHandler

  The event is raised each time an e-mail message is sent asynchronously when the send operation completes. To send an e-mail message asynchronously, use the methods.

  is the delegate for . The class provides the event handler with event data.

  Occurs when an asynchronous e-mail send operation completes.

- Property
  2.0.0.0
  4.0.0.0
  System.MonoTODO
  System.Net.ServicePoint To be added.

  The settings for the property are created using defaults specified in the application or machine configuration files and the class.

  Gets the network connection used to transmit the e-mail message.

- Property
  4.0.0.0
  System.String To be added.

  The property is used with integrated Windows authentication when an application is using extended protection. The can then provide extended protection to ensure that credential challenge responses contain service specific information (a SPN) and, if necessary, channel specific information (a channel binding token or CBT). With this information in the credential exchanges, services are able to better protect against malicious use of credential challenge responses that might have been improperly obtained.

  The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings.

  Gets or sets the Service Provider Name (SPN) to use for authentication when using extended protection.

- Property
  2.0.0.0
  4.0.0.0
  System.Int32 To be added.

  By default, calls to the method block until the operation completes. If you set the property to a positive value, and a operation cannot complete in the allotted time, the class throws an exception.

  To send a message and continue executing in the application thread, use the method.

  Gets or sets a value that specifies the amount of time after which a synchronous call times out.

- Property
  2.0.0.0
  4.0.0.0
  set: System.MonoNotSupported("no DefaultCredential support in Mono")
  System.Boolean To be added.

  Some SMTP servers require that the client be authenticated before the server sends e-mail on its behalf. Set this property to true when this object should, if requested by the server, authenticate using the default credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios.

  Credentials information can also be specified using the application and machine configuration files. For more information, see mailSettings for system.net.

  If the property is set to false, then the value set in the property will be used for the credentials when connecting to the server. If the property is set to false and the property has not been set, then mail is sent to the server anonymously.

  If you provide credentials for basic authentication, they are sent to the server in clear text. This can present a security issue because your credentials can be seen, and then used by others.

  Gets or sets a value that controls whether the are sent with requests.