NetTalk Email

Almost all programs can benefit from Sending and/or Receiving emails. NetTalk makes it easy to add simple, or sophisticated, email handling abilities directly into your application.

Emails are sent using the SMTP protocol.

Emails are received using either the POP3 or IMAP protocol.

In NetTalk 10 (specifically 10.22 and later) some of the properties changed from STRING values to STRINGTHEORY objects. Because assigning a value to an object using the = sign causes a GPF, the names of the properties have changed. This means that if you have used the old properties in your embed code then you will get a compile error.

If you get a compile error in your code then you can replace the old property name, and syntax, with the new property name and syntax.

These changes affect Email Sending (SMTP), Email Receiving (POP3 and IMAP) classes.

Old Syntax	New Syntax
x = email.WholeMessageLen	x = email.WholeMessageST.Length()
s = email.WholeMessage	s = email.WholeMessageST.GetValue()
x = email.MessageTextLen	x = email.MessageTextST.Length()
s = email.MessageText	s = email.MessageTextST.GetValue()
email.MessageText = s	email.MessageTextST.SetValue(clip(s))
x = email.MessageHTMLLen	x = email.MessageHTMLST.Length()
s = email.MessageHTML	s = email.MessageHTMLST.GetValue()
email.MessageHTML = s	email.MessageHtmlST.SetValue(clip(s))
if Imap.wholeMessageLen	if Imap.wholeMessageST.Length()
x = email.BufferLen	x = email.BufferST.Length()
s = email.Buffer	s = email.BufferST.GetValue()

The prototype for the following methods have changed;

MethodName	Change
EmbedImages	First parameter has changed from a *string to a StringTheory object.

The following methods are no longer required, and if you have called them in your embed code then you can just remove the call;

MethodName
SetRequiredMessageSize

Sending Emails
Receiving Emails
IMAP

Sending Emails

The example in \clarion\examples\NetTalk\Email\Demo\ABC is the best email example. And you can import various dictionary tables and procedures directly from there to speed things along. References to "the example" in the text below are referring to this example. A Legacy version of this example is in \clarion\examples\NetTalk\Email\Demo\Legacy

Quick Method

Import SecwinEmail.Dctx into your dictionary
Add the NetTalk Global Extension (and StringTheory Global Extension) to your app
On the NetTalk Global Extension, Procedures Tab, click on the SendEmail button

What Just Happened?

In order to be able to send emails from your application there are really only a few basic things to do;

Allow the user to enter server connection settings somewhere so that your program knows which server to send to.
Optionally, create a EmailLog table in your dictionary, and add a browse on this to your app.
Create a SendEmail procedure which you can call from anywhere in your code.
Add a call to SendEmail in all the various places where you wish to send emails.

Server Connection Settings

TIP: You can import the SecwinEmail.dctx file into your dictionary. This adds two tables, EmailSettings and EmailLog to your dictionary. The EmailSettings table contains the fields below.

A number of settings are used when connecting to a server. These settings can vary from one installation to the next so it's important to allow the user to capture these. Once set (on one workstation) the settings are usually valid for all the workstations so (assuming the settings are visible to all machines) no per-workstation setup is required.

You could add these settings to your existing shared settings table or you could create a new table. The settings are as follows:

