Princen Internet SendMail v3.02 - by Princen IT

by Tom Hebenstreit, Review Editor

Published 1998-10-01    Printer-friendly version

More and more often, I find that the programs I write need to be able to generate some kind of email. Whether it's for doing mass or custom mailings, automatically notifying business partners or team members of an event or requirement, or even replicating data to remote locations, the ability to easily send the information contained in my programs to someone else has become increasingly important.

Now, if you are talking email, nine time out of ten nowadays you are talking mail sent via the Internet – and implementing that in your programs is not exactly a trivial endeavor if you try to do it all yourself. Princen Information Technology, however, has developed a product that lets you do just that: easily send email from within your program across the Internet. Before I tell you about their Send Internet Mail templates (SendMail), though…

First, a word from your local MIME

No, I don't mean a white-faced wacko trying to get out of an invisible box.

Seeing as how the Internet is vast jumble of rather cryptic acronyms, I just want to clarify a few terms which are relevant to email and the templates before we start.

TCP/IP (Transmission Control Protocol/Internet Protocol) - In brief, the networking protocol underlying everything that happens on the Internet: Web, email, FTP, news groups – everything.

SMTP (Simple Mail Transport Protocol) - This is the standard basic method used by programs to send email through an Internet mail server. Two others standards called POP3 and IMAP4 are used to receive and manage email, but as the templates in question don't do that, we can safely ignore these two.

MIME (Multipurpose Internet Mail Extensions) - These were invented to allow more flexibility in the types of mail you can send and how attachments are handled. Most people don't know that Internet mail can only contain text - binary is not allowed. So how come you can attach a ZIP file or image to an email? The simple answer is that behind your back, your email program encodes (or translates) the binary information into text characters and then tacks them on to the email message itself. On the receiving end, the other person's mail program does the opposite - it shows them the text you wrote and decodes (un-translates, if you will) the encoded text back into the binary format. MIME is the standard that allows the two programs each to know what the other one did, and hence end up with the same binary file at either end. By the way, this is why you can attach a 10K ZIP file to a short message and see it received as a 25K message – the MIME encoded text representation isn't nearly as efficient (compact) as the binary one.

HTML Mail - This is a newer feature of Internet email whereby your message is sent (in essence) in the same format as a web page, complete with fancy fonts, tables, graphics, etc. If the recipient has a modern mail program, they will see it as you wrote it. If not, they will see it as a jumble of text and HTML tags – rather the same as if you view the source of a web page on the World Wide Web.

Winsock.dll - Winsock is the common name for the 16-bit dynamic link library that handles the low-level interfaces into the Internet (called sockets). For 32-bit, it is actually named WSOCK32.DLL, but most people still refer to it generically as Winsock (Windows Sockets, get it?). Virtually every Internet application on your machine from your web browser to your email program uses it. For Win 95/98/NT, it is installed as an integral part of Windows. For Windows 3.x, you can get third party ones or use one available for free from Microsoft.

MAPI (Messaging Application Programming Interface) - MAPI is a set of messaging services built into Windows and used by all Microsoft products like Inbox, Windows Messaging, Outlook, Outlook Express, etc. It handles many types of email, including Internet Mail. If you send mail through MAPI to the Internet, it will eventually end up being sent using TCP/IP, SMTP and, if there are attachments, MIME encoding.

Ok, enough of this, let's get back to the Princen SendMail templates…

Major Features

In broad terms, the SendMail templates provide a wrapper for an OOP class and DLL that do all of the actual work of implementing those acronyms we just discussed. Some of the capabilities of SendMail include:

• It uses your Internet connection and talks native TCP/IP. Mail is sent directly using SMTP – no MAPI is needed or used (less complexity for you).
• It supports single or multiple attachments, automatically MIME encoding files as needed.
• It supports HTML mail compatible with IE 4, Netscape 4, etc. You can select an html file as a mail message and it will automatically convert it (along with all any images, etc.) to HTML mail.
• You can send mail to Internet News Groups (USENET).
• The same email can be sent to multiple recipients without showing the names of all recipients in the TO: field. Multiple Carbon Copies and Blind Carbon Copies are also supported.
• There is no limit to message size, number of recipients and attachments (within reason, of course).
• You can use a callback function to track the status of the email you are sending so that you can display progress bars, bytes sent, etc.
• Virtually all of the common Internet mail standards are supported by SendMail (Princen lists eleven Internet mail standards that they support in their documentation).

