SimpleMail
User Manual

Version 3.1 SP4
Documentation Version 3.1 SP4

Welcome

Welcome to SimpleMail from Adiscon GmbH.

This ActiveX control empowers your applications as well as your ASP pages to send Internet mail messages. It also supports enhanced features like attachments, MIME and HTML mail. It offers high performance, ease of use and a very competitive low price. SimpleMail was created for our own internal use and is used intensive inside our own ASP applications. It was developed based on real world need and we hope, you'll find it useful as well.

This documentation covers the version 3.1. Any comments are appreciated at info@Adiscon.com.  For technical support, please contact support@adiscon.com.

Product updates as well as important announcements can be found at http://www.simplemail.adiscon.com (if that URL ever changes, please try http://www.Adiscon.com).

Installation

SimpleMail is a high performing tool using only minimal system resources. It also doesn’t require an extended installation process.

System Requirements

SimpleMail is developed under Windows NT 4.0 and Windows 2000. Although not extensively tested under Windows 95, 98 or Millenium Edition, we do not see any reason why it shouldn’t perform well in this environment. Under Windows NT 4 service pack 4 is required for the setup program. We also conducted successful tests under Windows XP beta 2.

The freely downloadable version is available for Intel X86 platforms only. Versions for the DEC Alpha platform are available to registered users free of charge. Please allow up to 4 days for delivery of the ALPHA version. Due to low demand, we have stopped compiling the ALPHA builds without request. So we will create a version as soon as the first customer asks for it. This is why we need a slight delay. Version 1.6 is instantly available for ALPHA and will be sent prior to the current version.

The Installation Process

Actual installation is very straightforward

1. download the install set
2. run it on your machine
3. follow the on-screen instructions (we use a standard windows setup script)

After finishing this simple steps, SimpleMail is set up and ready to run.

