SMTP/POP3/IMAP Email Engine
Library for PowerBASIC
Programmer's Manual
(SEE4PB)
Version 5.2
April 26, 2010
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2010
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Email: info@marshallsoft.com
Web: www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Features2 Library Overview
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
2.1 Dynamic Link Libraries3 Compiler Issues
2.2 Keycode
2.3 Win32 STDCALL and DECLSPEC
2.4 Using Threads
2.5 Error Display
2.6 Editing EMAIL.INC
2.7 Adding SEE to a PowerBASIC Program
2.8 PowerBASIC Declaration Files
2.9 Include Files
3.1 PowerBASIC Console Compiler4 Example Programs
3.2 PowerBASIC DLL Compiler
3.3 PowerBASIC Windows Compiler
3.4 Compiling Example Programs
4.1 Connectionless Example Programs5 Revision History
4.2 SMTP Example Programs
4.3 POP3/IMAP Example Programs
4.4 IMAP-Only Example Programs
The SMTP/POP3/IMAP Email Engine for PowerBASIC (SEE4PB) library is a toolkit that allows software developers to quickly develop SMTP and POP3/IMAP email applications in PowerBASIC (PB/CC, PB/DLL, and PB/WIN).
The SMTP/POP3/IMAP Email Engine (SEE) is a component library of functions providing direct and simple control of the SMTP (Simple Mail Transport Protocol), POP3 (Post Office 3), and IMAP 4 (Internet Message Access Protocol) protocols.
A straightforward interface allows sending, receiving and parsing email, including multiple MIME base64 and quoted-printable encoded attachments, over any TCP/IP network (such as the Internet). Knowledge of Winsock and TCP/IP is not needed.
The SMTP/POP3/IMAP Programmer's Manual provides information needed to compile and run programs in a PowerBASIC programming environment.
The SMTP/POP3/IMAP Email Engine for PowerBASIC component library supports and has been tested with the PowerBASIC console compiler (PB/CC) and PowerBASIC for Windows (PB/DLL and PB/WIN). SEE4PB includes numerous example programs that demonstrate SMTP and POP3/IMAP used to build mail applications using the SEE4PB library.
SEE4PB runs under all versions of Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows NT, Windows XP, Windows Vista and Windows 7). The SMTP/POP3/IMAP Email Engine SDK DLLs (SEE32.DLL or SEE64.DLL) can also be used from any language (C/C++, .NET, Visual Basic, VB. NET, VBA, Delphi, Visual FoxPro, COBOL, Xbase++, dBASE, etc.) capable of calling the Windows API.
When comparing the SMTP/POP3/IMAP Email component library against our competition, note that:
MarshallSoft also has versions of the SMTP/POP3/IMAP Email Engine library for Visual Basic (SEE4VB), Delphi (SEE4D), C/C++ (SEE4C), Visual FoxPro (SEE4FP), Visual dBASE (SEE4DB), and Xbase++ (SEE4XB). All versions of the SEE library use the same DLLs (SEE32.DLL or SEE64.DLL). However, the examples provided for each version are written for the specified programming language.
The latest versions of SMTP/POP3/IMAP Email Engine (SEE) can be downloaded from our web site at
http://www.marshallsoft.com/email-component-library.htm
Our goal is to provide a robust SMTP/POP3/IMAP email component library that you and your customers can depend upon. A fully functional evaluation version is available. Contact us if you have any questions.
Some of the many features of the SMTP/POP3/IMAP Email Engine component library are as follows:
The complete set of documentation consists of three manuals in Adobe PDF format. This is the first manual (SEE_4PB) in the set.
The SEE_4PB Programmer's Manual is the language specific (PowerBASIC) manual. All PowerBASIC programming issues such as compiling, compilers and example programs are discussed in this manual. Read this manual first.
The SEE User's Manual (SEE_USR) discusses email processing as well as language independent programming issues. Purchasing and license details are also provided.
The SEE Reference Manual (SEE_REF) contains details on each individual SEE function.
The online documentation can be accessed on the SMTP/POP3/IMAP Email Engine for PowerBASIC product page at:
http://www.marshallsoft.com/see4pb.htm
The following example demonstrates the use of some of the SMTP/POP3/IMAP Email for PowerBASIC component library functions:
Dim Code As Integer
Dim xServer, xIsNull, xTo, xFrom As Asciiz * 64
Dim xSubject, xMessage As Asciiz * 64
xIsNull = Chr$(0)
xServer = "mail.yourisp.com
xFrom = "my name<me@myisp.biz>"
xTo = "<support@marshallsoft.com>"
xSubject = "PowerBASIC Test"
xMessage = "Emailed from SEE4PB!"
Code = seeAttach(1, %SEE_KEY_CODE)
If Code < 0 Then
' error calling seeAttach !
. . .
End If
Code = seeSmtpConnect(0,xServer,xFrom,xIsNull)
If Code < 0 Then
' error calling seeSmtpConnect !
. . .
End If
Code = seeSendEmail(0,xTo,xIsNull,xIsNull,xSubject,xMessage,xIsNull)
If Code < 0 Then
' error calling seeSendEmail !
. . .
End If
Code = seeClose(0)
Code = seeRelease()
In the example program above, seeAttach is called to initialize SEE and then seeSmtpConnect is called to connect to the SMTP mail host. The SMTP server host name and your email address are required, while the "Reply-To" entry is optional.
seeSendEmail is then called, passing the addressee lists. The primary addressee is provided in the "To List". The CC ("Carbon Copy") lists additional recipients, as does the BCC (Blind Carbon Copy) list. The subject contains the email subject line. The message text is next. If it starts with the '@' symbol, it is considered the name of the file containing the email message. Lastly, the filename of any ASCII or binary attachment is specified. All fields, except the first, in seeSendEmail are optional.
After returning from seeSendEmail, the seeClose function is called to close the connection to the SMTP server. Lastly, seeRelease is called to perform SEE termination processing and release the Winsock.
Note that the install process does not modify the Windows registry.
Uninstalling SEE4PB is very easy. SEE does not modify the registry.
First, run UINSTALL.BAT, which will delete SEE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me/2003/XP/Vista/Windows 7 or C:\WINNT for Windows NT/2000.
Second, delete the SEE project directory created when installing SEE4PB.
A developer license for SEE4PB can be purchased for $115. Order using INVOICE.TXT provided with the evaluation version or order directly on our web site at
http://www.marshallsoft.com/order.htm
Registration includes one year of free updates and technical support. The registered DLL never expires.
When a developer license is purchased, the developer will be sent a registered DLL plus a license file (SEExxxxx.LIC, where xxxxx is your Customer ID). The license file can be used to update the registered DLL's for a period of one year from purchase. Updates can be downloaded from
http://www.marshallsoft.com/update.htm
After one year, your license must be updated to be able to download updates, although the registered DLL never expires. The license can be updated for $30 if ordered within one year of the original purchase (or previous update). Between one year and three years, licenses can be updated for $55. After three years, a license can be updated for $75.
Note that the registered DLL does not expire; however, the ability to download version updates expires after one year. Refer to the file UPDATES.TXT located in the /SEE4PB/DOCS directory for more information.
The SMTP/POP3/IMAP Email component library has been tested on multiple computers running Windows 95/98/Me/XP/2003/Vista/Windows 7 and Windows NT/2000.
The SEE4PB library has been tested and works with the PowerBASIC Console Compiler (PBCC), the PowerBASIC DLL Compiler (PBDLL) and PowerBASIC for Windows (PB/WIN).
The SETUP installation program will copy the SEE32.DLL to the Windows directory and copies the SEE4PB files to the directory specified (default \SEE4PB). Three sub-directories are created, as follows:
DOCS - All documentation files
APPS - All example code
DLLS - All DLL's
The SEE4PB SMTP/POP3/IMAP Email library component (SEE32.DLL) is implemented as a Win32 dynamic link libraries (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library that is bound to each and every application that uses it at link time.
An important advantage that DLLs have over other "popular" library formats such as VBX or OCX is that DLLs are callable by all Windows applications. Since DLLs are the building blocks of the Windows Operating System, they will not be replaced by a "newer technology".
SEE32.DLL has a keycode encoded within it. Your keycode is a 9 or 10-digit decimal number (unless it is 0), and will be found in the file KEYCODE.PBI. The keycode for the evaluation (shareware) version is 0. You will receive a new keycode and a new SEE32.DLL after purchasing or updating a developer license. The KEYCODE is passed to SeeAttach.
If you get an error message (value -74) when calling seeAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of the SEE32.DLL from the Windows search path or delete it.
SEE32 is written in ANSI C and is compiled using the STDCALL and DECLSPEC keywords. This means that SEE4PB uses the same calling conventions and file naming conventions as the Win32 API. . In particular, function names are NOT decorated; Leading underscores and trailing "@size" strings are not added to function names.
The SEE32.DLL functions may be called by any Windows application program capable of calling the Windows API provided the proper declaration file is used.
SEE4PB is thread safe, and can be used from any Windows application capable of using threads. Refer to the TSTAT example program, which demonstrates the use of threads.
The necessary Win32 thread functions are declared in the PowerBASIC INCLUDE file "WIN32API.INC"
The error message text associated with SEE error codes can be displayed by calling seeErrorText. Each sample program contains examples of error processing.
Also see the file seeErrors.txt for a list of all Winsock and SEE error codes.
The file EMAIL.INC is included by most of the example programs and contains the following defines:
#define YOUR_EMAIL_ADDR "!your_email_address
#define SMTP_HOST_NAME "!smtp_server_name"
#define SMTP_USER_NAME "!smtp_account_name"
#define SMTP_PASSWORD "!smtp_account_password "
#define POP3_HOST_NAME "!pop3_server_name"
#define POP3_USER_NAME "!pop3_account_name"
#define POP3_PASSWORD "!pop3_account_password ".
This file must be edited with your email configuration before compiling any of the example programs. This information is required for all email clients. If you are unsure of any of these settings, look in your email client program (Outlook, Eudora, Pegasus, etc.).
SMTP_USER_NAME and SMTP_PASSWORD are required only if you will be doing SMTP authentication. They are usually the same as POP3_USER_NAME and POP3_PASSWORD. Refer to the SEE User's Manual (SEE_USR) for more information on authentication.
SMTP_HOST_NAME is the name (or IP address) of your SMTP email server. POP3_HOST_NAME is the name of your POP3 server, which is typically the same as the SMTP server. YOUR_EMAIL_ADDR is your email address. Brackets "<>" are required. POP3_USER_NAME is the account name for your email (POP3) account. POP3_PASSWORD is the password for you email (POP3) account. For example,
#define YOUR_EMAIL_ADDR "Mike Marshall<info@marshallsoft.com>"
#define SMTP_HOST_NAME "mail.yourisp.net"
#define SMTP_USER_NAME "marshallsoft"
#define SMTP_PASSWORD "qwerty"
#define POP3_HOST_NAME "mail.hiwaay.net"
#define POP3_USER_NAME "marshallsoft"
#define POP3_PASSWORD "qwerty"
#define SMTP_USER_NAME "marshallsoft"
#define SMTP_PASSWORD "qwerty"
Note that EMAIL.INC is used only in the example programs. Strings passed to SEE functions can be taken from any source (hard-coded, read from keyboard, read from file, etc.).
Not all of the #defines are used by the example programs. For example, SMTP_USER_NAME and SMTP_PASSWORD are used only by the AUTHEN example program.
In order to add SEE to a PowerBASIC program, add
$INCLUDE "SEE32.PBI"
$INCLUDE "KEYCODE.PBI"
after any other $INCLUDE statements. Then add
Code = SeeAttach(1,%SEE_KEY_CODE)
If Code < 0 Then
'... display error code to user here...
EXIT FUNCTION
END IF
as the fist executed SEE function.
SEE constants are defined and all SEE functions are declared in the file SEE32.PBI and are included in all of the example programs.
There are three include files. The first two are included by all example programs.
The SMTP/POP3/IMAP Email Engine for PowerBASIC component library supports and has been tested with the PowerBASIC Console Compiler (PBCC), the PowerBASIC DLL Compiler (PBDLL) and PowerBASIC for Windows (PB/WIN).
Most of the example programs are written for the PowerBASIC Console Compiler (PBCC). Be sure to read the comments at the beginning of each example program. Also see section 4.0 "Example Programs" below.
SEE functions can be called from programs written for the PowerBASIC DLL Compiler (PBDLL). The same DLL (SEE32.DLL) is used for both PowerBASIC and Visual Basic. SEE functions are defined in SEE32.PBI for PowerBASIC and in SEE32.BAS for Visual Basic. The Visual Basic version can be downloaded from www.marshallsoft.com/see4vb.htm
See the PB_STAT.BAS example program.
SEE functions can be called from programs written for the PowerBASIC Windows Compiler (PBWIN). There are no differences in how SEE functions are called in programs written in any of the Windows PowerBASIC compilers.
See the HELLO.BAS example program.
Twenty-six (26) example programs are included. All are compiled at the command line with the PowerBASIC Console Compiler (PBCC), except for PB_STAT what uses the PowerBASIC DLL compiler (PBDLL), and HELLO.BAS what uses the PowerBASIC Windows compiler (PBWIN).
PBCC AUTHEN.BAS
PBCC AUTO.BAS
PBCC BCAST.BAS
PBCC CODETEST.BAS
PBCC DELETE.BAS
PBCC FORWARD.BAS
PBCC GB2312.BAS
PBCC GETRAW.BAS
PBCC GMAILMVP.BAS
PBCC GMAILSVP.BAS
PBCC HTML.BAS
PBCC IMAPFLAGS.BAS
PBCC IMAPSEARCH.BAS
PBCC ISO8859.BAS
PBCC MAILER.BAS
PBCC MPARTS.BAS
PBDLL PB_STAT.BAS
PBCC POP3RD.BAS
PBCC READER.BAS
PBCC SEEVER.BAS
PBCC STAT.BAS
PBCC STATUS.BAS
PBCC TSTAT.BAS
PBCC VERUSR.BAS
Compiling programs using the PowerBASIC Console Compiler is very easy. For example, to compile MAILER.BAS, type
PBCC MAILER.BAS
PBCC programs (such as TSTAT.BAS) that reference WIN32API.INC must specify the WINAPI directory on the command line. For example, if your PowerBASIC Console Compiler is installed at C:\PBCC, you would compile TSTAT with
PBCC TSTAT.BAS -IC:\PBCC\WINAPI
Compile and run SEEVER as the first example to check your installation. SEEVER does not require a TCP/IP connection. Also see Section 4 "Example Programs" for more information on each of the example programs.
Before compiling the example programs, edit the include file EMAIL.INC with your SMTP/POP3/IMAP host and email address. Refer to Refer to Section 2.6, Editing Email.Inc, for more information on SMTP/POP3/IMAP server names.
All example programs are compiled with PBCC except for PB_STAT.BAS that is compiled with PBDLL and HELLO.BAS that is compiled with PBWIN.
Three example programs do not require a connection to a server.
The SEEVER example program displays the SEE library version number and registration string and verifies that SEE32.DLL is being found and loaded by Windows. Compile with PBCC.
The CODETEST example program demonstrates how to use seeEncodeBuffer and seeDecodeBuffer, which BASE64 encodes and decodes a test string. The CODETEST example program also demonstrates the use of seeEncodeUTF8 and seeDecodeUTF8. Compile with PBCC.
The HELLO is the same program as SEEVER except that it is compiled with the PowerBASIC Windows (PBWIN) compiler.
There are eleven SMTP email example programs. SMTP programs send email using an SMTP server. Don't forget to edit EMAIL.INC before compiling.
AUTHEN is an example program that connects to an SMTP server using SMTP Authentication. You must connect to a SMTP server that allows authentication.
AUTHEN takes no command line arguments.
AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email. AUTO will read (but not delete) all email on your server and reply to each that "your email was received".
AUTO (and TSTAT) are the only example programs that use more than one channel concurrently.
BCAST (Broadcast) emails the same message to each recipient from a file of email addresses. Along with your SMTP server and your email address, you must create the file containing the email message to send, and create another file containing the list of recipients. See BCAST.EML for an example.
The GB2312 example program sends a text message that is GB2312 (simplified Chinese) encoded. The recipient's email client will be able to display the email message using the specified GB2312 character set provided that it is capable of identifying GB2312 MIME parts (such as MS OutLook).
The HTML example program connects to an SMTP server and emails an HTML file containing inline graphics. The graphics files are attached to the HTML email message.
To email the test file (TEST.HTM with image attachments IMAGE1.GIF and IMAGE2.GIF) to address <you@my-isp.com>, type
HTML you@my-isp.com
Note that the HTML example program uses the seeSendHTML function rather than the seeSendEmail function to send the email.
The ISO8859 example program sends a text message and subject line that are ISO-8859 encoded. The recipient's email client will be able to display the email message using the specified ISO character set provided that it is capable of identifying ISO-8859 MIME parts (such as MS OutLook).
MAILER emails a message, including optional MIME attachments. All required parameters are input using a dialog box at runtime.
For example, to mail TEST.TXT with attachment TEST.ZIP to info@marshallsoft.com with subject "TEST" (Note that <> brackets are required around the email address.):
MAILER "@test.txt" TEST "<info@marshallsoft.com>" test.zip
The MPARTS example program sends a multipart MIME email in which the Content-Type headers for each attachment are specified by the programmer.
The two attachment types specified in this example are a sound file (.wav) and of PDF file (.pdf).
VERUSR (Verify User) connects to a specified SMTP server and requests verification of the user.
Due to security concerns, some SMTP servers will not honor a "verify user" request. A user that does not verify does NOT necessarily mean that the email address is not good.
The FORWARD example program forwards an (undecoded) email to a new recipient. Only undecoded email can be forwarded.
The GmailMVP (Gmail Mailer Via Proxy) example program emails a specified email message connecting to a GMAIL account via the (free) STUNNEL proxy server, which is started and terminated without user intervention. See gmail.txt in the DOCS directory or http://www.marshallsoft.com/gmail.htm for more information on STUNNEL.
There are ten POP3/IMAP email example programs. These examples read email from a POP3 (or IMAP) server. Don't forget to edit EMAIL.INC before compiling.
AUTO ("auto-responder") uses two channels concurrently to automatically respond to all new email. AUTO will read (but not delete) all email on your server and reply to each that "your email was received".
AUTO (and TSTAT) are the only example programs that use more than one channel concurrently.
The DELETE program deletes an email message from the server. Be careful! Once deleted, email messages cannot be recovered.
GETRAW is a program that downloads a specified email message without decoding it. This is used to see what the email looks like on the server. Email can also be downloaded without decoding by the READER example program.
For example, to download message 2 from the POP3 account mail.myisp.biz as user "mike" and password "qwerty", type
GETRAW "mail.myisp.biz" "mike" "qwerty" 2
The PB_STAT example program demonstrates how to call DLL's created by the PowerBASIC DLL compiler from Microsoft Visual Basic. PB_STAT.BAS is compiled by
PBDLL PB_STAT.BAS
You must also compile the Visual Basic program PB_STAT.FRM by loading PB_STAT.VBP in Visual Basic version 4.0 or above.
READER reads an email message from your server, including any MIME attachments. The email message is saved as a file.
For example, to read message 1 to file FILE1.TXT, type
READER 1 FILE1.TXT
The STAT program is the simplest POP3 example. It logs onto the POP3 server and gets the number of messages waiting.
STAT takes no command line arguments.
STATUS reads the number of email messages waiting on your POP3 server, and displays the "DATE:", "FROM:", and "SUBJECT:" header fields from each email.
STATUS takes no command line arguments.
TSTAT checks several POP3 mailboxes using multiple threads. Edit TSTAT.BAS with the POP3 accounts to check before compiling. Note that since TSTAT references the WINAPI directory, it must appear on the command line. For example (assuming PBCC is installed at C:\PBCC):
PBCC TSTAT.BAS -IC:\PBCC\WINAPI
TSTAT takes no command line arguments. Be sure to edit TSTAT.BAS before compiling.
The POP3RD example program uses the seePop3Source function to specify an (undecoded) email message file to be decoded.
The GmailSVP (Gmail Status Via Proxy) example program reads the status of each email message on a GMAIL account via the (free) STUNNEL proxy server. See gmail.txt in the DOCS directory or http://www.marshallsoft.com/gmail.htm for more information on STUNNEL.
There are two IMAP-only example programs. These examples access the IMAP server.
The ImapFlags example program tests the manipulation of flags on the IMAP server. It reads, sets, and deletes certain flags for the specified email message on the IMAP server.
IMAP flags are:
\Seen Message has been read
\Answered Message has been answered
\Flagged Message is "flagged" for urgent/special attention
\Deleted Message is "deleted" for removal by later EXPUNGE
\Draft Message has not completed composition (marked as a draft).
\Recent Message has arrived since the previous time this mailbox was
selected. ["\Recent" may be fetched but not stored]
The ImapSrch example program tests IMAP search capability.
See ImapSearch.txt or http://www.marshallsoft.com/ImapSearch.htm for a complete list of all IMAP search strings.
Example search strings as passed to seeImapSearch():
SEEN
SEEN NOT ANSWERED
FLAGGED SINCE 1-Feb-2008 NOT FROM "Smith"
LARGER 10000 NOT SEEN
The SMTP/POP3/IMAP Email Engine DLL (SEE32.DLL) is written in ANSI C. All language versions of SEE (C/C++, Delphi, Visual Basic, PowerBASIC, FoxPro, Delphi, Xbase++, COBOL, and Fortran) use the same identical DLLs.
Version 1.0: June 22, 1998.
Version 2.0: October 2, 1998.
Version 2.1: December 9, 1998.
Version 3.0: April 5, 1999.
Version 3.1: July 21, 1999.
Version 3.2: January 24, 2000.
Version 3.3: October 30, 2000
Version 3.4: August, 2001
Version 3.5: March 20, 2002
Version 3.6: April 1, 2003
Version 3.7: February 4, 2005.
Version 4.0: June 27, 2006.
Version 5.0: June 3, 2008 (Win32 Version only)
Version 5.1: June 10, 2009.
Version 5.2: April 26, 2010 (Win32) version