SMTP/POP3/IMAP Email Engine
Users Manual
(SEE_USR)
Version 5.0
April 8, 2008
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2008
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA
Voice: 1.256.881.4630
email: info@marshallsoft.com
web: www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Email Client Compatibility2 SMTP/POP3/IMAP Library Overview
1.2 Documentation Set
1.3 Technical Support
1.4 How to Purchase
1.5 Updates
1.6 Customer ID
1.7 License File
1.8 Distribution
2.1 Dynamic Link libraries3 Computer Settings
2.2 Keycode
2.3 GUI and Console Mode
2.4 Getting Started using the Library
2.5 Application Program Logic
3.1 Auto Dial4 Email Basics
3.2 MarshallSoft DUN Dialer
4.1 SMTP Servers5 Application Notes
4.2 POP3 Servers
4.3 IMAP Server
4.4 SMTP/POP3/IMAP Host Name
4.5 Email Address Format
5.1 Sending Email6 Theory of Operation
5.2 Setting User Headers
5.3 Receiving Email
5.4 Proxy Servers
5.5 Firewalls
5.6 CompuServe Mail
5.7 Microsoft Network (MSN)
5.8 Web Based Email
5.9 Secure Email
5.10 SMTP Authentication
5.11 POP3 Authentication
5.12 MIME Extensions
5.13 ISO-8859 Character Sets
5.14 Windows 1252 ands 1255 Character Sets
5.15 16-bit Character Sets
5.16 16-bit Unicode
5.17 Wide Text
5.18 Embedded HTML
5.19 Attaching Graphics Files
5.20 Downloading Attachments
5.21 Message Status
5.22 Return Receipt
5.23 Verifying Users
5.24 Connection Status
5.25 Determining An SMTP Server
5.26 Undecoded Email
5.27 Forwarding Email
5.28 Reading Email from a File
5.29 Using GMAIL
6.1 Indirect Method7 Using SEE with Other Languages
6.2 Direct Method
7.1 Using SEE with Supported Languages8 Versions of SEE
7.2 Using SEE with Unsupported Languages
8.1 Evaluation Version9 Resolving Problems
8.2 Academic Version
8.3 Professional Version
10 Legal Issues
10.1 License11 SEE Function Summary
10.2 Warranty
The SMTP/POP3/IMAP Email Engine (SEE) is a component library of functions providing easy control of the SMTP (Simple Mail Transport Protocol), POP3 (Post Office 3), and IMAP 4 (Internet Message Access Protocol) protocols. A simple interface provides the capability to quickly develop SMTP/POP3/IMAP email software applications to send and receive mail, including multiple MIME base64 and quoted-printable encoded attachments from within a Windows application. Knowledge of Winsock and TCP/IP is not needed. SMTP/POP3/IMAP email functions can easily be called from any program written in any programming language (such as C/C++, C++ .NET, Visual C#, Delphi, Visual Basic, VB.NET, PowerBASIC, Visual FoxPro, dBase, Xbase++, COBOL) that is capable of calling Windows API functions. This manual applies to the SMTP/POP3/IMAP Email Engine (SEE) component library for all supported programming languages. It discusses SMTP POP3 IMAP email processing as well as language independent programming issues and provides purchasing and licensing information.
We have versions of the SMTP/POP3/IMAP Email Engine SDK (SEE) for C/C++ (SEE4C), Delphi (SEE4D), Visual Basic (SEE4VB), PowerBASIC (SEE4PB), Visual FoxPro (SEE4FP), Visual dBase (SEE4DB), Alaska Xbase++ (SEE4XB), COBOL (SEE4CB), and Fortran (SEE4F). Purchase a developer license for one programming language and use it with all others. All versions of the SEE component use the same DLL (SEE32.DLL). However, the examples provided for each version are written and tested for the specified programming development language. Development time is shortened because programmers need only to learn one interface.
We also have declaration files and example programs for a few other languages (such as MATLAB). The SMTP/POP3/IMAP Email Engine DLL (SEE32.DLL) run under all versions of Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows NT, Windows 2003, Windows XP and Windows Vista).
Fully functional 60-day evaluation versions of our SMTP /POP3 IMAP Email software components are provided so that the developer can test the SEE library in their environment. The evaluation version as well as a list of the many SMTP POP3 IMAP email features provided can be found on our website at:
http://www.marshallsoft.com/email-component-library.htm
The SMTP/POP3/IMAP Email Engine component library has been tested against multiple email clients, including Eudora, Microsoft Outlook, Outlook Express, Thunderbird, Pegasus, Calypso, PM Mail 98, Actif Mail, Lotus Notes, and Netscape.
The library has also been tested against a variety of UNIX and Windows servers on our LAN and on the Internet.
The complete set of documentation is divided into three manuals which are provided in 2 formats. This is the second manual (SEE_USR) in the set.
The "x" in SEE_4x Programmer's Manual specifies the host programming language such as C for C/C++, D for Delphi, VB for Visual Basic, PB for Power BASIC, FP for FoxPro, DB for dBase, and XB for Xbase.
Each manual comes in two formats:
The SEE_4x Programmer's Manual is the programming language specific manual. All language dependent programming issues such as compiling, compilers and example programs are discussed here.
The SMTP/POP3/User's Manual (SEE_USR) discusses language independent SMTP/POP3 email processing issues. License and purchase information is also provided.
The SMTP/POP3/Reference Manual (SEE_REF) contains specific details on each individual SEE email function. It also includes an error return code list.
We want you to be successful in developing software applications using our SMTP/POP3/IMAP Email Library! We are committed to providing the best, most robust software development toolkit that we can. If you have any suggestions for enhancements or comments, please let us know.
If you are having a problem using SEE, refer to section 9.0 "Resolving Problems". If you still cannot resolve the problem, email us at
support@marshallsoft.com
To avoid having your email deleted by our Spam scanners, begin the subject with "MSC HELP" or with the product name (SEE4C, SEE4VB, etc.). Zip up any attachments and send plain ASCII text email only.
Contact us by phone at 1.256.881.4630 between 7:00 AM - 7:00 PM CST Monday-Thursday and 7:00 AM -5:00 PM Friday.
The latest versions of our products are available on our web site at
http://www.marshallsoft.com
and on our anonymous FTP site at
ftp://ftp.marshallsoft.com/pub/windows/
Registered users with a current license (12 months or less) can update to the latest DLL's at
http://www.marshallsoft.com/oem.htm
A developer license for the professional version of the SMTP/POP3/IMAP Email Library SDK (SEE) may be purchased for $115 (US dollars) for electronic delivery. This price is good for one year from the release date. The professional version DLL is also branded internally with your company name or Customer ID.
The fastest and easiest way to order is on our web site at
http://www.marshallsoft.com/order.htm
You can also order by completing INVOICE.TXT (Pro Forma invoice) and emailing (info@marshallsoft.com), mailing (see our address at top), or faxing it to us. Our fax number will be provided upon request.
Multiple copy discounts (3 or more) and site licenses are available. Please call for details.
We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, Pay Pal and Western Union payments and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet.
For credit card orders, be sure to include the account number, the expiration date, the exact name on the credit card, and the complete card billing address (the address to which the credit card bill is mailed- not the banks). The cardholder's signature is required on faxed orders.
The registered package includes:
Note that the SEE DLLs never expire.
We offer an "academic price" with a 30% discount for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. The software must be used for educational purposes.
To qualify for the discount, your school must have a web site and you must have an email address at your school. On the online order form on our web site order page, put "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments. Your order will be sent to your email address at your school.
This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing cannot be used for any commercial purpose.
When ordering SEE, a CDROM can be purchased for $10 for delivery to the, US, Canada, and Mexico. For all other destinations, the CDROM is $15.
Printed manuals (refer to Section 1.1 "Documentation Set) are the same as in the SEE evaluation version. Printed manuals with a CDROM can be purchased for $20 for delivery to the US (US Priority Mail), Canada, and Mexico. For all other destinations, printed manuals are $25.
See INVOICE.TXT or http://www.marshallsoft.com/order.htm.
When a developer license is purchased for the SMTP/POP3/IMAP Email Library SDK, the developer will be sent a new set of registered DLLs plus a license file (SEExxxx.LIC) that 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/oem.htm
After one year, the developer license must be updated to be able to download updates. The developer license can be updated for $30 if ordered within one year from the original purchase (or previous update). After one year, licenses can be updated for $55 ($75 after 3 years).
Note that the registered DLL's do not expire.
Also see file UPDATES.TXT.
The Customer ID is the 4 or 5 digits following the product name (SEE) in the license file. For example, customer 1234 will receive license file SEE1234.LIC. Provide the Customer ID in the SUBJECT of an email when contacting us for technical support (SEE4C 1234).
A license file, SEExxxx.LIC, where "xxxx" is the 4 or 5- digit customer ID is provided with each developer license. The license file is an encrypted binary file used for updating SEE as explained in section 1.6 "Updates". The license file is required in order to create (or update) the registered DLL's. The license file can be found in the /DLLS directory created after SETUP is run.
To run an application (that calls SEE functions) on another computer, the file SEE32.DLL must be copied to the Windows directory of the other computer. The Windows direction is normally \WINDOWS for Windows 95/98/ME/XP/Vista and \WINNT for Windows NT/2000. Do not attempt to "register" the DLLs.
The SMTP/POP3/IMAP Email Library SDK uses a Win32 [SEE32.DLL] dynamic link library (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 a static library that is bound at link time to each and every application that uses it.
When a developer license is purchased, the developer will receive a new set of DLL's and a keycode for your DLL's. Pass this keycode as the argument to seeAttach. The keycode will be found in the file named "KEYCODE". The keycode for the evaluation (shareware) version is 0. The keycode for the registered version will be a unique 9 or 10 digit number. Note: Your keycode is NOT your Customer ID/Registration number.
SMTP/POP3/IMAP Email Library (SEE) functions can be called from WIN32 console mode programs as well as GUI programs. A "console mode" program is a Windows 95/98/ME/NT/2000/XP/Vista WIN32 command line program running in a command window. Although console mode programs look like DOS programs, they are WIN32 programs which have access to the entire Windows address space.
The first SMTP/POP3/IMAP (SEE) function that should be called is seeAttach, which initializes the SEE library and allocates necessary resources. seeAttach is typically called in the initialization section of the application and should be called just once.
After seeAttach is called, you are ready to connect to a SMTP server with seeSmtpConnect or a POP3 server with seePop3Connect. Once connected you are ready to call the other SMTP or POP3 functions in order to send or receive email.
After sending or receiving email, the connection to the server can be closed with seeClose. seeClose should not be called if the previous seeSmtpConnect or seePop3Connect failed.
Before exiting the application, seeRelease should be called. seeRelease should not be called if seeAttach failed.
The best way to get familiar with SEE is to try out one of the example programs. The example programs are described in the SEE_4x Programmer's Manual. The "x" in SEE_4x specifies the host language such as C for C/C++, VB for Visual Basic, etc. the example source is written in.
Application programs developed using the SMTP/POP3/IMAP Email library should follow this logic:
SENDING MAIL:
seeAttach
seeSmtpConnect
LOOP
Any SMTP command such as seeSendEmail
END-LOOP
seeClose
seeRelease
CHECKING MAIL:
seeAttach
seePop3Connect (or seeImapConnect)
LOOP
Any POP3 (or IMAP) command such as seeGetEmailFile
END-LOOP
seeClose
seeRelease
CHECK MAIL THEN SEND MAIL
seeAttach
seePop3Connect (or seeImapConnect)
LOOP
Any POP3 (or IMAP) command such as seeGetEmailFile
END-LOOP
seeClose
seeSmtpConnect
LOOP
Any SMTP command such as seeSendEmail
END-LOOP
seeClose
seeRelease
Changes to a Windows computer are not necessary in order to run programs calling SMTP/POP3/IMAP Email functions. However, there are changes that some users find useful.
To allow Dial-Up Networking (DUN) to dial up an ISP when only the Winsock (WIN32 only) is accessed:
HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/EnableAutod ial
HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/EnableAutod isconnect.
HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/DisconnectI dleTime
This changes the idle time (until disconnect) from 20 minutes (hex 14) to one minute.
Windows NT users can control auto dialing by editing the setting in the "Dial-Up Networking" (DUN) window. Choose "More", "User Preferences", then "Appearance".
The Dial-Up Networking window can also be displayed by executing RASPHONE.EXE.
Start Windows help, then type "autodial", then click "configuring". Follow all directions, including "notes". Note that the "Remote Access Auto Connection Manager" must be enabled.
Instead of using the "auto dial" feature of Windows, the MarshallSoft DUN Dialer (MDD) component library can be used to dial up (and hang up) under program control. MDD works under all Windows 32-bit operating systems (Win 95, 98, Me, NT, 2000, XP/VISTA).
Refer to the MDD product page at http://www.marshallsoft.com/mdd4c.htm (for Visual C++) http://www.marshallsoft.com/mdd4vb.htm (for Visual Basic), etc.
An email account is normally hosted on a computer that has a permanent connection to the Internet. Outgoing email is sent over the Internet using the SMTP (Simple Mail Transport Protocol) and is stored in mass storage until retrieved using the POP3 (Post Office Protocol 3) or IMAP (Internet Message Access Protocol) protocol. POP3 is a subset of IMAP, so that the POP3 protocol can be used to download email from an IMAP server.
The SMTP/POP3/IMAP Email Engine (SEE) component library is an "email client" and is used to send and receive email using the SMTP and POP3 protocols.
In order to connect to a SMTP server, the host name (or IP address) must be known.
An SMTP server uses "well known port" 25, although other ports can be used. Many SMTP servers also support port 576 for sending email. The function seeIntegerParam provides the capability to set the SMTP port.
An SMTP server does not require a user name or password, and therefore most SMTP servers require that you be locally connected or the email will be refused and a "relaying denied" error returned. Some SMTP servers (known as Extended SMTP servers) support "SMTP Authentication" in which a user name and password are used so that the client doesn't have to be locally connected. Refer to Section 5.11, "SMTP Authentication".
In order to connect to a POP3 server, the host name (or IP address), user name, and password for the POP3 account must be known.
A POP3 server hosts your email account. It uses "well known port 110", although other ports can be used. The function seeIntegerParam provides the capability to set the POP3 port.
The seePop3Source function can be use to read an (undecoded) email message directly from a file. Refer to Section 5.28, "Reading Email from a File".
In order to connect to an IMAP server, the host name (or IP address), user name, and password for the IMAP account must be known.
An IMAP server hosts your email account. It uses "well known port 143", although other ports can be used. The function seeIntegerParam provides the capability to set the IMAP port.
The seeImapSource function can be use to read an (undecoded) email message directly from a file. Refer to Section 5.28, "Reading Email from a File".
In order to send or receive email, you must know the name (or IP address) of the server. All email client programs (Eudora, Outlook, etc.) must have this name in order to send email. Note that any SMTP server that will accept your email can be used to send email.
Typically, the email server name will be "mail.XXX.YYY" where XXX.YYY is the name of the computer which hosts your email account. If you aren't sure of the email host name, look in the setup of your email client program (see Section 5.26 "Determining your SMTP Server) or ask your system administrator.
Email addresses are always specified as "xxx<yyy@zzz>" where
For example, the email address for Technical Support can be specified by any of the following:
Multiple email addresses can be strung together separated by semicolons, as in:
"<mike@myisp.com>;<pam@myisp.com>;<lauren@myisp.com>"
See the example programs for more samples of email address usage.
NOTE: All text delimiters in SEE were changed to the semicolon in SEE version 3.6.1.
Refer to the seeSendEmail (and seeSendHTML ) functions in the SEE Reference Manual (SEE_REF) for more details on sending email. (http://www.marshallsoft.com/see_ref.htm). Also refer to the MAILER example program.
One or more headers can be added by calling seeStringParam with parameter name SEE_ADD_HEADER. For example, the following adds two headers to all outgoing email:
seeStringParam(0,SEE_ADD_HEADER, "X-Priority: Normal")
seeStringParam(0,SEE_ADD_HEADER, "X-Sender: MarshallSoft Computing")
In order to remove all user added headers, pass a string (use SEE_SET_HEADER rather than SEE_ADD_HEADER) with the first character as a binary zero (null string).
In order to receive email, you must first connect to the POP3 server. Once connected, the email messages in an account are numbered (starting with 1) and the account is locked. Email in the account is identified by this number. The account is not renumbered when email is deleted, but it is renumbered after being closed.
Only one connection to your POP3 account is allowed at any one time. Once connected, any new arriving email is not posted until you have closed the connection.
Refer to the functions seeGetEmailFile and seeGetEmailLines in the SEE Reference Manual (SEE_REF) http://www.marshallsoft.com/see_ref.htm) for more details on receiving email. Also refer to the STATUS and READER example programs.
Connecting to a proxy server is no different from connecting to any other SMTP or POP3 server. You must know the IP address of the proxy server and the user name and password assigned by the proxy server. However, you may need to connect using a proxy specified port, rather than the standard well known SMTP and POP3 ports. These alternate ports can be specified by calling seeIntegerParam with parameter SEE_SMTP_PORT or SEE_POP3_PORT before connecting.
There is no standard method for providing connection parameters to proxy servers. Refer to the documentation for your specific proxy server.
Also see Section 5.29, "Using GMAIL".
Firewalls operate transparently with respect to TCP/IP programs, monitoring inbound and outbound traffic. Firewalls can filter packets based on their contents, source addresses, destination addresses, and port numbers. If the traffic meets criterion of the firewall, it is allowed, otherwise it is not.
In order to check CompuServe mail, POP3 mail must first be set up. Log onto CompuServe, and execute "GO POPMAIL".
MSN uses the authentication protocol "Secure Password Authentication", which is Microsoft proprietary. The protocol specification is not publicly available, which means that only a Microsoft email client can be used.
However, you can set an MSN account to operate with standard SMTP/POP3/IMAP servers, which will allow the use of SEE (as well as other standard email clients) with MSN.
Web based email services such as AOL and HOTMAIL can only be accessed by connecting with an HTTP client, such as a web browser. They do not run a (public) SMTP or POP3 server.
Some other web based email services provide POP3 servers so that web based email can be checked. For example, YAHOO runs the POP3 server:
pop.mail.yahoo.com
There are several ways to implement secure email using SEE. The first way is to use a package such as "Pretty Good Privacy" (search http://www.download.com for "PGP") to encrypt the message, optionally compress the resulting file using PKZIP or similar product, and then send the encrypted message as an attachment.
Another way to send encrypted messages with PGP is to first encrypt the message using PGP (which yields 7-bit ASCII text) then paste it directly into the message portion of the outgoing email. Once downloaded by the recipient, the encrypted portion of the message is decrypted using PGP.
A "Virtual Private Network" (VPN) can also be created which automatically encrypts all data (not just email) sent over the VPN. VPN products may be either software or hardware, and are widely available. If running Windows XP, enter "VPN" in the search box of Windows HELP and SUPPORT.
SMTP authentication requires connection to an ESMTP (Extended SMTP) server. Three forms of SMTP authentication are supported: "AUTH PLAIN", "AUTH LOGIN" and "AUTH CRAM-MD5".
"AUTH PLAIN" is fairly simple protocol supported by many SMTP servers that support authentication.
"AUTH LOGIN" is a Microsoft authentication mechanism used in Exchange Server. It is not an Internet standard nor is it covered by an RFC.
"AUTH CRAM-MD5" is based on public key encryption and is the preferred authentication protocol. It is covered by RFC2554 and RFC 2195.
To perform SMTP authentication, make the following calls before connecting:
seeIntegerParam(0, SEE_ENABLE_ESMTP, 1)
seeStringParam(0, SEE_SET_USER, your-user-name)
seeStringParam(0, SEE_SET_SECRET, your-password)
The 'secret' is normally the same as the user's password.
A particular protocol can be specified calling
seeIntegerParam(0, SEE_AUTHENTICATE_PROTOCOL, X)
where "X" is set to AUTHENTICATE_PLAIN, AUTHENTICATE_LOGIN, or AUTHENTICATE_CRAM.
POP3 authentication is performed by the use of either (1) the USER and PASS commands, or the (2) APOP command. Since the APOP command is an optional command, some POP3 servers have not implemented it.
To perform APOP authentication rather than USER/PASS, make the following call before connecting:
seeIntegerParam(0, SEE_ENABLE_APOP, 1)
Internet mail can only transport 7-bit ASCII characters. Multipurpose Internet Mail Extensions (MIME) is used to allow the attachment of binary data to an email message.
The standard MIME attachment types are "quoted-printable" and "base64". The SMTP/POP3/IMAP Email Engine library supports both.
Quoted-Printable encoding is used for three primary purposes:
To enable Quoted-Printable encoding, call
seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, QUOTED_PLAIN)
before calling seeSendEmail. To embed HTML text into an email message, which can be rendered by email clients capable of interpreting HTML (such as Outlook Express), call
seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, QUOTED_HTML)
To allow ISO-8859-1 characters in an email message, call
seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, QUOTED_8859)
To disable Quoted-Printable encoding (the default), call
seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, QUOTED_OFF)
Binary attachments are encoded using MIME base-64. Most email clients (such as made by Eudora, Netscape, and Microsoft) can decode MIME base-64 attachments.
To attach a file to an email, specify the filename as the last argument of the seeSendEmailFile function. Refer to the SMTP/POP3/IMAP Email Reference Manual (SEE_REF) for more details. Multiple attachments are listed with semicolons separating them, such as "file1.zip;file2.zip;file3.zip".
Only named attachments are decoded. To specify that unnamed attachments also be decoded, call
seeIntegerParam(0, SEE_DECODE_UNNAMED, 1)
before calling seeGetEmailFile.
ISO 8859 is a set of 10 standardized 8-bit graphic character sets:
ISO-8859-1 Latin1 (West European) ISO-8859-6 Arabic
ISO-8859-2 Latin2 (East European) ISO-8859-7 Greek
ISO-8859-3 Latin3 (South European) ISO-8859-8 Hebrew
ISO-8859-4 Latin4 (North European) ISO-8859-9 Turkish
ISO-8859-5 Cyrillic ISO-8859-10 Nordic
In order to specify ISO-8859-1for outgoing email, call (before sending email)
seeIntegerParam(0, SEE_QUOTED_PRINTABLE, QUOTED_ISO_8859_1);
For ISO-8859-8, replace 8859_1 with 8859_8 above.
For ISO-8859-1 through ISO-8859-10, replace "charset=ISO-8859-1" below with the proper ISO number. Note that the recipient's email client must be capable of displaying the selected ISO character set.
// C/C++ Example:
seeIntegerParam(0,SEE_QUOTED_PRINTABLE, QUOTED_USER);
seeStringParam(0, SEE_SET_CONTENT_TYPE,
(LPSTR)"Content-Type: text/plain; charset=ISO-8859-1");
seeStringParam(0, SEE_SET_TRANSFER_ENCODING,
(LPSTR)"Content-Transfer-Encoding: quoted-printable");
Also see http://www.marshallsoft.com/iso-8859.htm
The Windows 1252 (and Windows 1255) character sets can be specified as follows:
seeIntegerParam(0, SEE_QUOTED_PRINTABLE, QUOTED_WIN_1252); // set Windows-1252
seeIntegerParam(0, SEE_QUOTED_PRINTABLE, QUOTED_WIN_1255); // set Windows-1255
Any language that is represented by 16-bit character codes (such as Chinese, Japanese, and Korean) can be inserted into email. For example, if the body of the email contains GB2312 characters (16-bit binary Chinese character codes), the character set can be specified in the email as (C/C++ example)
Code = seeIntegerParam(0, SEE_QUOTED_PRINTABLE, QUOTED_USER);
Code = seeStringParam(0, SEE_SET_CONTENT_TYPE,
(LPSTR)"Content-Type: text/plain; charset=gb2312");
The above approach works for any defined character set such as
gb2312 Simplified Chinese
big5 Chinese
euckr Korean
koi8-r Cyrillic
ms_kanji Japanese
UTF-8 is an ASCII encoding of 16-bit Unicode. Any 16-bit Unicode text can be encoded to UTF-8 text by calling the seeEncodeUTF8 function. Conversely, UTF-8 encoded text can be decoded into 16-bit Unicode by calling the seeDecodeUTF8 function.
Note however, that the recipient's email client must be capable of decoding UTF-8 and displaying 16-bit Unicode characters. For information on Unicode, refer to:
http://www.unicode.org
Also see the CODETEST example program.
All email messages are formatted as 7-bit ASCII with each line ending in a carriage return line feed pair. Each line of text should be no more than 1000 bytes.
In order to allow wider email messages, call
seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, QUOTED_PLAIN)
before sending email. Also refer to Section 5.12.1 "Quoted-Printable Encoding".
Graphic images may be embedded within HTML encoded email by passing the image filename(s) in the seeSendHTML function. Within the HTML encoded email itself, the first image must be referenced as:
<IMG SRC="cid:message-root.1">
Additional images may be reference as "message-root.2", "message-root.3", etc. Note that the "cid:message-root" above must be in lower case.
See the HTML (or SendHTML.C for SEE4C) example program.
Attaching files ending with ".BMP", ".GIF", ".TIF", and ".JPG" are attached as image types, and therefore can be displayed by email clients (such as Eudora and Outlook, etc.) that are capable of displaying graphics files. To disable this feature, call
seeIntegerParam(Chan, SEE_ENABLE_IMAGE, 0)
To enable this feature, call
seeIntegerParam(Chan, SEE_ENABLE_IMAGE, 1)
Specify a download directory when calling seeGetEmailFile so that you don't overwrite an existing file of the same name in the current directory. This is an important security precaution.
For example (double backslashes required for C/C++ only):
seeGetEmailFile(Chan,MsgNbr,MsgName,".\\download",".\\download")
After downloading, the list of attachment filenames can be found by calling
seeDebug(Chan,SEE_GET_ATTACH_NAMES,Buffer,BufferLength)
The POP3 server typically inserts the header line
Status: U
in the header area of newly received messages. Once the email message has been read, the POP3 server changes this to
Status: R
The SMTP protocol itself has no provisions for return receipt acknowledgements. However, several headers are recognized by most SMTP servers. Older SMTP servers may recognize the header
Return-Receipt-To:
while newer SMTP servers will recognize the header:
Disposition-Notification-To:
For example:
seeStringParam(Chan, SEE_ADD_HEADER,
"Disposition-Notification-To: <info@marshallsoft.com>")
You can also send both headers.
The seeVerifyUser function can be used to verify an email account, as demonstrated in the VERUSR example program.
However, some SMTP servers may refuse to connect to non-local clients. Those that do may refuse to honor the verify request. This means that a negative verify response does NOT mean that the email address is necessarily incorrect.
If seeStatistics(Chan, SEE_GET_CONNECT_STATUS) is called and it fails because there is no live TCP/IP network, seeRelease must be called (followed by calling seeAttach again) to re-initialize the winsock layer. The problem appears to be in the Microsoft winsock code.
Rather than use SEE_GET_CONNECT_STATUS, attempt to connect to any (SMTP or POP3) email server on the net and send the NOOP command (with seeCommand):
Code = seeCommand(Chan, "NOOP")
All email clients (such as Outlook, Eudora, .etc) require a SMTP server host name (or IP address) before they can send email. If an email client is installed on a computer, the SMTP that it uses can be found. For example:
Eudora: Tools/Options/Sending Mail/SMTP Server:
Outlook Express: Tools/Accounts/Mail/Properties/Servers/Outgoing mail (SMTP)
Outlook: Tools/Options/Mail Setup/E-mail Account/View.../[Next]/Change.../Outgoing mail server (SMTP)
Mozilla Thunderbird: Tools/Account Settings.../Outgoing Server (SMTP)/Server Name:
Netscape Mail: Window/Mail & Newsgroups/Edit/Mail & Newsgroups Account Settings.../Outgoing Server (SMTP)/Server Name:
There are several ways to get an undecoded copy of (incoming) email. seeGetEmailLines can be called or an undecoded copy can be saved to disk when seeGetEmailFile is called.
In the later case, if the function
seeStringParam(Chan, SEE_SET_RAWFILE_PREFIX, prefix-character)
is called before calling seeGetEmailFile, then an undecoded copy of the email being downloaded will be saved to disk whose name consists of the email file name (3rd argument in seeGetEmailFile) prefixed by the above specified prefix character.
For example, if the underscore character "_" is specified as the prefix character, and "Email.txt" is specified in seeGetEmailFile for the message file, then the undecoded copy of the downloaded email will be save to "_Email.txt" in the same directory to which the message file is written.
See the entry for seeGetEmailLines, seeGetEmailFile, and seeStringParam (with parameter SEE_SET_RAWFILE_PREFIX) in the SEE Reference Manual (SEE_REF.*) and also the READER example program.
In order to forward email, you must have an undecoded copy of the email to be forwarded. To get an undecoded copy, refer to Section 5.27 "Undecoded Email".
The seeForward function forwards email by using the "message/rfc822" content type.
Call seeForward to forward an email to a new recipient. See the entry for seeForward in the SEE Reference Manual (SEE_REF.*) and the FORWARD example program.
The seePop3Source function can be used to specify the filename of an undecoded email message so that it can be read (and thus decoded) when seeGetEmailFile is called.
Rather than connecting to a POP3 server and reading a specific email message from the server, the function seePop3Source is called. Subsequently calling seeGetEmailFile will read and decode the email as if it were being downloaded from a POP3 server.
See the entry for seePop3Source in the SEE Reference Manual (SEE_REF) and the POP3RD example program.
If you have an account at GMAIL, it is possible to send and receive email using an SSL/TLS enabled proxy server such as the (free) STUNNEL (http://www.stunnel.org/) proxy server. See http://www.marshallsoft.com/gmail.htm
The SMTP/POP3/IMAP Email Engine component library is state driven. This means that each call to SEE functions (that access the server) is broken down into sequential steps, each of which can be performed within a second or two. There are two ways in which SEE is used: (1) indirect use of the state engine, and (2) direct use of the state engine.
The first (or "indirect") way to use the SEE library is to allow all SEE function calls to automatically call the SEE driver (seeDriver) before returning. This is the default way that SEE operates.
The major advantage of this approach is that each SEE function returns only after it has completely finished. The disadvantage of this approach is that some functions may run for a considerable amount of time during which time the calling application must wait.
Refer to the sample programs MAILER and STATUS for an example of this approach.
The second (or "direct") way that the SEE state driver is used is to call it (seeDriver) directly. In order to operate this way, the function seeIntegerParam must be called which sets the AUTO_CALL flag to off:
seeIntegerParam(Chan, SEE_AUTO_CALL_DRIVER, 0)
After the above statement is executed, the state driver (seeDriver) must be called after all other SEE functions that access the server. For example (pseudo code example),
... enable direct mode (disable indirect mode).
seeIntegerParam(Chan, SEE_AUTO_CALL_DRIVER, 0)
... connect to server.
Code = seeSmtpConnect(...)
If Code < 0 Then
... handle error here.
End If
... run the driver.
Loop
... call the driver
Code = seeDriver(Chan)
If Code < 0 Then
... handle error here.
Exit Loop
End If
If Code = 0 Then
... seeDriver has finished.
Exit Loop
End If
... display progress or do other processing here.
End Loop
... enable indirect mode (disable direct mode).
seeIntegerParam(Chan, SEE_AUTO_CALL_DRIVER, 1)
The major advantage of the direct approach is that the calling application can perform other work such as reporting the progress of large downloads. The disadvantage is the extra code that must be written to call seeDriver.
Refer to the sample program READER (or STATUS) for an example of this approach.
We have versions of SEE for C/C++ (.NET and C# .NET) (SEE4C), Delphi (SEE4D), Visual Basic (VB .NET. VBA) (SEE4VB), PowerBASIC (SEE4PB), Visual FoxPro (SEE4FP), Visual dBase (SEE4DB), Alaska Xbase++ (SEE4XB), COBOL (SEE4CB), and Fortran (SEE4F). All versions of SEE use the same.DLL (SEE32.DLL). Evaluation versions for these may be downloaded from our website at
http://www.marshallsoft.com/email-component-library.htm
The SMTP/POP3/IMAP Email Engine DLL's can also be used with any application written in any language capable of calling the Windows (95/98/Me, NT/2000/XP/Vista) API. SEE32.DLL is required for all Win32 (Windows 95/98/Me/XP/Vista/2000/NT) applications.
Once you have purchased one language version of the SMTP/POP3/IMAP Email Library SDK (SEE), you can use it with all other supported languages. Supported languages are C/C++, Visual Basic, PowerBASIC, Delphi, Visual FoxPro, Visual dBase, Xbase++, and (Fujitsu) COBOL.
For example, assume that you have previously downloaded and installed the registered version of SEE4C and now you want to also call SEE functions from Visual Basic.
The SMTP/POP3/IMAP Email Engine DLLs can be used with any application written in any language capable of calling the Windows (95/98/ME/XP/Vista, NT/2000) API. SEE32.DLL is required for all Win32 applications.
Declaration files have been defined by the following languages:
C/C++ SEE.H
Visual Basic SEE32.BAS
VBA (Excel, Access,...) SEE32.BAS
PowerBASIC SEE32.BAS [not the same as above]
Borland Delphi SEE32.PAS
Fujitsu COBOL SEE32.CBI
ABSOFT FORTRAN SEE32ABS.INC
Compaq Visual Fortran SEE32DEC.INC [formerly Digital Visual Fortran]
Visual FoxPro SEE32.FOX
Visual dBase SEE32.CC
Alaska Xbase++ SEE32.CH
Additional declaration files will be added. Give us a call if you need a declaration not listed above.
If you have interfaced SEE to an unusual programming language, email us the declaration file!
The SMTP/POP3/IMAP Email Engine (SEE) SDK library is available in three versions. All three versions have identical functionality.
The evaluation version can be differentiated from the other two versions by:
"X-OEM: EVALUATION VERSION [http://www.marshallsoft.com]"
"___________________________________________________________________"
"MarshallSoft SMTP/POP3 Engine. Programmers see www.marshallsoft.com"
The evaluation version may not be used for commercial purposes.
The academic version can be differentiated from the other two versions by:
"X-OEM-To: ACADEMIC INSTITUTE [http://www.marshallsoft.com]"
DLL's purchased with the academic discount may not be distributed, and must be used for educational purposes only.
The professional version can be differentiated from the other two versions by:
Your compiled DLLs may be distributed with your compiled applications as specified by the software license. However, the Keycode to the DLLs can NOT be distributed. The Professional version may be used for commercial purposes. Licensing information is provided in Section 10.1
does not match the keycode in the DLL's. This is caused by (1) using the evaluation keycode (value = 0) with the registered DLL, or (2) using the registered keycode with the evaluation DLL.
For example (C Example):
Code = seeSmtpConnect(0,"mail.isp.net","<support@marshallsoft.com>",NULL);
if(Code<0)
{static char Buffer[64];
seeErrorText(0,Code,Buffer,64);
printf("Error %d: %s\n", Code, Buffer);
}
Another good idea is turn on logging by calling
seeStringParam(Chan, SEE_LOG_FILE, logfilename)
We recommend the following steps if you believe that you have discovered a bug in the library:
If the problem is an error in the library and can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge.
This license agreement (LICENSE) is a legal agreement between you (either an individual or a single entity) and MarshallSoft Computing, Inc. for this software product (SOFTWARE). This agreement also governs any later releases or updates of the SOFTWARE. By installing and using the SOFTWARE, you agree to be bound by the terms of this LICENSE. If you do not agree to the terms of this LICENSE, do not install or use the SOFTWARE
MarshallSoft Computing, Inc. grants a nonexclusive license to use the SOFTWARE to the original purchaser for the purposes of designing, testing or developing software applications. Copies may be made for back-up or archival purposes only. This product is licensed for use by only one developer at a time. All developers working on a project that includes a MarshallSoft Software SDK, even though not working directly with the MarshallSoft SDK, are required to purchase a license for that MarshallSoft product.
The "academic" registered DLL's may not be distributed under any circumstances, nor may they be used for any commercial purpose.
The "professional" registered DLL's may be distributed (royalty free) in object form only, as part of the user's compiled application provided the value of the Keycode is not revealed. The registered DLL's may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission.
Note that registered DLL's do not expire. Registered users may download free updates for a period of one year from the date of purchase.
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you.
This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts.
Refer to the SMTP/POP3/IMAP Email Reference Manual (SEE_REF) for detailed information on the SEE functions. A one- line summary of each function follows.
There are 47 functions in the SMTP/POP3/IMAP Email Engine component library.
seeAbort Aborts SEE session. seeAttach Attaches SEE DLL. seeAttachmentParams Specify attachment content parameters. seeClose Closes SMTP/POP3/IMAP Email Engine. seeCommand Transmit arbitrary SMTP/POP3/IMAP command. seeDebug Returns debug information. seeDecodeBuffer Decodes base-64 buffer. seeDecodeUTF8 Decodes UTF-8 to 16-bit Unicode. SeeDecodeUU Decodes UU-encoded text. seeDeleteEmail Deletes email. seeDriver Executes next SEE state. seeEncodeBuffer Encodes base-64 buffer. seeEncodeUTF8 Encodes 16-bit Unicode to UTF-8. seeErrorText Get text associated with error code. seeExtractLine Extracts line by line number. seeExtractText Extracts line containing specified text. SeeForward Forward an email. seeForward Forwards email. seeGetEmailCount Get number of emails waiting on server. seeGetEmailFile Read email file and save to disk. seeGetEmailLines Read email lines into buffer. seeGetEmailSize Get size of email message on server. seeGetEmailUID Get email message user ID string. seeImapConnect Connects to IMAP server. seeImapCopyMBmail Copies mail between IMAP mailboxes. seeImapCreateMB Creates a mailbox. seeImapDeleteMB Deletes a mailbox. seeImapFlags Get, set, or delete IMAP message flags. seeImapListMB List all IMAP mailboxes. seeImapMsgNumber Gets message #'s from buffer filled by seeImapSearch Searches IMAP mailbox for specified keywords. seeImapRenameMB Renames a mailbox. seeImapSearch Search for IMAP messages with specified flags. seeImapSelectMB Selects IMAP mailbox. seeImapSource Specifies file from which to read IMAP email. seeIntegerParam Parameters to control how email is sent/receive. seePop3Connect Connects to POP3 server. seePop3Source Specifies file from which to read POP3 email. seeQuoteBuffer Creates ISO-8859 encoded strings. seeRelease Releases SEE. seeSendEmail Sends email and attachments. SeeSendHTML Sends HTML encoded email. seeSetErrorText Sets error message language (French, German, etc.) seeSmtpConnect Connects to SMTP server. seeStatistics Returns runtime statistics. seeStringParam Sets SEE string parameter for email control. seeVerifyFormat Check email address format. seeVerifyUser Check email address with SMTP server.