If you have downloaded a ZIP file, be sure to unzip the install set using a Win32 version of PKUNZIP or WinZip (available at http://www.pkware.com or http://www.winzip.com). The install set contains files with long names. If you use a non-Win32 version, this names will be lost and installation will fail. Also be sure not to move the .dll to any other directory. This will cause the ActiveX control to fail. If you need to change directories, uninstall SimpleMail first and re-install it from the new directory.

Uninstallation

This is also very straightforward. Just go to control panel and remove the SimpleMail product.

Usage

SimpleMail needs no further customization - it can be used right after installation. SimpleMail is a standard ActiveX control. It can be called from any ActiveX compatible container application, most notable the IIS' ASP processor as well as Visual Basic (VB).

Use it as follows:

1. Instantiate the control (e. g. with CreateObject)
2. fill in the correct property values
3. call the SendEx method 
4. you can re-specify properties and call the sent method as often as you want without re-instantiating the control.
5. be sure to destroy the control as soon as you are done (not required by SimpleMail but generally good programming practice).

Properties

Methods

• AttachFile
• AttachFileWithContentType
• ResetAttachments
• Send
• SendEx

AttachFile(LocalFileName, FileDisplayName)

This method attaches the local file name "LocalFileName" to the email to be send. Inside the mail, it will be named "FileDisplayName". The later one should not include a path name.

AttachFile can be called multiple times. Every time it is called, a new file is attached. So if you'd like to attach multiple files, simply call AttachFile for each file.

The attached file information is stored as long as the control is kept active (instantiated). Once a file has been attached, it will be send with each successive Send() or SendEx() call. Use ResetAttachments() to destroy the attachment information.

The default Content-type that will internally be used is always "application/octet-stream" for this function.

Important: File attachments are only supported in processing mode 2 (MIME). They are simply ignored in modes 0 and 1.

AttachFileWithContentType(LocalFileName, FileDisplayName, ContentType)

This method is almost similar to AttachFile(), expect that you can additionally specify the ContentType for the Attachment. Be careful to choose the correct ContentType, an invalid or empty one can cause problems with the emailclient reading emails from SimpleMail.

Below is a short list of known and possible Content-Types:

Important: File attachments are only supported in processing mode 2 (MIME). They are simply ignored in modes 1 and 2.

ResetAttachments()

This method removes all attachments associated with the email.

Send

This is the only method for all versions up to 1.3. All properties must be set before calling the send-method. Once the method is invoked, it sends the mail message according to the given parameters. There is no feedback about the outcome of the operation.

SendEx()

Same as Send(), except that it returns either 0 (OK) or -1 (error occurred). If an error occurred, the read-only property LastStatus contains the SMTP error code.

The SendEx() method is only available with version 1.4 and above.

ASP Sample

This is a simple basic page with hardcoded parameters.

<%@ LANGUAGE="VBSCRIPT" %>
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; 
charset=iso-8859-1">
<title>ASP Sample Mailer</title>
</head>
<body>
<p>We are sending mail according to your hardcoded parameters.
<p>
<%
set o = Server.CreateObject("ADISCON.SimpleMail.1") ' create mailer!

o.MailServer = "127.0.0.1"
o.Sender = "Test@Test.com"
o.Recipient = "SomeOne@SomeCompany.Com"
o.Subject = "My first SimpleMail mail"
o.MessageText = "Line 1" + Chr(13) + Chr(10) + "Line 2"
' of course, this could also be somethig like this:
' o.MessageText = Request("strMessage")

call o.Send

set o = Nothing
%>
</body>
</html>

VB Sample

The following sample is a snippet of VB code. It does all its work with constants. Of course. you can substitute variables for any of this constants.

Private Sub Command1_Click()
Dim o As Object

MousePointer = 11

Set o = CreateObject("ADISCON.SimpleMail.1")
o.MailServer = "127.0.0.1"  ' Address of SMTP-Server
o.Sender = "Test@Test.com"
o.Recipient = "SomeOne@SomeCompany.Com"
o.Subject = "My first SimpleMail mail"
o.MessageText = "Line 1" + vbCrLf + "Line 2"
Call o.send

Set o = Nothing    ' de-instanciate control

MousePointer = 0
End Sub

Common SMTP Status Codes

This chapter lists common SMTP status codes as seen in the "LastStatus" property. These are derived from RFC821.

The exact status codes themselves depend on the mail server talking to. As a general rule, a status beginning with 2 means the operation succeeded, while a status beginning with 5 means it failed. More complete information can be found in RFC821.

We encourage users to act on the "LastStatus" property only if the actual codes are well know. For error reporting, please use the "LastStatusMessage" property. This read-only property holds the status code as well as a descriptive message. That message was generated by the SMTP server and as such can be assumed to point to the exact cause of the problem.

Support

Product support is available via our private internet newsserver at news://news.adiscon.com/adiscon.products.simplemail. Email support is available via  support@adiscon.com. There is also a FAQ and some helpful information at http://www.simplemail.adiscon.com/

We strongly encourage our users to use the newsserver. 

Version History

This short history shall provide you with some background information about the versions available. The file "whatsnew.txt" from the install set does also include version information (a bit more verbose for some versions).

1.0

This is the initial release.

1.1 to 1.3

This were private builds not available to the public.

1.4

Released November, 14th 1998.

• new method SendEx()
• new property LastStatus
• now writes a date header
• fixed some bugs:
• fixed a bug causing disconnect to fail
• HELO string now reports correct server
• some minor optimizations

1.5

Released May, 2nd 1999.

• fixed some minor problems
• changed date reporting to use 4 digit dates

1.6

Released November, 14th 1999.

This product has been delivered to some customers since September, 16th 1999.

• fixed a bug which caused IP sockets to remain open after sending mail. This caused a resource leak in high volume environments.
• SimpleMail now allows easy integration into VB setup wizard
• added 3 new properties: Port, RecipientName, SenderName

2.0

Released December, 16th 1999.

• fixed a bug that could cause page faults when using the "senderName" property (rare case)
• added functionality: single CC recipient / name possible
  

2.01

Released December, 18th 1999.

• fixed a bug that caused invalid SMTP error codes to be reported
• added read-only property "LastStatusMessage" --> holds complete error message in case SMTP error occurs
  

2.02 (Build 107)

Released January, 15th 2000

• fixed a bug that caused an invalid date/time header to be written if we were in minute 0 to 9 of each hour (e. g. "9:03 am" was written as "9: 3" - notice the space after the colon).  
• fixed file version information
  This was visible if right-clicking SimpleMail.dll in Windows Explorer and then selecting properties. The Version tab specified version 1.6. This was incorrect, the actual version was 2.0/2.01 (as specified in the X-Mailer header). However, it was confusing. The version reported in the version property is now correct. Please note the the 4th number indicates the build ID (107 in this case).

2.1 (Build 108)

Released February, 17th 2000.

• first version supporting the "ProcessingMode" property (for details please see property documentation)
• new property "CustomHeaders" added
• new property "BCCRecipient" added

2.11 (Build 109)

Released March, 19th 2000.

• new property "LineLength" added

2.2 (Build 110)

Released June, 22nd 2000.

• fixed a bug that caused very large strings (e.g. URLs) to be truncated in processing modes other than 0 when the string length was larger than the maximum line length.

2.3 (Build 111)

This was a private bug-fixing build issued upon request.

• fixed a bug that caused connections to some mail-servers to stall. This was the case of the mail server sent a multi-line hello message. 

2.4 (Build 112)

Released November, 2nd 2000.

• this build contains all 2.3 enhancements
• Date format changed. The date is now formatted in local time. Previous versions used UTC. That was perfectly according to the SMTP RFC, however, some mail services (like Yahoo) did not correctly convert the date stamp to local time. So we are now using the senders local time to create a more consistent user experience.

2.5 (Build 113)

Released November, 20th 2000.

• Added a client configuration program to allow easy configuration of the default parameters
• Client configuration programs with quick-test screen to check SimpleMail and Mailserver setup.
• SimpleMail can now read default parameters (like the Mailserver) from the registry - thus there is no need to code these values into the actual script.
• Fixed a problem that could cause SimpleMail to abort when the connect  to the SMTP server failed.
• Support for Remote Data Service (RDS) added
• Greatly enhanced setup program
• Adiscon SimpleMail is now being licensed via a license name/license key pair - so the actual product is the same for both the trial version as well as the fully registered one. 

2.6 (Build 114)

Released 2001-04-27.

• fixed a bug that could case the email time stamp to become corrupted
• added the errors-to header
• enhanced setup via Windows installer and install shield

3.0 (Build 115) Beta 1

Released 2001-05-25.

• support for MIME added
• support for HTML mail added
• support for file attachments added
• corrected a few minor bugs

3.0 (Build 116) Final

Released 2001-06-01.

• fixed a bug that occurred if a mail server refuses the connection immediately after connecting. 

3.1 (Build 119) Final

Released 2002-05-16.

• Added support for SMTP Authentication (Method AUTH Login is supported). We decided to add this feature by customer requests and because many ISP's require authentication.    

3.1 SP1 (Build 120) Final

Released 2003-02-21.

• Fixed minor bugs which occurred if some Properties were not initialized correctly. 

3.1 SP2 (Build 121) Final

Released 2003-07-16.

• Fixed a bug in the MIME Handling. When the Messagetext or MessageHTMLText property was set to an empty string, the send email contained mime part for it. That caused various Mailclients to display an empty email.

3.1 SP3 (Build 122) Final

Released 2004-01-06.

• Fixed memory leaks when using SMTP authentication. On a system (IIS WebServer) with a high load, this could cause a high memory usage of dllhost.exe.

3.1 SP4 (Build 125) Final

Released 2005-01-20.

• Added a new Method called "AttachFileWithContentType". Using this method, you can add attachments and customize the content-type. See the manual for more details and a list of possible content-types.

How to obtain Updates

Please visit our web site http://www.simplemail.adiscon.com/ for information about new and updated products. Registered users will receive notification of new versions via email.

License

SimpleMail is distributed as Shareware. You are free to use the product for evaluation. However, if you feel comfortable with it and plan to use it for an extended period of time, you must register with Adiscon and pay the license fee.

Please support further development by registering the product. There is a license fee per Windows system (CPU) SimpleMail is running on. For orders outside of the European community, the fee is $US 39 (plus tax if applicable). European community  orders are EUR 57 incl. 16% VAT. European Community residents with VAT identification number should state this number in order to get an tax exemption. If not stated, full VAT will be charged.

You need a separate license for each system (CPU) SimpleMail is running on. If you intend to use SimpleMail on 5 systems, you need to purchase 5 licenses.

BBS sysops feel free to include the distribution set of this product in your library. Please be sure to include the full set (program & this documentation). Any questions can be directed to Info@Adiscon.com.

SimpleMail is not licensed for sending mass unsolicited email (know as spam). Using SimpleMail for this purpose constitutes a license violation. In this case, we reserve the right to charge US$ 1,000,000 (one million) in damages.

Are there any restrictions in the unregistered version?

There are no functional restrictions. However, the product indicates its unregistered status inside the X-Mailer mail header field. This is invisible to normal users (you need to explicitly look up the mail headers inside your mail program). The unregistered release does also include a registration reminder at the end of the message body. This is in plain text and as such readable by the recipient. The evaluation period is limited to 30 days after which SimpleMail will stop processing mails.

How to register

Registration is as simple as 1-2-3:

1. Print out the following registration form
2. Please fill it in. Remember to include number of licenses requested and payment information as well as your email id.
3. Mail or fax the registration form to Adiscon.

or - even easier:

1. Visit our secure online order facility at
   http://www.simplemail.adiscon.com/en/intermediate-order.php

We accept cash (bills please – and: no faxed ones, please ;-) ) and major credit cards. We also accept payment by check if - and only if - the following criteria is met:

If you are paying in US$, your check must be drawn on an US American bank and made payable to "Rainer Gerhards" (very important, do not make payable to Adiscon GmbH!).

If you are paying in DM, your check must be drawn on a German bank and made payable to "Adiscon GmbH". Please note that the check must be drawn on a German bank. Even if you reside inside a member state of the European Community, you can not use "Euro Cheque" (EC) made payable in DM.

We apologize for the restrictions in our check acceptance policy. We were forced to introduce these by banking regulations and fees (one quick example: our bank charge DEM 20,-- for any EC check payable in DEM - this is quite a good share for a DEM 39,95 product!).

If you need an additional payment options, please contact us at Info@Adiscon.com or the below given addresses. Please note that – for your security – we generally do not accept email registrations. We strongly encourage you never to transmit your credit card information in clear text over the Internet.

Direct your registrations to:

Adiscon GmbH
Franz-Marc Strasse 144
50374 Erftstadt
Germany

Fax: +49-9349-928820
email: order@Adiscon.com
Web: http://www.Adiscon.com

Please note: due to German laws, credit card orders will be processed in German Mark (DEM). We convert US$ orders based on the current exchange rate. However, there might be a small difference to the actual price when you get your credit card bill. We are sorry for this inconvenience.

Registration/Order Form

SimpleMail Registration