As you can see, SendMail seems to have all the bases covered when it comes to generating Internet mail. Let's dig in deeper and see how it turns out…

Installation

SendMail is distributed as a self-contained installation file downloaded from the Princen web site. (It is also available on disk through the TopSpeed Accessories program.)

Upon running the installation program, you are asked which version of Clarion you want to install for: CW 2.0 or C4. I chose C4, and the installer proceeded to find the appropriate directory for that version. I was then presented with the option of installing the SendMail Demo programs, the templates, or both. Note: only the template option is password protected so that you can try the demo programs before purchasing the templates. I chose to install everything, entered the password I had received from Princen and away it went, copying the files and creating a Princen SendMail group on my Win95 menu.

When it finished, I was offered the option of viewing the ReadMe file, the What's New file or both. All in all, a very nicely done install which made it easy to know what to do next.

Implementation

To add SendMail to an application, you must first add its Global extension. This template has no prompts or choices – it simply does the work of including the SendMail classes, defining its variables and other sundry background tasks. How you use SendMail beyond this point depends on what you are trying to accomplish. Let's take a look at a few scenarios:

Let a user create a mail message and send it

In this case, you would create a procedure (Window, most likely) which contains as many of the usual email type fields as you need. For example, entry fields for the 'To' email address, subject and a text box for the body of the message. The user would fill in the prompts and message, then press a 'Send' button.

To do this, you would create the Window and button, then place the 'Send Internet Mail' code template in the 'Accepted' event for the button. This template is where you specify which mail server to use, which variables hold the parts of the message and more, as illustrated below in Figure 1.

The Send Internet Mail code template options

See how you can use either strings or variables for prompts. This allows you to, for instance, hard code the mail server and 'From' address information while letting the user fill in the rest. You can also wrap the send within a conditional test simply by entering something into the 'Condition' prompt. For example, you could ask the user to confirm sending the message, and send it only if they answer yes.

In any case, this template takes care of creating the SendMail object, sending the message and then destroying the object. No hand code is required unless you wish to manipulate the variables yourself somehow (load them from an INI file, example).

Note: To help you create this type of functionality, both of the demo programs have variants of a procedure that lets you create and send messages. You can import one into your own application and modify it or just use them as a guideline to create your own.

demos)

Generate mail without user intervention

Let's say you want your system to automatically send a message to your buyer when the inventory of a product is getting low. In this case, you could define and fill the variables for the email in embeds within your program and then simply drop in the 'Send Internet Mail' template where appropriate. Once again, the template takes care of sending the mail, although you would need to fill the variables first.

Using a process to generate multiple email messages

This type of functionality is not directly supported by templates (which is a shame), so you would need to write a bit of handcode. To help illustrate how easy it is to use SendMail in handcode, I've provided some actual code snippets from a test application. All it took was the following:

Step 1: Add the 'Send Internet Mail Declare' extension to my Process procedure. This template simply creates the SendMail object (with a name that you specify) at procedure start and then destroys it at procedure end. It's up to you to use the SendMail methods and properties to actually send any mail. By the way, I named the SendMail object 'Email', so the examples below will all be prefaced with that name.

Step 2: Initialize the variables which won't change, such as the mail server and who the message is from. I do this in the Open Window embed like this:

Email.SetMailHost('mail.acme.com')
Email.SetMailer('ACME Online Auto Notify')
Email.SetFrom('wcoyote@acme.com')Email.SetOrganization('ACME Online')Email.SetSubject('New Inventions')

Note the 'SetMailHost' method. This is where you specify the name of the SMTP mail server you will be sending your mail through.

Step 3: Create a customized message and send it in the 'Activity for each Record' embed:

Email.AddTo(CLIP(CUS:LastName) & ', ' & |
            CLIP(CUS:FirstName),|
            CLIP(CUS:EmailAddress))
Email.SetMessage('Hey ' & clip(CUS:FirstName) &|
                 ', buy my stuff!')
