How to send e-mail using the tsNet external
Last Updated: 17 August 2020
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:".mail delivery. This is particularly common for mailing lists and "bcc" recipient addresses.
Lay out the Stack
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.
Create the Script
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.
on mouseUp pMouseButton
local tUrl, tEmailMessage, tRecipient, tBody, tFrom, tTo, tCc, tSubject, tAttachments
local tSettings, tResult, tBytes, tResponseHeaders
-- Specify the e-mail server settings
put "smtp://my.mailserver.com:587/" into tUrl
put "username" into tSettings["username"]
put "password" into tSettings["password"]
-- Enable TLS for SMTP
put true into tSettings["use_ssl"]
-- Encode the e-mail message body
put mimeEncodeFieldAsMIMEMultipartDocument(the long id of field "email_message") into tBody
-- 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
-- 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
-- Make tRecipient a list of all recipients (To and Cc)
put tTo & cr & tCc into tRecipient
-- Send the e-mail
put tsNetSmtpSync(tURL, tFrom, tRecipient, tEmailMessage, tResponseHeaders, tBytes, tSettings) into tResult
-- Check the result
if the first word of tResult is "tsneterr:" then
answer "Error" && tResult && "returned from server"
else
answer "E-mail sent"
end if
end mouseUp
What the Script does
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 tUrlThe address needs to be specified in one of the following formats:
- For standard unencrypted SMTP connections - smtp://mailserver.domain.com:25
- For SSL encrypted SMTP connections - smtps://mailserver.domain.com/
- 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 tBodyWe 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 ifIf 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 tEmailMessageAfter 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 tRecipienttsNet 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 tResultMost 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 ifSample stacks
The code that was used in the above is available as a Livecode stack from this url: https://tinyurl.com/vw2l3ra
Hi everybody! Does somebody has an idea why both example stacks didn't work anymore? I got always the error message button "Send Email": execution error at line 38 (Function: error in function handler) near "tsNetSmtpSync", char 8". What did I do wrong?