EmailServer (String 255)
This is the URL of the server. It's sometimes an IP address (eg 192.168.1.1) or a DNS name (eg mail.capesoft.com)
EmailPort (Long) (A long.
The default value should be 25. Values of 587, 990 and 465 are also commonly used.
AlwaysSSL (Long).
A boolean value (0 or 1) this is set to 1 if the connection to the server is always over TLS
StartTLS (Long)
A boolean value (0 or 1) this is set to 1 if the connection starts normally but then a STARTTLS command switches it to TLS.
SSLMethod (Long)
The TLS version to use when connecting to the server. The default is TLS 1.2, 1.1 or 1.0 (in that order).
UserName (String 255)
The user name for the user on the server.
Password (String 255)
The password for this user when connecting to the server
FromAddress (String 255)
The default FROM address of the "person" sending the email. All emails must have a valid FROM address (ie the server must recognize the FROM address) or the chance of the email being successful is very small.

Once you have the fields in your table you should give the user some way to change these settings. They will need to be different with each site you install, so the user will need to have access to them.

Tip: On one of our internet machines we run a mail server. In our shipping programs we default all the above settings to that (internet) mail server. This increases the chances of the email sending "just working" immediately after the program is installed. The customer can change the settings later if they like. Of course if they've blocked the outgoing port in their firewall then they won't be able to send via our server, but then they will have their own internal server they can route the mail through.

EmailLog Table

TIP: You can import the SecwinEmail.dctx file into your dictionary. This adds two tables, EmailSettings and EmailLog to your dictionary. The EmailLog table contains the fields below.

Keeping a record of outgoing emails is very useful. Exposing this record to the customer adds value to your program and also allows them (or you) to audit what emails were sent, and when.

While you can store any fields you like in this table, the following are recommended;

Guid (String 16)
User (String 255)
Date (Long / Date)
Time (Long / Time)
SendDate (Long / Date)
SendTime (Long / Time)
ToEmail (String 255)
FromEmail (String 255)
Subject (String 255)
CC (String 255)
BCC (String 255)
Attachment (String 1024)
EmbedList (String 1024)
MessageText (MEMO 64000)
MessageHTML (MEMO 64000)
Status (Long)

Global Variables

When logging outgoing emails it's useful to know the current user's Name and Email Address. (ie the name and address of the user currently using the program.) There are many systems for managing users, so the easiest way to support this is to add two global variables to your program. These can be set when a user logs in, (you will need to do that in your embed code) and then used in the SendEmail procedure when a mail is sent.

The global variable names are

Glo:UserEmail (String 255)
Glo:UserName (String 255)

You can change these names if you need to - then just change where they are used in the SendEmail procedure.

UpdateEmailSettings Procedure

The example contains a sample procedure which just edits a single record in a table. Of course you may have added the fields to an existing table, in which case just use your existing form to set the settings.

BrowseEmailLog Procedure

An example of this procedure is in the example. This procedure is optional. It allows users to see what emails have been sent, and if desired, resend an email that did not get through. This procedure is a very standard browse on the table - there are no special NetTalk extensions here.
The only bit of hand-code in the procedure revolves around the Resend button.

SendEmail Procedure

The SendEmail procedure is a normal procedure in your app tree, so you have a lot of control over what the window looks like, and how it works. If you are logging emails then this is a great procedure to add the logging code to.

The SendEmail procedure has the following prototype;
(EmailParametersGroup pEmail),Long,Proc

The parameters are set to;
(EmailParametersGroup pEmail)

the NetTalk Send Email control template has been added to the window. Note the template settings for this, as this is where you use a combination of the email server settings, and the parameters to construct the email. See the example for some ideas.

The example contains an interface which makes debugging email problems easier. It allows you to see the conversation between the program and the email server as it occurs. The log of the most recent conversation is also written to a text file for you. Plus of course each outgoing email is logged to the EmailLog table.

You can of course edit this procedure to make it work, or look, different so that it better matches your application.

Calling the SendEmail Procedure

The SendEmail procedure can be acalled from any other procedure. It might be a button, or a menu item, or it might happen in source code when some event occurs. To call SendEmail follow these steps:

Create a local variable in the procedure;
parms group(EmailParametersGroup).
Where you want to send the email, prime the components of the parms parameter
clear(parms)
parms.pEmailTo = 'bruce@capesoft.com'
parms.pEmailFrom = glo:UserEmail
parms.pEmailSubject = 'Great Release'
parms.pEmailCC = ''
parms.pEmailBCC = ''
parms.pEmailFileList = ''
parms.pEmailEmbedList = ''
parms.pEmailMessageTextST.SetValue('Well done on a great release')
parms.pEmailMessageHTMLST.SetValue('<html>...</html>')
Call the SendEmail procedure. You can do this on another thread;
START(SendEmail,25000,parms)
or on the same thread (in which case you get a returned value;
result = SendEmail(parms)

Receiving Emails

IMAP

For English speaking users, who exclusively use the Roman alphabet from A to Z there is no issue here, and this section in the documentation can be skipped.

For non-English speaking users though, you may need to deal with non-roman characters. You will have some choices in how you do that though, and so those choices need to be communicated to the class so that it knows what you are doing. The default approach though is the one most likely to be used by your program, so it is probable that you will not need to do anything yourself.

A number of the class properties could be subject to these foreign characters. These include any email address list (From, To, CC, BCC), the Subject and of course the MessageText and MessageHTML. It is assumed that whichever approach you take to handling foreign characters, this approach is consistent across all these properties.

The two primary approaches to encoding non-ASCII text are to either use Unicode, or codepages (aka charsets). Since Clarion (up to version 10) cannot display, or get user entry, in Unicode, most programs would use the codepage approach.

Codepages (Charsets)

This is the default approach for non-ASCII characters. The codepage property will default to the setting (system{prop:charset}) used in your program, so it is likely there is nothing you will need to do. If your system charset is set then the class will assume that all outgoing properties are in that charset, and all incoming properties need to be converted to that charset.

You are also able to set the codepage property yourself to any st:CP_ value, as listed in StringTheory.Inc.

The CodePage property will only be used if the encoding property is not set to either st:EncodeUtf8 or st:EncodeUtf16 (see Unicode below).

Unicode

If your email values are already formatted in Unicode then you MUST set the encoding property before calling the SendEmail method. It should be set to either st:EncodeUtf8 or st:EncodeUtf16 (depending on how you have formatted your strings.)

The SendEmail Control Template lets you easily create your own SendEmail procedure. It places a lot of fields on the window for you, but you can obviously remove the ones you do not want to see. In the Demo example all the fields, except the actual Send button have been removed.

The Control template also acts as the "Glue" between the incoming parameters, the application-wide email settings, and the SendEmail object. The template settings should be filled in carefully.

General Tab

Object Name

Defaults to ThisSendEmail. You can change this if you like.

Base Class

Defaults to NetEmailSend. You can change this to a derived class if you have written one.