i# = Email.SendIt() ! Send the mail message
IF i# <> 0
  MESSAGE('Error send E-Mail!|' & Email.GetMailError(i#)
          ,'Internet Mail', ICON:Exclamation)
END
Email.ClearAll ! Clear out all To, CC, etc.

Notice the use of the SendMail method called 'AddTo' which simply adds people to the 'To' portion of the email address (it can be called multiple times for a message). There are also 'AddCC' and 'AddBCC' methods for adding carbon copy and blind carbon copy recipients as well as methods for adding multiple attachments. This should all be done before using the 'SendIt' method to actually send the mail, of course. (By the way, I use J&S Software's killer Mail Merge templates to create the text for customized email messages in my production applications. It makes a great pair with the Princen templates.)

So, as you can see, you may need to use a certain amount of embed code when using SendMail for some tasks but the simplicity of the class makes it quite easy to work with (and much easier than using MAPI or trying to do it yourself!).

On the user's end, all they need to have on their machines is the appropriate Winsock.dll and a way of connecting to the Internet (some kind of dial-up account or direct network access). You don't have to worry about them having their Windows Inbox set up, profiles or a host of other potential support problems which can plague you if you use MAPI.

I did find one oversight on Princen's part: the SendMail templates do not automatically add the email DLL to the ship list for your application (the SHP file lists all of the components that are required to run your application).

Performance

How fast the template sends mail will depend to some extent on three things: 1) how fast your machine can generate mail, 2) how fast your connection is to your mail server, and 3) how fast the mail server can process the mail you are sending it. Given all of that, I found SendMail to be reasonably fast even over a 28.8 connection (sending over 1,200 5K messages in about 45 minutes).

SendMail handled errors gracefully if, for example, it couldn't make a connection (I purposefully entered a non-existent server name). Error messages were plain and to the point, e.g., "Failed to connect: mail server was not found".

I did experience some random strange behavior (GPF's) in the demo programs, but was never able to pin down exactly why they occurred. Most of the time, the demos worked fine. In my applications, I had no problems with SendMail at all, even on cranky machines that constantly GPF'ed if you tried to send mail using MAPI.

Documentation

Princen provides a 26 page printable manual, as well as a printable Frequently Asked Questions (FAQ) document. They do an excellent job of documenting the templates and all of the associated SendMail class methods and properties. This is great, because even where there aren't templates to accomplish a given task, you can generally do it yourself in a few lines of code.

The only gotcha was that they were set up to print on European A4 size paper, which is longer than the standard U.S. 8 ½"x11" paper. A little tweaking in Word's page setup got me around that, but it should be fixed for non-European customers.

In addition to the manual, two demo applications are provided which demonstrate how the templates and SendMail classes can be used. They are also a useful source of procedures which you can copy into your own applications and modify, though you have to watch out for the odd window title or tool tip which wasn't translated from Dutch to English. I also found that the demos were pre-compiled as 16-bit programs, and therefore needed a 16-bit Winsock.dll (which I don't have on my system anymore). Re-compiling them as 32-bit fixed that right up, though, and you'll want to open them up and look around in the example code anyway.

Technical Support

Technical support was provided via email, and I got an answer to my questions within 24 hours each time I tried it. Given that Princen is located in Europe (the Netherlands) and I am in the U.S., that rated them a top mark for support.

Summary

There is an old adage about doing one thing and doing it well, and I found that it applies quite nicely to the Princen Send Internet Mail templates. They have but one purpose, and they accomplish that purpose in fine style. The class design is logical, and they encapsulate a whole lot of very complex tasks behind a very easy to use set of methods. As mentioned above, all the nasty work of encoding attachments, creating HTML mail and so forth is handled transparently – you just tell it which files to send and that's it.

Could they be improved? Well, I'd love to see a few more code templates, especially for integrating SendMail in a Process (this could easily be done simply by creating a couple new templates out of the existing 'Send Internet Mail' one). They might also do a bit more work on bulletproofing the demo applications.

So are these templates for everybody? Nope. If, for example, you need to use cc:Mail or CompuServe mail directly (i.e., not through the Internet), or you also want to receive mail, they aren't for you. But if you have any need to send email through the Internet, I highly recommend that you check them out.

I must confess, in fact, that I actually use both SendMail and MAPI templates in some applications simply because it is so much easier to send mail (and avoid the MAPI layer) using the Princen product. Well done, Princen!

Category	Product Score
Ability to do the task	Excellent
Ease of use	Very Good
Ease of Installation	Excellent
Documentation	Very Good
Technical Support	Excellent
Modifies Shipping Templates	No
Black-Box DLLs/LIBs	Yes

The Princen IT Send Internet Mail templates are available for $99 USD direct from Princen via the Internet (MasterCard only) or through the TopSpeed Accessories Program (1-800-354-5444). Versions for CW 2.x, C4/Clarion and C4/ABC are all included.

More information and downloadable demos are available at the Princen web site at http://www.princen-it.nl/clarion or from the Accessories pages at the TopSpeed web site http://www.topspeed.com.

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942