* Please note: for single licenses ordered, either Intel or Alpha versions are shipped. If you tick the "Alpha platform request" for a single license, no Intel executable will be mailed.

Please be sure to specify your email address, number of licenses requested and payment information (fields in bold typeface).

Please sign below:

______________ ___________________________________________
Date                            Signature

and forward this form to

Adiscon GmbH
Franz-Marc Strasse 144
50374 Erftstadt
Germany

Fax: +49-2235-985032
Fax option for credit card  orders, only.

Liability

Please use the evaluation period to check if SimpleMail is suitable for you and your system environment. We encourage you to try SimpleMail in a test environment. We accept no liability for any damage during the evaluation period.

Liability for registered users is limited to twice the amount of the registration fee.

Other Products

To learn more about other Adiscon products, please visit http://www.adiscon.com/en/products/.

Year 2000 Compatibility

All versions of SimpleMail 2.x/3.x and above are fully year 2000 compliant. SimpleMail only uses dates to generate the "send" header, which records when the message has been send. The original SMTP RFC requests this header to be written with 2 digit years. Newer implementation allow 4 digit years. As such, SimpleMail writes 4 digit years since version 1.5. Users of SimpleMail 1.1, 1.2, 1.3 and 1.4 need to upgrade to 1.6 in order to be fully compliant. Otherwise, 2 digit years will be written. These should be correctly interpreted by most systems, but we recommend the upgrade to the most recent version. SimpleMail 1.0  is also fully compliant as it doesn't write a "send" header and as such has no date-related coding.

Copyrights

This documentation as well as the actual SimpleMail product is Copyright © 1996-2005 by Adiscon GmbH, Germany.

Microsoft, Windows and Windows NT are registered trademarks of Microsoft Corp., Redmond, WA, USA.