Class
SMTPSecureSocket
Description
Used to send secure email via the SMTP protocol using SSL or TLS encryption.
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
Encoding As TextEncoding = Nil |
|||
Bytes As Integer, Encoding As TextEncoding = Nil |
|||
Encoding As TextEncoding = Nil |
|||
Data As String |
|||
Events
Name |
Parameters |
Returns |
---|---|---|
greeting As String |
||
err As RuntimeException |
||
Email As EmailMessage |
||
ErrorID As Integer, ErrorMessage As String, Email As EmailMessage |
Enumerations
SMTPSecureSocket.SMTPConnectionTypes
SMTPConnectionTypes
Specifies the types of connections a SMTPSecureSocket can make.
Types |
---|
STARTTLS |
SSLTLS |
Property descriptions
SMTPSecureSocket.Address
Address As String
The TCP/IP address to try to connect to.
In this example, the address has been entered into a TextField.
TCPSocket1.Address = TextField1.Text
SMTPSecureSocket.BytesAvailable
BytesAvailable As Integer
The number of bytes of data are available in the internal receive buffer.
This property is read-only.
TextField1.Text = Me.BytesAvailable.ToString
SMTPSecureSocket.BytesLeftToSend
BytesLeftToSend As Integer
The number of bytes left in the queue remaining to be sent.
This property is read-only.
This enables you to create a synchronous socket without needing to subclass it.
TextField1.Text = Me.BytesLeftToSend.ToString
SMTPSecureSocket.CertificateFile
CertificateFile As FolderItem
The file that contains the SSL certificate.
This example opens the certificate file and assigns it to the property.
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
If f <> Nil Then
Socket1.CertificateFile = f
End If
SMTPSecureSocket.CertificatePassword
CertificatePassword As String
The certificate password for the secure connection.
This example sets the certificate password from a TextField.
socket1.CertificatePassword=TextField1.Text
SMTPSecureSocket.CertificateRejectionFile
CertificateRejectionFile As FolderItem
The certificate rejection file.
This example gets the certificate rejection file from disk.
Var f As FolderItem
f = FolderItem.ShowOpenFileDialog("text/plain")
If f <> Nil Then
Socket1.CertificateRejectionFile = f
End If
SMTPSecureSocket.Handle
Handle As Integer
This is the socket's internal descriptor and it can be used with Declare statements.
This property is read-only.
On Windows, Handle is a Socket, suitable for use in Declares on Windows.
On macOS and Linux, Handle is a UNIX socket descriptor.
The descriptor is platform-specific. If Handle is less than zero, the descriptor is not available.
SMTPSecureSocket.IsConnected
IsConnected As Boolean
Indicates whether the socket is currently connected.
This property is read-only.
For TCPSockets, a connection means you can send and receive data and are connected to a remote machine. For UDPSockets, this means that you are bound to the port and are able to send, receive, join or leave multicast groups, or set socket options.
If EasyUDPSocket1.IsConnected Then
' proceed using the connection
Else
MessageBox("Connection failed!")
End If
SMTPSecureSocket.LocalAddress
LocalAddress As String
The local IP address of the computer.
This property is read-only.
Var localIP As String = Socket1.LocalAddress
SMTPSecureSocket.Messages
Messages As EmailMessage
The queue of messages that are waiting to be sent.
This is an array of which the 0th element is the next message to be sent. When a message is sent, it is removed from the queue and passed to the MessageSent event. To add a message to the queue, use the Arrays method. To remove a message, use the Arrays method.
Send a simple email:
Var mail As EmailMessage
' set up the socket
Socket1.Address = "smtp.myserver.com"
Socket1.Port = 25
Socket1.UserName = "<username>"
Socket1.Password = "<password>"
' populate the email message
mail = New EmailMessage
mail.FromAddress = "test@testsite.org"
mail.Subject = "My Subject"
mail.BodyPlainText = "Hello!"
mail.Headers.AddHeader("X-Mailer","SMTP Test")
' send the email
Socket1.Messages.AddRow(mail)
Socket1.SendMail
SMTPSecureSocket.NetworkInterface
NetworkInterface As NetworkInterface
Specifies which network interface the socket should use when binding.
You can get the network interface(s) of the user's computer by calling the GetNetworkInterface method of the System module.
Leaving this property set to Nil will use the currently selected interface. In the case of UDPSockets, if you assign a non-Nil value, the socket may not be able to receive broadcast messages. The behavior is OS-dependent; it appears to work on Windows but not on other supported operating systems. If you wish to send broadcast packets out, then you should not bind to a specific interface because the behavior is undefined.
This example specifies that the TCPSocket will use the first Network Interface on the user's computer.
TCPSocket1.NetworkInterface = System.NetworkInterface(0)
SMTPSecureSocket.Password
Password As String
The Password to use to log into the SMTP server.
SMTPSecureSocket.Port
Port As Integer
The port to bind on or connect to.
On most operating systems, attempting to bind to a port less than 1024 causes a Error event to fire with an error number 107 unless the application is running with administrative permissions. This is due to security features built into the underlying OS.
You need to set the port property explicitly before any call to Listen or Connect as the Port property will be modified to reflect what the actual bound port is during the various stages of operation.
For instance, if you listen on port 8080 and a connection comes in, you can check the Port property to ensure that you're still listening on port 8080 (that the port hasn't been hijacked). Or, if you connect to a socket on port 8080, once the connection occurs, you can check to see what port the OS has bound you to. This will be a random-seeming port number.
This trick can be very useful when you do things like Listen on port 0. In that case, the OS will pick a port for you and listen on it. Then you can check the Port property to see which port the OS picked. This functionality is used for various protocols, such as FTP.
This example sets the Port to 8080.
TCPSocket1.Port = 8080
SMTPSecureSocket.RemoteAddress
RemoteAddress As String
The address of the remote machine you are connected to.
This property is read-only.
Use this instead of the Address property to determine the address of the machine you are actually connected to.
This example reports the address of the remote machine that the user is connected to. It is in the Connected event.
TextField1.Text = Me.RemoteAddress
SMTPSecureSocket.SMTPConnectionType
SMTPConnectionType As SMTPConnectionTypes
The type of connection to make to the SMTP server. The default is STARTTLS.
Use SMTPSecureSocket with this property.
SMTPSecureSocket.SSLConnected
SSLConnected As Boolean
True if you have an SSL connection.
This property is read-only.
If Me.SSLConnected Then
' connection established with secure communications, proceed ...
Else
Exit
End If
SMTPSecureSocket.SSLConnecting
SSLConnecting As Boolean
True if the socket is in the process of doing a handshake to establish an SSL connection.
This property is read-only.
If Me.SSLConnecting Then
' proceed with connection
End If
SMTPSecureSocket.SSLConnectionType
SSLConnectionType As Integer
Specifies the type of SSL connection.
Note
Use the SSLSocket constant names for ConnectionType, and not the integer values so that the IDE can warn you when constants are removed or deprecated.
Set this property by assigning a SSLConnectionTypes value to it.
The default is TLSv1. If you need to change the connection type, close the connection first.
This example changes the connection type to TLSv1.
Socket1.SSLConnectionType = SSLSocket.SSLConnectionTypes.TLSv1
SMTPSecureSocket.SSLEnabled
SSLEnabled As Boolean
Set to True to specify an SSL connection.
If SSLEnabled is False, the SSLSocket transmits data just like a TCPSocket. This property can be toggled at any time.
Me.SSLEnabled = True
SMTPSecureSocket.Username
Username As String
The Username to use to log into the SMTP server.
Method descriptions
SMTPSecureSocket.Close
Close
Closes the socket's connection, closes any connections the socket may have, and resets the socket.
The only information that is retained after calling Close is the socket's port, address (in the case of TCPSockets), and data left in the socket's receive buffer. All other information is discarded.
This example closes the EasyTCPSockets that were open. The sockets were added to the main window.
Connector.Close
Listener.Close
SMTPSecureSocket.Connect
Connect
Attempts to connect.
For TCPSockets, the address and port properties must be set. For UDPSockets, the port property must be set. The Connect method binds a socket to a port. After calling Connect, the Port property will report the actual port you are bound to.
SMTPSecureSocket.Disconnect
Disconnect
Disconnects the socket, resets it, and fires a SocketCore Error event with a 102 error to let you know that the socket has been disconnected.
This example disconnects the EasyTCPSockets that were opened.
Connector.Disconnect
Listener.Disconnect
SMTPSecureSocket.DisconnectFromServer
DisconnectFromServer
Closes the connection with the mail server.
SMTPSecureSocket.EndOfFile
EndOfFile As Boolean
Returns True when there's no more data left to read.
This code reads the rows and columns of data from a tab-delimited text file into a ListBox:
Var f As FolderItem
Var textInput As TextInputStream
Var rowFromFile, oneCell As String
f = FolderItem.ShowOpenFileDialog("text/plain") ' defined as a FileType
If f <> Nil Then
textInput = TextInputStream.Open(f)
textInput.Encoding = Encodings.UTF8
Do
rowFromFile = textInput.ReadLine
Var values() As String = rowFromFile.ToArray(String.Chr(9))
ListBox1.ColumnCount = values.Count
ListBox1.AddRow("")
Var col As Integer
For Each value As String In values
ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, col) = value
col = col + 1
End For
Loop Until textInput.EndOfFile
textInput.Close
End If
This example reads each pair of bytes from a file and writes them in reverse order to a new file. The user chooses the source file using the Open-file dialog box and saves the new file using the Save as dialog box. The EOF property is used to terminate the Do...Loop.
Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text")
If readFile <> Nil Then
Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
ReadStream.LittleEndian = True
Var writeFile As FolderItem = FolderItem.ShowSaveFileDialog("", "")
If writeFile <> Nil Then
Var writeStream As BinaryStream = BinaryStream.Create(writeFile, True)
writeStream.LittleEndian = True
Do Until ReadStream.EndOfFile
writeStream.WriteInt8(ReadStream.ReadInt8)
Loop
writeStream = Nil
End If
readStream = Nil
End If
SMTPSecureSocket.Flush
Flush
Immediately sends the contents of internal write buffers to disk or to the output stream.
This function can be useful in point-to-point communication over sockets and similar connections: To optimize for transmission performance, some types of output streams try to collect small pieces of written data into one larger piece for sending instead of sending each piece out individually. By calling Flush, the data collection is stopped and the data is sent without further delay, reducing latency.
When using this on a stream that ends up as a file on disk, it is useful, too: Any short parts of previously written data are written to disk right away, ensuring the data is actually on disk if the application terminates abruptly, e.g. due to a crash.
Avoid calling this method too often. For example, do not call it between successive Write calls because you'll slow down performance without getting much benefit.
A typical use case would look like this:
mySocket.Write("you typed: ")
mySocket.Write(key)
mySocket.Write(".")
mySocket.Flush
SMTPSecureSocket.Listen
Listen
Attempts to listen for incoming connections on the currently specified port.
After calling Listen, the Port property will report the actual port you are bound to.
SMTPSecureSocket.Lookahead
Lookahead(Encoding As TextEncoding = Nil) As String
Returns a String, containing the data that is available in the internal queue without removing it.
The optional Encoding parameter enables you to specify the text encoding of the data to be returned. The default is Nil. Use the Encodings module to specify an encoding.
This example adds the contents of the internal queue to a TextArea. The Listener EasyTCPSocket has been added to the window.
TextArea1.AddText(listener.Lookahead)
SMTPSecureSocket.Poll
Poll
Polls the socket manually, which allows a socket to be used synchronously.
The EasyTCPSocket "Listener" has been added to the window.
Listener.Poll
SMTPSecureSocket.Purge
Purge
Removes all data from the socket's internal receive buffer. It does not affect the socket's internal send buffer.
Listener.Purge
SMTPSecureSocket.Read
Read(Bytes As Integer, Encoding As TextEncoding = Nil) As String
Reads Bytes bytes from the input stream and returns a String.
If provided, the optional parameter Encoding specifies the text encoding to be defined for the String to be read.
If Bytes is higher than the amount of bytes currently available in the stream, all available bytes will be returned. Therefore, make sure to always consider the case that you get less than you requested. To see if you received all requested bytes, check the returned string's String property (avoid using Length as it may give a different number if the encoding is not nil).
If not enough memory is available, you get back an empty string.
This example reads the first 1000 bytes from a BinaryStream.
Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text/plain")
If readFile <> Nil Then
Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
ReadStream.LittleEndian = True
TextArea1.Text = ReadStream.Read(1000, Encodings.UTF8)
End If
SMTPSecureSocket.ReadAll
ReadAll(Encoding As TextEncoding = Nil) As String
Reads all the data from the internal buffer.
This example reads all the data in the buffer into a TextArea.
TextField1.AddText(listener.ReadAll)
SMTPSecureSocket.ReadError
ReadError As Boolean
If True then an error occurred during reading.
SMTPSecureSocket.RemoveAllMessages
RemoveAllMessages
Removes all messages from the send queue.
This example removes all the messages in the queue.
Socket1.RemoveAllMessages
SMTPSecureSocket.SendMail
SendMail
Connects to the mail server, sends the messages in the queue, and disconnects. SendMail is asynchronous.
SMTPSecureSocket.Write
Write(Data As String)
Writes the passed data to the output stream.
Note that in order to make sure that the data actually ends up on disk or gets sent to the socket it is connected to, the stream must either get closed or the Flush method be called. Otherwise, the data, if small, may end up temporarily in a write buffer before either a certain time has passed or more data is written. This buffering increases performance when writing lots of small pieces of data, but may be causing unwanted delays when another process, e.g. the other end of a socket connection, is waiting for the data. Consider calling the Flush method to reduce latencies that this buffering may cause in such cases.
If Write fails, an IOException will be raised.
This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.
Var f As FolderItem
Var stream As BinaryStream
f = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt")
If f<> Nil Then
stream = BinaryStream.Create(f, True)
stream.Write(TextArea1.Text)
stream.Close
End If
SMTPSecureSocket.WriteError
WriteError As Boolean
If True then an error occurred during writing.
Event descriptions
SMTPSecureSocket.ConnectionEstablished
ConnectionEstablished(greeting As String)
Executes when the connection has been established with the mail server and passes the greeting string that the server returned.
SMTPSecureSocket.Error
Error(err As RuntimeException)
Occurs when an error occurs with the socket.
These error codes provide you with key information about your socket, and it is not advisable to ignore them.
When an error occurs, the RuntimeException property will likely contain one of the following error codes:
Error Code |
Description |
---|---|
0 |
No error occurred. |
100 |
There was an error opening and initializing the drivers. |
101 |
This error code is no longer used. |
102 |
This code means that you lost your connection. |
103 |
The socket was unable to resolve the address that was specified. |
104 |
This error code is no longer used. |
105 |
The address is currently in use. |
106 |
This is an invalid state error, which means that the socket is not in the proper state to be doing a certain operation. |
107 |
This error means that the port you specified is invalid. |
108 |
This error indicates that your application has run out of memory. |
Information on additional error codes is available.
The following example in the Error event handler displays the error code.
MessageBox(Me.e.ErrorNumber.ToString)
SMTPSecureSocket.MailSent
MailSent
Executes when all of the messages in the queue have been sent.
SMTPSecureSocket.MessageSent
MessageSent(Email As EmailMessage)
Executes when a message has been sent; Email contains the message that was sent.
SMTPSecureSocket.SendProgress
SendProgress(BytesSent As Integer, BytesLeft As Integer) As Boolean
Occurs when your network provider queues your data in chunks and is about to send the next chunk.
The parameters indicate the amount of progress that has been made during the send. Returns a Boolean.
Returning True from this event causes the send to be cancelled. This does not close the socket's connection; it only clears the buffer. After all of the data has been transferred you will get a final SendProgress event followed by a SendComplete event.
bytesSent is the number of bytes that were sent in the chunk, not the total number of bytes sent.
SMTPSecureSocket.ServerError
ServerError(ErrorID As Integer, ErrorMessage As String, Email As EmailMessage)
Executes when an error occured while sending a message.
ErrorID and ErrorMessage are sent by the mail server and Email is the message that was being sent when the error occurred. Email is removed from the queue at the time the event executes.
Notes
The SMTPSecureSocket class is the same as the SMTPSecureSocket class except that it is derived from SSLSocket instead of TCPSocket. As a result, you can use the Secure property of the SSLSocket class to provide secure communications.
If you use a constructor in a subclass of a SMTPSecureSocket, you must call the Super class's constructor in your subclass's constructor. The subclass will not work unless this is done.
Error codes
For a list of codes, refer here: * Understanding SMTP Error Codes * RFC 5321
Keep in mind that some codes may be server specific.
Gmail
In order to connect to Gmail you'll need to enable the "allow less secure apps" option as described in this Google support document:
https://support.google.com/accounts/answer/6010255
With that enabled, these settings work for most users:
MailSocket.Address = "smtp.gmail.com"
MailSocket.Port = 465
MailSocket.SSLConnectionType = SSLSocket.SSLConnectionTypes.TLSv1
MailSocket.SMTPConnectionType = SMTPSecureSocket.SMTPConnectionTypes.SSLTLS
MailSocket.SSLEnabled = True
MailSocket.UserName = <YourGmailUserName>
MailSocket.Password = <YourGmailPassword>
Xojo cloud
To access an SMTP server from web apps running on Xojo Cloud, you will first have to use the FirewallPort class to open the port used to connect to the SMTP Server:
Var fwp As New XojoCloud.FirewallPort(587, _
XojoCloud.FirewallPort.Direction.Outgoing)
fwp.Open ' This call is synchronous
If fwp.isOpen Then
' Do what you need to do
End If
Sample code
This code uses an SMTPSecureSocket called MailSocket that has been added to a Window to send a simple email using Gmail. Update the Username, Password and email address in this code to use it.
' Connect to Gmail
MailSocket.Address = "smtp.gmail.com"
MailSocket.Port = 465
MailSocket.SSLConnectionType = SSLSocket.SSLConnectionTypes.TLSv1
MailSocket.SMTPConnectionType = SMTPSecureSocket.SMTPConnectionTypes.SSLTLS
MailSocket.SSLEnabled = True
MailSocket.Username = "<YourGmailUsername>" ' Provide your Gmail username
MailSocket.Password = "<YourGmailPassword>" ' Provide your Gmail password
' Create EmailMessage
Var mail As New EmailMessage
mail.FromAddress = "myemail@mydomain.com" ' Your from email address
mail.AddRecipient("recipient@domain.com") ' The recipient's email address
mail.Subject = "Test from Xojo"
mail.BodyPlainText = "This email was sent from a Xojo app."
mail.Headers.AddHeader("X-Mailer","SMTP Test")
' Send it
MailSocket.Messages.AddRow(mail)
MailSocket.SendMail
Compatibility
All project types on all supported operating systems.
See also
SSLSocket parent class; EmailMessage, URLConnection, URLConnection, POP3SecureSocket, TCPSocket, POP3SecureSocket, SMTPSecureSocket, SocketCore classes.