Versión en español de este artículo

An easy way to send email from a Visual FoxPro application

Use this simple technique to help your users compose and send email messages

The most popular topic in our advanced Advanced Visual FoxPro course explains how to send and receive emails automatically from within a VFP application. We show how to do this by using Microsoft Outlook as an ActiveX Automation server. Although this works very well, the technique is somewhat complicated, and you can only use it if the user has Outlook installed.

In this article, we will describe a much simpler approach - one that works with any MAPI-compliant email client (such as Outlook Express). It is not as flexible as the ActiveX Automation method, but it has the advantage of requiring only a couple of lines of code.

The trick is to "shell execute" a mailto link. If you haven't used the ShellExecute() function before, it's worth taking a moment to get to know it. It is not a VFP function, but is part of the Windows shell. Before you can use it, you must declare it, like so:

DECLARE INTEGER ShellExecute IN shell32.dll ; 
  INTEGER hndWin, STRING cAction, STRING cFileName, ; 
  STRING cParams, STRING cDir, INTEGER nShowWin

You can put this code anywhere in your application, provided it is executed before you create the email message. (Note that ShellExecute is case-sensitive in the above command.)

So what does it do?

Essentially, ShellExecute() lets you "execute" any pogram, document or shortcut. At its simplest, it can be used to launch an external application. For example, this command will launch Notepad:

ShellExecute(0,"open","Notepad.Exe","","",1)

Alternatively, you could use the following code to launch Notepad and have it open a file called Readme.txt:

ShellExecute(0,"open","Readme.txt","","",1)

And this will launch Word and open Disclaimer.RTF:

ShellExecute(0,"open","Disclaimer.RTF","","",1)

The beauty of this is that you don't have to know which application is registered to open a specific document type on the user's system. If the user didn't have Word installed, the above code would launch Wordpad instead, as this can also process RTF files. Of course, if the user had no application at all associated with RTFs, the command would fail.

The second parameter to ShellExecute() lets you specify the action that you want to execute. By changing it to "print", for example, you can print the document rather than open it for editing. Similarly, the following code will play a sound file (using either the Windows Media Player or whatever other application is associated with the WAV extension):

ShellExecute(0,"play","ringin.wav","","",1)

Another possibility:

ShellExecute(0,"open","www.microsoft.com","","",1)

This will launch the user's default web browser and navigate to the site specified.

For more examples of this versatile function, see our article, Introducing ShellExecute().

What about email?

So, back to our original requirement. To create an email message, all you have to do is ShellExecute a mailto link. At its simplest, the link looks something like this:

mailto:john@mycompany.com

So the following code will open a message composing window in the user's default mail client, with the To line already filled in: 

lcMail = "mailto:john@mycompany.com" 
ShellExecute(0,"open",lcMail,"","",1)

Going further, you can specify the following parameters to the mailto link:

Place a question mark before the first of these parameters (right after the email address). Use ampersands to separate further parameters, as in this example:

lcMail = "mailto:john@mycompany.com"+ ;
  "?CC= boss@mycompany.com&Subject= Meet for lunch"+ ;
   "&Body= Please join me for a sandwich at noon." 

ShellExecute(0,"open",lcMail,"","",1)

This will produce the message composing window shown in Figure 1. As you can see, the To, CC and Subject lines are already filled in, as is the text of the message. All that the user has to do is to click the Send button.

Figure 1: Use ShellExecute() to pop up this message window.

If you want to include a line break in the body of the message, insert the new-line character in "URL format", that is, as "%0A" (without the quotes). For example: 

lcMail = "mailto:john@mycompany.com"+ ;
  "?CC= boss@mycompany.com&Subject= Meet for lunch"+ ;
   "&Body= Please join me for sandwich.%0AWe can meet at noon."
ShellExecute(0,"open",lcMail,"","",1)

Limitations

This technique has some obvious limitation. First, it is not suitable for creating very long messages, as the entire mailto link is subject to a maximum of 2,047 characters. It cannot be used to create formatted messages, nor is it possible to add attachments to the message. More seriously, you have to rely on the user to actually send the message. You can't do that programmatically, nor can you prevent the user from cancelling the message rather than sending it.

On the other hand, if all you need is a simple way of helping the user to compose and send an unformatted message without attachments, the technique will work extremely well. You could use it, for example, to create a message which confirms an order or one which chases a customer for payment. It is especially useful if you want to let the user edit the text before hitting the Send button.

Mike Lewis Consultants Ltd. February 2002. Revised April 2005.