How to send e-mail using the tsNet external

Getting started with sending e-mail

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.

An example using the tsNetSmtpSync function

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:".

Here is a simple script that uses this function to send e-mail via a SMTP server that uses TLS encryption.

   local tUrl, tEmailMessage, tSender, tRecipient, tSettings, tResult, tBytes, tResponseHeaders

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

   put "smtp_username" into tSettings["username"]
   put "smtp_password" into tSettings["password"]
   put "me@mydomain.com" into tSender
   put "recipient1@mydomain.com" & cr into tRecipient
   put "recipient2@mydomain.com" after tRecipient

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

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

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

Now, 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.

Next we get the contents of the e-mail message to send, which in this case we are getting from a field.

put field "emailMessage" into tEmailMessage

The contents of the e-mail must include the e-mail headers and a very basic e-mail message may look like this:

From: Tom Smith <tsmith@livecode.com>
To:  Sally Jones <sjones@runrev.com>
Subject:  My new e-mail application

Hi Sally,
I am sending this from my new LiveCode application!
See you soon,
Tom

The e-mail headers are separated from the e-mail body by a blank line.  There are a lot of e-mail headers that can be used in e-mails, along with different MIME formats for sending HTML e-mails and attachments.  These are beyond the scope of this introduction lesson.

After storing the e-mail message and mail server into variables, there are a few other pieces of information that the script needs to deal with before the tsNetSmtpSync function can be called.

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"]

Next we must set the sender and recipient e-mail addresses.  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.

put "me@mydomain.com" into tSender
put "recipient1@mydomain.com" & cr into tRecipient
put "recipient2@mydomain.com" after tRecipient

In this script, the sender's e-mail address is stored in a variable called tSender and the recipients e-mail addresses are stored in another variable called tRecipient.

Note that to specify multiple recipients, simply list each e-mail address one per line within the variable.

The next line of the script is very important.

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

Remember that we are building a settings array called tSettings.  A few lines further up in the code, we set the "username" and "password" keys in this array.  Another 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.

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

put tsNetSmtpSync(tURL, tSender, 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

Sample stacks

The code that was used in the above is available as a Livecode stack here.

A more advanced example that includes some basic MIME encoding support and the ability to add an attachment to the e-mail is also available.

0 Comments

Add your comment

E-Mail me when someone replies to this comment