The tsNet external that comes bundled with the commercial versions of LiveCode supports the ability to send e-mail through most SMTP servers.  It supports connecting to:

• Plain unencrypted SMTP servers
• SMTP servers using SSL encryption
• SMTP servers using TLS encryption

It is important to know which methods your SMTP server supports, what ports it uses and if it requires authentication before going any further.

The simplest version of the tsNet SMTP functions is tsNetSmtpSync.  The syntax for this function is

tsNetSmtpSync(pURL, pFrom, pRcpt, pData, pOutHeaders, pBytes, [pSettings])

This function will connect to the specified mail server and send a single message to a number of recipients.  If an error occurs while sending the e-mail, the function will return a string that begins with "tsneterr:".mail delivery.  This is particularly common for mailing lists and "bcc" recipient addresses.

NOTE:  You must ensure to select “MIME Library” as well as “Internet” and “tsNet”  from the Inclusions tab of “Standalone Application Settings” before you can run this as a standalone.

Create a new stack then drag a button and five fields onto it.

Set the name of the fields to "email_from", "email_to", "email_cc", "email_subject" and "email_message".  

Drag out a label beside each field and set a name for them.  For example, "Sender address" for the first label.

Rename the button, "Add attachments and send".

Save this stack.

Edit the script of the button that you placed on the stack by right clicking on the button and selecting "edit script".

Add the following code.

Let us look at the various parts of that script to understand what is going on in more detail.

Firstly, we store the address of the mail server to be used in a variable called tURL.

put "smtp://mymailserver.domain.com:587/" into tUrl

The address needs to be specified in one of the following formats:

1. For standard unencrypted SMTP connections - smtp://mailserver.domain.com:25
2. For SSL encrypted SMTP connections - smtps://mailserver.domain.com/
3. For TLS encrypted SMTP connections - smtp://mailserver.domain.com:587

Note:  For any of these formats, a port number may be specified if your mail server does not use the standard SMTP ports.

If your mail server requires authentication, you can store the username and password to be used by the function in an array.  In this case, we are using an array called tSettings.  The "username" and "password" keys are used to store these values.

put "smtp_username" into tSettings["username"]
put "smtp_password" into tSettings["password"]

The next line of the script is very important.

-- Enable TLS for SMTP
put true into tSettings["use_ssl"]

As well as the username and password required to send e-mails, nother key that can be set is "use_ssl".  

When using TLS encryption with a SMTP server, this key must be set to true.  If you are using unencrypted SMTP, or SMTP via SSL, this should be left out or set to false.

Next we use functions from LiveCode’s MIME library to encode the body of the e-mail in the MIME format, suitable for sending via SMTP.

-- Encode the e-mail message body
put mimeEncodeFieldAsMIMEMultipartDocument(the long id of field "email_message") into tBody

We also check to see if the user wants to add an attachment to the e-mail and store that ready for encoding.

   -- See if the user wants to add an attachment
   if the environment is "mobile" then
      answer "Do you wish to include an image from your photo library?" with "Yes" or "No"
      if it is "Yes" then
         set the lockloc of the templateimage to true
         set the width of the templateimage to "300"
         set the height of the templateimage to "400"
         mobilePickPhoto "library"
         
         put the text of the last image into tAttachments[1]["data"]
         put "image/png" into tAttachments[1]["mimetype"] 
         put "image.png" into tAttachments[1]["name"]
         answer "Attaching photo from library"
         delete the last image
      else
         answer "No image attached"
      end if
   else
      answer file "Select a file to attach:"
      if the result is not "Cancel" then
         put it into tAttachments[1]["filepath"]
         answer "Attaching file:" && tAttachments[1]["filepath"]
      else
         answer "No file attached"
      end if
   end if

If the user selects a file to attach or a photo on a mobile device, the details of these attachments will be stored in a numerically indexed array called tAttachments.  This is required so that we can encode the attachments in MIME format before sending the e-mail.

Next we get the sender, recipient and subject details for the e-mail and encode them using the MIME library along with the e-mail body and any attachments.

-- Encode the e-mail headers and body
put field "email_from" into tFrom
put field "email_to" into tTo
put field "email_cc" into tCc
put field "email_subject" into tSubject

mimeEncodeAsMIMEEmail tBody, tFrom, tTo, tCc, tSubject, tAttachments
put it into tEmailMessage

After encoding the e-mail message in MIME format and setting the mail server into variables, there is one other piece of information that the script needs to deal with before the tsNetSmtpSync function can be called.

-- Make tRecipient a list of all recipients (To and Cc)
put tTo & cr & tCc into tRecipient

tsNet requires a complete list of all the recipient e-mail addresses - one per line - regardless of whether they are To, Cc or Bcc stored in one variable.  Note that tsNetSmtpSync does not use the values stored within the contents of the e-mail message, as they may not match the actual addresses used for the e-mail delivery.  This is particularly common for mailing lists and "bcc" recipient addresses.

Now that we have all that information, we can make the actual call to tsNetSmtpSync.

put tsNetSmtpSync(tURL, tFrom, tRecipient, tEmailMessage, tResponseHeaders, tBytes, tSettings) into tResult

Most of the parameters to the function have been discussed above, however you will notice two other variables tResponseHeaders and tBytes variables in the call to tsNetSmtpSync.

The contents of these two variables are replaced when the function returns and provide more information about what happened during the SMTP transaction.

The tResponseHeaders variable will contain the complete SMTP response to all the commands that were sent to the SMTP server.  In general, the last line of this variable should contain a 250 response line indicating that the message has been successfully sent to the server.

The tBytes parameter will contain the number of bytes that were sent to the SMTP server.

While this example does not utilise the information provided in these variables, they must be included in every call to the function.

If the e-mail has been sent successfully, the result from the tsNetSmtpSync call will contain the final status code response that is returned from the SMTP server.  This will usually be "250".

However, if the e-mail has failed to be sent, the result will start with "tsneterr:" followed by an readable error message and the status code that was returned.

As the final piece of code in this script shows, this makes it very easy to check if the e-mail has been sent.

if the first word of tResult is "tsneterr:" then
   answer "Error" && tResult && "returned from server"
else
   answer "E-mail sent"
end if

The code that was used in the above is available as a Livecode stack from this url: https://tinyurl.com/vw2l3ra