ActiveEmail E-mail Toolkit
Manual Pages

© 1999-2007 - ActiveXperts Software B.V.
http://www.activexperts.com
info@activexperts.com




Table of Contents

1. Introduction
2. System Requirements
3. Installation
4. Using ActiveEmail
5. Error Codes and Constants
6. SmtpServer Object
7. SmtpMail Object
8. Pop3Server Object
9. Pop3Mail Object
10. ActiveEmail Queue Server
11. Samples
12. Troubleshooting
13. Purchase and Product Activation
   
Appendix A: About MIME
Appendix B: License Agreement



1. Introduction

1.1. What is ActiveEmail?

ActiveEmail provides an easy-to-use scripting interface to SMTP and POP3 e-mail communications.
It's perfectly suited for situations in which e-mails have to be sent/received automatically, or in batches, from within applications, webservers, or from the command-line.
The performance of the engine is outstanding, due to its multi-threaded architecture and its (optional) queuing features. It has proven its strength in many business environments over the years.

ActiveEmail is an ActiveX/COM-component, that can be used in Windows programming environment, including:

1.2. ActiveEmail features

The following features are supported by ActiveEmail:

1.3. ActiveEmail Architecture

ActiveEmail is built on top of the Microsoft WinSock drivers. It does NOT replace any Windows drivers during installation; it neither adds any files or components to the Windows or Windows System directory.

The core of ActiveEmail consists of two files:

ActiveEmail can be distributed easily to many PC's. Once you have purchased the licenses, you copy the AEmail.dll to the PCs and register the DLL on that PC.



2. System Requirements

The ActiveEmail component can be used by many Windows development platforms, including:

2.1. .NET Framework

To use ActiveEmail in an ASP .NET, Visual Basic .NET or Visual C#. NET environment, the .NET Framework must be installed on the system. The .NET Framework is part of the Windows 2003 Operating System. On Windows 2000, Windows 98, Windows ME, Windows NT, Windows Server 2003, Windows XP, it's available as a separate installation. Please visit the Technology Information for the .NET Framework page to download the .NET Framework.

2.2. Internet Information Server

Internet Information Server (IIS) Setup installs the Visual Basic Script and Java Script engines.

To run ASP pages on NT4 Servers, IIS 4.x must be installed. IIS 4.x ships with the NT4 Option Pack CD's.
To run ASP pages on Windows 2000 Servers, IIS 5.x must be installed. IIS is part of the Windows 2000 Operating System.

2.3. Internet Explorer 4.x or higher

The Internet Explorer 4.x Setup (or higher) installs the Visual Basic Script and Java Script engines.
You can use the ActiveEmail component from within the client HTML code.

2.4. Windows Scripting Host

ActiveEmail can be used in VBScript scripts. VBScripts can be used by passing the script-file as a parameter to the scripting host ( either 'cscript' or 'wscript').
WSH relies on the Visual Basic Script and Java Script engines provided with Internet Explorer 4.x or later. WSH is also installed as part of Windows 98, Windows 2000, and Internet Information Services 4.0. A separate setup program is provided for Windows 95.

2.5. Visual Basic

ActiveEmail can be used in Visual Basic 5.x or higher.

2.6. Visual C++

ActiveEmail can be used in Visual C++ 5.x or higher.



3. Installation

The ActiveEmail package consists of 4 components; any combination of components can be installed:

3.1. Installation on a single computer

Simply run the AEmail.exe Setup program. The InstallShield wizard will guide you through the rest of the setup.
If you choose the ActiveEmail COM component, the Setup program can perform the registration of the COM component for you. But it will also give you the opportunity to register the object yourself;

If you choose the ActiveEmail Queue Server service, the Setup can install the service for you. But it will also give you the opportunity to install the service yourself, for instance by using the INSTSVR Resource Kit utility;

Any subsequent installation of ActiveEmail can be performed either manually or by using the Setup program.

3.2. Installation on multiple computers

Any subsequent installations can be performed using the setup program.
But since the installation of the core components is very simple, you may want to do it manually, or integrate it into your companies software distribution program.

If you choose to install the COM component manually on other machines, simply perform the following actions:
  • Copy the AEmail.dll (the ActiveEmail COM component) to a destination location on the new machine;
  • Register the COM component by using the following command: REGSVR32 <dest-location>\AEmail.dll
  • ONLY if you use queuing, make the proper registry setting as described below.

If you choose to install the Queue component manually on another machine, simply perform the following actions:
  • Copy the AEMailQ.exe (the ActiveEmail Queue Service) to a destination location on the new machine;
  • Install the service by giving the following command:INSTSVR <dest-location>\AEMailQ.exe.exe
  • Specify the Queue-directory in the registry:
        Key: HKEY_LOCAL_MACHINE\Software\ActiveXperts\ActiveEmail\PickupMailDir
        Data-type: REG_SZ
        Value: <a UNC path>
Queuing:
  • If you use queuing, ALL computers that you want to make use of the queue, must have the
      HKEY_LOCAL_MACHINE\Software\ActiveXperts\ActiveEmail\PickupMailDir
    value set. It must have the same value as the PickupMailDir value on the Queuing computer.

4. Using ActiveEmail

4.1. Introduction

The following code snippets (VBScript) illustrate how to use various ActiveEmail objects.


Send a simple e-mail message

   Set objSmtpServer          = CreateObject( "ActiveXperts.SmtpServer" ) ' Create SmtpServer object
   Set objSmtpMail            = CreateObject( "ActiveXperts.SmtpMail" )   ' Create SmtpMail object
   objSmtpServer.Connect( "smtp.mydomain.com" )                           ' Establish connection
   If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.FromAddress = "sender@mydomain.com"                     ' From (e-mail address)
      objSmtpMail.FromName    = "ActiveEmail Demo"                        ' From (name)
      objSmtpMail.Subject     = "ActiveEmail Message"
      objSmtpMail.Body        = "Hello, how are you?"
      objSmtpMail.AddTo "frank@myrecipients.com", "Frank"                 ' Add a recipient

     objSmtpServer.Send( objSmtpMail )                                    ' Send mail now
     objSmtpServer.Disconnect                                             ' Disconnect
   End If
Send an e-mail message: high priority, HTML formatted, to multiple recipients

   Set objSmtpServer          = CreateObject( "ActiveXperts.SmtpServer" ) ' Create SmtpServer object
   Set objSmtpMail            = CreateObject( "ActiveXperts.SmtpMail" )   ' Create SmtpMail object
   Set objConstants           = CreateObject( "ActiveXperts.EMailConstants" )  ' Create constants object
   objSmtpServer.Connect( "smtp.mydomain.com" )                           ' Establish connection
   If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.FromAddress = "sender@mydomain.com"                     ' From (e-mail address)
      objSmtpMail.FromName    = "ActiveEmail Demo"                        ' From (name)
      objSmtpMail.Subject     = "ActiveEmail Message"
      objSmtpMail.Priority    = objConstants.asMESSAGE_PRIORITY_HIGH      ' High priority
      objSmtpMail.BodyType    = objConstants.asMESSAGE_BODY_HTML          ' RTF/HTML body format)
      objSmtpMail.Body        = "<b>Hello, how are you?</b><br>I'm fine"
      objSmtpMail.AddTo  "frank@myrecipients.com", "Frank"                ' Add a recipient
      objSmtpMail.AddTo  "harry@myrecipients.com", "Harry"                ' Add a recipient
      objSmtpMail.AddCc  "joseph@myrecipients.com", "Joseph"              ' Add a CC recipient
      objSmtpMail.AddBcc "john@myrecipients.com", "John"                  ' Add a BCC recipient

     objSmtpServer.Send( objSmtpMail )                                    ' Send mail now
     objSmtpServer.Disconnect                                             ' Disconnect
   End If
Send an e-mail message with attachments

   Set objSmtpServer          = CreateObject( "ActiveXperts.SmtpServer" ) ' Create SmtpServer object
   Set objSmtpMail            = CreateObject( "ActiveXperts.SmtpMail" )   ' Create SmtpMail object
   objSmtpServer.Connect( "smtp.mydomain.com" )                           ' Establish connection
   If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.FromAddress = "sender@mydomain.com"                  
      objSmtpMail.FromName    = "ActiveEmail Demo"                     
      objSmtpMail.Subject     = "ActiveEmail Message"
      objSmtpMail.Body        = "Hello, how are you?"
      objSmtpMail.AddTo "frank@myrecipients.com", "Frank"              
      objSmtpMail.AddAttachment ".\picture1.jpg"                          ' Add attachment
      objSmtpMail.AddAttachment ".\picture2.jpg"                          ' Add anotherattachment

     objSmtpServer.Send( objSmtpMail )                                    ' Send mail now
     objSmtpServer.Disconnect                                             ' Disconnect
   End If
Receive e-mail headers

   Set objPop3Server = CreateObject ( "ActiveXperts.Pop3Server" )         ' Create Pop3Server object
   objPop3Server.Connect "pop3.mydomain.com", "acc", "passwd"             ' Connect to server, login using POP3 account 'acc'
   If( objPop3Server.LastError = 0 ) Then
      numMessages = objPop3Server.CountMessages()
      For i = 1 to numMessages                                            ' Iterate over all POP3 messages
         Set objPop3Mail = objPop3Server.GetEmailHeader( i )
         If ( objPop3Server.LastError = 0 ) Then
            WScript.Echo "MessageID        : " & objPop3Mail.ID
            WScript.Echo "   FromAddress   : " & objPop3Mail.FromAddress 
            WScript.Echo "   FromName      : " & objPop3Mail.FromName 
            WScript.Echo "   To            : " & objPop3Mail.ToAddress
            WScript.Echo "   Subject       : " & objPop3Mail.Subject
            WScript.Echo "   Date          : " & objPop3Mail.Date  
            WScript.Echo vbCrLf 
         End If
      Next
      objSmtpServer.Disconnect                                            ' Disconnect
   End If
Receive an e-mail

   Set objPop3Server   = CreateObject ( "ActiveXperts.Pop3Server" )       ' Create Pop3Server object
   objPop3Server.Connect "pop3.mydomain.com", "acc", "passwd"             ' Connect to server, login using POP3 account 'acc'
   If( objPop3Server.LastError = 0 ) Then

      numMessageID    = CInt( inputbox( "1", "Enter message ID (1 <= Message ID <= Count" )

      Set objPop3Mail = objPop3Server.GetEmail ( numMessageID )
      If( objPop3Server.LastError = 0 ) Then
         WScript.Echo "MessageID       : " & objPop3Mail.ID
         WScript.Echo "  From          : " & objPop3Mail.FromAddress
         WScript.Echo "  To            : " & objPop3Mail.ToAddress
         WScript.Echo "  Cc            : " & objPop3Mail.CcAddress
         WScript.Echo "  Reply Address : " & objPop3Mail.ReplyAddress	
         WScript.Echo "  Subject       : " & objPop3Mail.Subject
         WScript.Echo "  Priority      : " & objPop3Mail.Priority
         WScript.Echo "  Date          : " & objPop3Mail.Date
         WScript.Echo "  Hash          : " & objPop3Mail.Hash
         WScript.Echo "  Header        : " & Left ( objPop3Mail.Header, InStr ( objPop3Mail.Header, vbCrLf ) )	
         WScript.Echo "  Body          : " & Left ( objPop3Mail.Body, InStr ( objPop3Mail.Body, vbCrLf ) )
         WScript.Echo "  Attachments   : " & objPop3Mail.CountAttachments & vbCrLf
   
         numAttachments = objPop3Mail.CountAttachments 
         For i = 1 to numAttachments                                      ' Iterate over all attachments
           WScript.Echo "Attachment  : " & objPop3Mail.GetAttachment ( i )
         Next
      End If
      objSmtpServer.Disconnect                                            ' Disconnect
   End If

4.2. Visual Basic .NET

Make sure that the ActiveEmail Toolkit is installed on your system. For details about the installation, click here.

Add a reference to the object using the Visual Basic Solution Explorer:

Declare and create a new Constants object in the following way:
   Dim objConstants As AEMAILLib.EMailConstants            ' Declaration
   objConstants = New AEMAILLib.EMailConstants()           ' Creation

Declare and create a new SmtpServer object in the following way:
   Dim objSmtpServer As AEMAILLib.SmtpServer               ' Declaration
   objSmtpServer = New AEMAILLib.SmtpServer()              ' Creation

Declare and create a new SmtpMail object in the following way:
   Dim objSmtpMail As AEMAILLib.SmtpMail                   ' Declaration
   objSmtpMail = New AEMAILLib.SmtpMail()                  ' Creation

Declare and create a new Pop3Server object in the following way:
   Dim objPop3Server As AEMAILLib.Pop3Server               ' Declaration
   objPop3Server = New AEMAILLib.Pop3Server()              ' Creation

Declare and create a new Pop3Mail object in the following way:
   Dim objPop3Mail As AEMAILLib.Pop3Mail                   ' Declaration
   objPop3Mail = New AEMAILLib.Pop3Mail()                  ' Creation

After declaration and creation of the object(s), you can use it in your Visual Basic .NET projects.
Visual Basic .NET samples are installed as part of the product, but can also be found on the ActiveXperts web site.

4.3. Visual C# .NET

Make sure that the ActiveEmail Toolkit is installed on your system. For details about the installation, click here.

Add a reference to the object using the Visual C# Solution Explorer:

Declare and create a new Constants object in the following way:
   using AEMAILLib;
   ...
   EmailConstants objConstants = new EmailConstants()      ' Declaration and Creation

Declare and create a new SmtpServer object in the following way:
   using AEMAILLib;
   ...
   SmtpServer objSmtpServer = new SmtpServer()             ' Declaration and Creation

Declare and create a new SmtpMail object in the following way:
   using AEMAILLib;
   ...
   SmtpMail objSmtpMail = new SmtpMail()                   ' Declaration and Creation

Declare and create a new Pop3Server object in the following way:
   using AEMAILLib;
   ...
   Pop3Server objPop3Server = new Pop3Server()             ' Declaration and Creation

Declare and create a new Pop3Mail object in the following way:
   using AEMAILLib;
   ...
   Pop3Mail objPop3Mail = new Pop3Mail()                   ' Declaration and Creation

After declaration and creation of the object(s), you can use it in your Visual C# .NET projects.
Visual C# .NET samples are installed as part of the product, but can also be found on the ActiveXperts web site.

4.4. Visual Basic

Make sure that the ActiveEmail Toolkit is installed on your system. For details about the installation, click here.

ActiveEmail can be used in Visual Basic 5.x or higher. In Visual Basic, go to the 'Project/References...' menu item and check the box next to ActiveEmail Type Library. Now, you can declare and create ActiveEmail objects.

Declare and create a new Constants object in the following way:
   Dim objConstants As AEMAILLib.EmailConstants                      ' Declaration
   Set objConstants = CreateObject( "ActiveXperts.EmailConstants" )  ' Creation

Declare and create a new SmtpServer object in the following way:
   Dim objSmtpServer As AEMAILLib.SmtpServer                         ' Declaration
   Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )     ' Creation

Declare and create a new SmtpMail object in the following way:
   Dim objSmtpMail As AEMAILLib.SmtpMail                             ' Declaration
   Set objSmtpMail = CreateObject( "ActiveXperts.SmtpMail" )         ' Creation

Declare and create a new Pop3Server object in the following way:
   Dim objPop3Server As AEMAILLib.Pop3Server                         ' Declaration
   Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )     ' Creation

Declare and create a new Pop3Mail object in the following way:
   Dim objPop3Mail As AEMAILLib.Pop3Mail                             ' Declaration
   Set objPop3Mail = CreateObject( "ActiveXperts.Pop3Mail" )         ' Creation

Visual Basic samples are installed as part of the product, but can also be found on the ActiveXperts web site.

4.5. Visual C++

Make sure that the ActiveEmail Toolkit is installed on your system. For details about the installation, click here.
ActiveEmail can be used inside Visual C++ applications. Include the *.h and *.c file provided by ActiveXperts to bind your code to the ActiveEmail component.
These files are located in the Include directory of the Visual C++ samples directory. These are the files:
Declare and create a new Constants object in the following way:
   IEMailConstants *pConstants = NULL;                                    ' Declaration
   CoCreateInstance(CLSID_EMailConstants, NULL, CLSCTX_INPROC_SERVER, IID_IEMailConstants, (void**) &pConstants); 
                                                                          ' Creation

Declare and create a new SmtpServer object in the following way:
   ISmtpServer *pSmtpServer = NULL;                                       ' Declaration
   CoCreateInstance(CLSID_SmtpServer, NULL, CLSCTX_INPROC_SERVER, IID_ISmtpServer, (void**) &pSmtpServer);
                                                                          ' Creation

Declare and create a new SmtpMail object in the following way:
   ISmtpMail *pSmtpMail = NULL;                                           ' Declaration
   CoCreateInstance(CLSID_SmtpMail, NULL, CLSCTX_INPROC_SERVER, IID_ISmtpMail, (void**) &pSmtpMail); 
                                                                          ' Creation

Declare and create a new Pop3Server object in the following way:
   IPop3Server *pPop3Server = NULL;                                       ' Declaration
   CoCreateInstance(CLSID_Pop3Server, NULL, CLSCTX_INPROC_SERVER, IID_IPop3Server, (void**) &pPop3Server); 
                                                                          ' Creation

Declare and create a new Pop3Mail object in the following way:
   IPop3Mail *pPop3Mail = NULL;                                           ' Declaration
   CoCreateInstance(CLSID_Pop3Mail, NULL, CLSCTX_INPROC_SERVER, IID_IPop3Mail, (void**) &pPop3Mail); 
                                                                          ' Creation

Visual C++ samples are installed as part of the product, but can also be found on the ActiveXperts web site.

4.6. Delphi 6.x or higher

Make sure that ActiveEmail is installed on your system. For details about the installation, click here.

First, add a reference to the ActiveEmail objects:

You can create a new Constants object in the following way:
  EMailConstants : TConstants;                             ' Declaration of the wrapper class
  objConstants : IConstants;                               ' Declaration of the interface class
  objConstants := EMailConstants.DefaultInterface;         ' Creation new instance of the object
Declare and create a new SmtpServer object in the following way:
  SmtpServer : TSmtpServer;                                ' Declaration of the wrapper class
  objSmtpServer : ISmtpServer;                             ' Declaration of the interface class
  objSmtpServer := SmtpServer.DefaultInterface;            ' Creation new instance of the object
Declare and create a new SmtpMail object in the following way:
  SmtpMail : TSmtpMail;                                    ' Declaration of the wrapper class
  objSmtpMail : ISmtpMail;                                 ' Declaration of the interface class
  objSmtpMail := SmtpMail.DefaultInterface;                ' Creation new instance of the object
Declare and create a new Pop3Server object in the following way:
  Pop3Server : TPop3Server;                                ' Declaration of the wrapper class
  objPop3Server : IPop3Server;                             ' Declaration of the interface class
  objPop3Server := Pop3Server.DefaultInterface;            ' Creation new instance of the object
Declare and create a new Pop3Mail object in the following way:
  Pop3Mail : TPop3Mail;                                    ' Declaration of the wrapper class
  objPop3Mail : IPop3Mail;                                 ' Declaration of the interface class
  objPop3Mail := Pop3Mail.DefaultInterface;                ' Creation new instance of the object

4.7. ASP 2.x environment

   <html>
   <body>
   Version: 
   <script language=vbscript runat=server>
     Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )
     Response.Write objSmtpServer.Version
   </script>
   </body>
   </html>
 Visual Basic .NET samples are installed as part of the product, but can also be found on the ActiveXperts web site.

A more convenient way of embedding server side scripting (ASP) is by putting the script code inside <% and %> delimiters: 
   <html>
   <body>
   Version:
   <%
     Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer )
     Response.Write objSmtpServer.Version
   %>
   </body>
   </html>



5. Error Codes and Constants

 

5.1. Error Codes

When a function is called, the result of the function is stored in the object's 'LastError' property.
When 'LastError' is 0, it means that the last called function completed successfully; otherwise, an error occured.

The value of the LastError tells you why the function failed. All error codes are listed on the ActiveXperts web site:

www.activexperts.com/support/errorcodes (list of error codes).

Here, you can also lookup a specific error to find its description.

You can also call the 'GetErrorDescription' function of any of the objects to find the error description.
 

5.2. Constants

In ActiveEmail, all constants are grouped together in a separate object called EMailConstants. You must first create the Constants object before you can actually use constants: 
   Set objConstants = CreateObject( "ActiveXperts.EMailConstants" )
   WScript.Echo objConstants.asMESSAGE_BODY_PLAIN
   WScript.Echo objConstants.asMESSAGE_BODY_HTML
   ...
  
5.2.1. Format Values

Name Description
asMESSAGE_BODY_PLAIN Plain message body (default)
asMESSAGE_BODY_HTML Message body supports HTML tags

 
5.2.2. Priority Values

Name Description
asMESSAGE_PRIORITY_HIGHEST Highest priority
asMESSAGE_PRIORITY_HIGH High priority
asMESSAGE_PRIORITY_MEDIUM Normal priority (default)
asMESSAGE_PRIORITY_LOW Low priority
asMESSAGE_PRIORITY_LOWEST Lowest priority

 
5.2.3. Encoding Values

Name Description
asMESSAGE_ENCODING_DEFAULT Default encoding. Uses the Operating System's current codepage
asMESSAGE_ENCODING_THAI ISO-8859-11 encoding
asMESSAGE_ENCODING_JAPANESE ISO-2022-jp encoding
asMESSAGE_ENCODING_CHINESE_SIMP GB2312 encoding
asMESSAGE_ENCODING_KOREAN KSC-5601 encoding
asMESSAGE_ENCODING_CHINESE_TRAD BIG5 encoding
asMESSAGE_ENCODING_CENTRALEUROPE ISO-8859-2 encoding
asMESSAGE_ENCODING_RUSSIAN ISO-8859-5 encoding
asMESSAGE_ENCODING_WESTERN ISO-8859-1 encoding
asMESSAGE_ENCODING_GREEK ISO-8859-7 encoding
asMESSAGE_ENCODING_TURKISH ISO-8859-3 encoding
asMESSAGE_ENCODING_HEBREW ISO-8859-8 encoding
asMESSAGE_ENCODING_ARABIC ISO-8859-6 encoding
asMESSAGE_ENCODING_BALTIC ISO-8859-4 encoding
asMESSAGE_ENCODING_VIETNAMESE WINDOWS-1258 encoding
asMESSAGE_ENCODING_UTF7 UTF-7 encoding
asMESSAGE_ENCODING_UTF8 UTF-8 encoding

 
5.2.4. SMTP Authentication Values

Name Description
asAUTH_SMTP_AUTO Auto detect (default)
asAUTH_SMTP_PLAIN AUTH-PLAIN authentication
asAUTH_SMTP_LOGIN AUTH-LOGIN authentication
asAUTH_SMTP_MD5CRAM AUTH-CRAM-MD5 authentication

 
5.2.5. POP3 Authentication Values

Name Description
asAUTH_POP3_AUTO Auto detect (default)
asAUTH_POP3_PLAIN AUTH-PLAIN authentication
asAUTH_POP3_APOP APOP authentication



6. SmtpServer Object

6.1. SmtpServer Object - Introduction

The SmtpServer object can be used to connect to an SMTP server and sumbit one or more SmtpMail messages.
By default, port 25 is used to connect to the remote SMTP server. You can also specify an alternate port.

The following sample demonstrates the use of the 'SmtpServer' object (sample written in VBScript).

Send a simple e-mail message

   Set objSmtpServer          = CreateObject( "ActiveXperts.SmtpServer" ) ' Create SmtpServer object
   Set objSmtpMail            = CreateObject( "ActiveXperts.SmtpMail" )   ' Create SmtpMail object
   objSmtpServer.Connect( "smtp.mydomain.com" )                           ' Establish connection
   If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.FromAddress = "sender@mydomain.com"                     ' From (e-mail address)
      objSmtpMail.FromName    = "ActiveEmail Demo"                        ' From (name)
      objSmtpMail.Subject     = "ActiveEmail Message"                     ' Subject
      objSmtpMail.Body        = "Hello, how are you?"                     ' Body
      objSmtpMail.AddTo "frank@myrecipients.com", "Frank"                 ' Add a recipient

     objSmtpServer.Send( objSmtpMail )                                    ' Send mail now
     objSmtpServer.Disconnect                                             ' Disconnect
   End If

6.2. SmtpServer Object - Overview of Properties and Functions

Property Type In/Out Mand/Opt Description
Version String Out n/a Version number of ActiveEmail
ExpirationDate String Out n/a Expiration date of ActiveEmail
LogFile String In/Out n/a Log file, for troubleshooting purposes
HostPort Number In/Out Optional The TCP port of the SMTP server. Default: 25
Authentication Number In/Out Optional The preferred authentication mechanism
LastError String Out n/a Result of a previously called Send or Queue function
LastSmtpResponse String Out n/a Reponse of the SMTP server on last e-mail operation

Function Description
Activate Activate the product
Clear Clear all properties
Connect Connect to an SMTP server
Disconnect Disconnect SMTP session
IsConnected Get connection status
Send Send an e-mail message
GetErrorDescription Lookup error description of the given error code

6.3. SmtpServer Object - Properties


 SmtpServer::Version property

Description:
Version information of ActiveEmail. This property is read-only; you cannot assign a value to it.
Example:
    Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )        ' Create SmtpServer object
    ...
    WScript.Echo "Version: " & objSmtpServer.Version

 SmtpServer::ExpirationDate property

Description:
ExpirationDate of ActiveEmail. This property is read-only; you cannot assign a value to it. Once you have registered the product, the property holds the empty string ("") value.
Example:
    Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )        ' Create SmtpServer object
    ...
    WScript.Echo "ExpirationDate: " & objSmtpServer.ExpirationDate

 SmtpServer::LogFile property

Description:
For troubleshooting purposes, you can specify a log file to trace all SMTP operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all SMTP server operations will be written to this log file.
Example:
    Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )        ' Create SmtpServer object
    ...
    objSmtpServer.LogFile = "c:\smtp.log"                                ' Specify log file
    objSmtpServer.Connect( "smtp.mydomain.com" )
    If( objSmtpServer.LastError = 0 )
      ...
      objSmtpServer.Disconnect()
   End If

 SmtpServer::HostPort property

Description:
The 'HostPort' property specifies the port used by the Connect function to connect to a remote SMTP server. If the remote SMTP server uses a different port than port 25 (default), you can specify it by assigning a value to this property.
Example:
    Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )
    ...
    objSmtpServer.HostPort = 7025                  ' To specify an alternate port other than 25
    objSmtpServer.Connect( "smtp.myserver.com" )   ' Attempt to connect on port 7025
    ...

 SmtpServer::Authentication property

Description:
The 'Authentication' property specifies the mechanism used by the Connect function to authenticate to a remote SMTP server. By default, the ActiveEmail Toolkit uses auto-detection. For a list of valid authentication identifiers, click here.
NOTE: If you do not pass credentials to the Connect function (the 2nd and 3rd parameter of the function), the 'Authentication' property is ignored.
Example:
    Set objSmtpServer      = CreateObject( "ActiveXperts.SmtpServer" )
    Set objConstants       = CreateObject( "ActiveXperts.EMailConstants" )
    ...
    objSmtpServer.Authentication = objConstants.asAUTH_SMTP_MD5CRAM      
    objSmtpServer.Connect( "smtp.myserver.com", "userid", "passwd" )     ' Connect and authenticate using MD5/CRAM
    ...

 SmtpServer::LastError property

Description:
This read-only property indicates the result of the last called function. You should always checks the result of your functions. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription function provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.
Example:
    Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )
    ...
    objSmtpServer.Send
    WScript.Echo "Result code: " & objSmtpServer.LastError
    WScript.Echo "Result description: " & objSmtpServer.GetErrorDescription( objSmtpServer.LastError )

 SmtpServer::LastSmtpResponse property

Description:
The last response of the SMTP server. The property is read-only; you cannot assign a value to it. The property can be very useful for troubleshooting purposes: when a mail fails, the information provided by the SMTP server can explain exactly what went wrong.

If you need more advanced trace information, try the LogFile property.
Example:
    Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )
    ...
    objSmtpServer.Send
    WScript.Echo "LastError: " & objSmtpServer.LastError
    WScript.Echo "Response of SMTP Server: " & objSmtp.LastSmtpResponse

6.4. SmtpServer Object - Functions


 SmtpServer::Activate function

Description:
This functions activates the ActiveEmail Toolkit product. A valid registration key should be passed as parameter.
Parameters:
  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' function only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers (see also here).
Return value:
Always 0. Check LastError property to see if the function completed successfully
Example:
    Set objSmtpServer  = CreateObject( "ActiveXperts.SmtpServer" )
    objSmtpServer.Activate "xxxxx-xxxxx-xxxxx", True             ' Use a valid registration code
                                                                 ' Pass True to make the activation persistent, so you need to call
                                                                 ' Activate only once. If you pass False, you need to call Activate 
                                                                 ' each time the product is started.
 SmtpServer::Clear function

Description:
This function clears all properties of the object.
Parameters:
None.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objSmtpServer = CreateObject( "ActiveXperts.SmtpServer" )
    objSmtpServer.Connect( "smtp.thisdomaindoesnotexist.com" )
    WScript.Echo objSmtpServer.LastError
    objSmtpServer.Clear()
    WScript.Echo objSmtpServer.LastError

 SmtpServer::Connect function

Description:
Connects to an SMTP server on port 25 (unless HostPort is set to a different port). After you've established a connection to the mail server, you can send one or more e-mail messages.
Call Disconnect to disconnect the session when you don't want to send any more messages.

There are a few different authentication mechanisms for SMTP. ActiveEmail auto-detects the way of authentication; if you want to force the toolkit to use a particular authentication mechanism, set the Authentication property before you call 'Connect'.
Parameters:
  • Host - Hostname or IP address of the mail server
  • Account (optional) - Only required if your SMTP server requires authentication
  • Password (optional) - Only required if your SMTP server requires authentication
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example (no authentication):
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    objSmtpServer.Connect( "smtp.domainname.com" )
    If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.From    = "me@mydomain.com"
      objSmtpMail.Subject = "This is my subject"
      ...
      objSmtpServer.Send
      objSmtpServer.Disconnect
    End If
Example (authentication required by SMTP server):
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    objSmtpServer.Connect( "exchange.domainname.com", "administrator", "mypassword" )
    If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.From    = "me@mydomain.com"
      objSmtpMail.Subject = "This is my subject"
      ...
      objSmtpServer.Send
      objSmtpServer.Disconnect
    End If

 SmtpServer::Disconnect function

Description:
After you've established a connection to the mail server, you can send one or more e-mail messages.
Call 'Disconnect' to disconnect the session.
Parameters:
None.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    objSmtpServer.Connect( "smtp.domainname.com" )
    If( objSmtpServer.LastError = 0 ) Then
      ...
      objSmtp.Disconnect
    End If

 SmtpServer::IsConnected function

Description:
This function returns True (-1) if the object has a connection to an SMTP server; otherwise, False (0) is returned.
Parameters:
None.
Return value:
True (-1) or False (0).
Example:
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    objSmtpServer.Connect( "smtp.domainname.com" )
    WScript.Echo objSmtpServer.LastError
    If( objSmtpServer.IsConnected() Then )
       WScript.Echo "Connected!"
    Else
       WScript.Echo "Not connected"
    End If
    ...

 SmtpServer::Send function

Description:
This function sends a SMTP message directly to a SMTP server. You must first establish a connection to your mail server before you can call the 'Send' function.
Parameters:
  • Host - Hostname or IP address of the mail server
  • SmtpMail object - You must pass an SmtpMail object with all mandatory fields set (i.e.. at least one recipient and a sender address).
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    objSmtpServer.Connect( "smtp.domainname.com" )
    If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.From    = "me@mydomain.com"
      objSmtpMail.AddTo "john@company.com", "My Friend John"
      objSmtpMail.Subject = "This is my subject"
 	 ...
      objSmtpServer.Send( objSmtpMail )
      objSmtpServer.Disconnect
    End If

 SmtpServer::Queue function

Description:
This function puts an SMTP message into the queue. The ActiveEmail Queue Service will pick it up and send it to the SMTP server.
You do NOT need to establish a conection to the mail server first (this is done by the ActiveEmail Queue Server service).
Parameters:
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    ...
    objSmtpMail.From    = "me@mydomain.com"
    objSmtpMail.AddTo "john@company.com", "My Friend John"
    objSmtpMail.Subject = "This is my subject"
    ...
    objSmtpServer.Queue( "smtp.domainname.com", objSmtpMail )

 SmtpServer::GetErrorDescription function

Description:
Function to retrieve the explanation of an error code.
Parameters:
  • Error Code.
Return value:
The Error string.
Example:
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    objSmtpServer.Connect( "smtp.domainname.com" )
    If( objSmtpServer.LastError = 0 ) Then
      ...
      objSmtpServer.Disconnect
    Else
      WScript.Echo "Error description: " & objSmtpServer.GetErrorDescription( objSmtpServer.LastError )
    End If



7. SmtpMail Object

7.1. SmtpMail Object - Introduction

The SmtpMail object holds all properties of an SMTP message, like: recipients, subject, body, priority, attachments, etc.. The SmtpMail object can be used by SmtpServer's Send and Queue functions, where the SmtpMail object is passed as parameter.

The following sample demonstrates the use of the 'SmtpMail' object (sample written in VBScript).

Use SmtpMail object to send an e-mail

    ' Create a new SmtpMail object; assign values to properties
    Set objSmtpMail         = CreateObject( "ActiveXperts.SmtpMail" )   
    objSmtpMail.FromAddress = "sender@mydomain.com"                     ' From (e-mail address)
    objSmtpMail.FromName    = "ActiveEmail Demo"                        ' From (name)
    objSmtpMail.Subject     = "ActiveEmail Message"                     ' Subject
    objSmtpMail.Body        = "Hello, how are you?"                     ' Body
    objSmtpMail.AddTo "frank@myrecipients.com", "Frank"                 ' Add a recipient
 
    ' Create a new SmtpServer object; connect to the mail server
    Set objSmtpServer       = CreateObject( "ActiveXperts.SmtpServer" ) ' Create SmtpServer object
    objSmtpServer.Connect( "smtp.mydomain.com" )                        ' Establish connection
    If( objSmtpServer.LastError <> 0 ) Then
       WScript.Quit
    End If
 
    ' Send the message
    objSmtpServer.Send( objSmtpMail )                                   ' Send mail now
 
    objSmtpServer.Disconnect                                            ' Disconnect

7.2. SmtpMail Object - Overview of Properties and Functions

Property Type In/Out Mand/Opt Description
FromAddress String In/Out Optional The Sender's e-mail address
FromName String In/Out Optional The Sender's name
Organization String In/Out Optional The Sender's organization name
ReplyAddress String In/Out Optional The Sender's reply-address. If not specified, FromAddress will be the reply-address
ReadReceiptAddress String In/Out Optional E-mail address of the person who should receive read receipt(s) of the outgoing e-mail
Encoding Number In/Out Optional The encoding to be used. Various encodings are supported, including: Japanese, Chinese, Russian, Greek, Turkish and more
Subject String In/Out Optional The Subject of the message
Priority Number In/Out Optional The Priority of the message. There a five different priority-levels
BodyType Number In/Out Optional The Body type of the message.
Body String In/Out Optional The Body of the message
LastError String Out n/a Result of a previously called function

Function Description
Clear Clear all properties
AddTo Add an e-mail recipient
AddCc Add a Carbon Copy Recipient (CC)
AddBcc Add a Blind Carbon Copy Recipient (BCC)
AddAttachment Add an attachment
LoadMIME Load properties, recipients and attachments from a MIME file
SaveMIME Save properties, recipients and attachments to a MIME file

7.3. SmtpMail Object - Properties


 SmtpMail::FromAddress and FromName properties

Description:
The FromAddress and FromName fields specify the Sender. The FromAddress specifies the Sender's e-mail address. This is the return-path for your e-mail, unless you specify the ReplyAddress property. The ReplyAddress property always overrides the FromAddress property for it's return path. The FromName field specifies the sender's friendly name.
You can only declare one sender.
FromAddress and FromName are optional properties, because RFC 822 doesn't require a sender specification for e-mail transmissions.
Example:
    Set objSmtpMail = CreateObject( "ActiveXperts.SmtpMail" )
    ...
    objSmtpMail.From     = "me@mydomain.doc"
    objSmtpMail.FromName = "This is Me"
    ...

 SmtpMail::Organization property

Description:
The sender's organization name.
Example:
    Set objSmtpMail = CreateObject( "ActiveXperts.SmtpMail" )
    ...
    objSmtpMail.Organization = "My Organization"

 SmtpMail::ReplyAddress property

Description:
The Reply-address of the e-mail. If not specified, the reply-address will be the address indicated by the FromAddress property.
Example:
    Set objSmtpMail = CreateObject( "ActiveXperts.SmtpMail" )
    ...
    objSmtpMail.ReplyAddress = "myself@mydomain.com"

 SmtpMail::ReadReceiptAddress property

Description:
E-mail address of the person who should receive a 'read receipt'. The receipt is sent when the message recipient has displayed your message. This is useful when you are sending time-critical information, or any time you want confirmation that your message has been received.
Example:
    Set objSmtpMail = CreateObject( "ActiveXperts.SmtpMail" )
    ...
    objSmtpMail.ReadReceiptAddress = "myself@mydomain.com"

 SmtpMail::Encoding property

Description:
For a list of valid encoding values, click here.

Example:
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    Set objConstants      = CreateObject( "ActiveXperts.EMailConstants" )
    ...
    objSmtpMail.Encoding  = objConstants.asMESSAGE_ENCODING_JAPANESE     ' Message will be encoded as Japanese text

 SmtpMail::Subject property

Description:
The Subject of a message. Not mandatory.
Example:
   Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
   ...
   objSmtpMail.Subject   = "This is an important message"

 SmtpMail::Priority property

Description:
The Priority of the message. There are 5 priority levels, described here.
Example:
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    Set objConstants      = CreateObject( "ActiveXperts.EMailConstants" )
   ...
    objSmtpMail.Priority  = objConstants.asPRIORITYHIGH                  ' High priority

 SmtpMail::BodyType , SmtpMail::Body properties

Description:
Two body formats are supported by ActiveEmail
  • Clear Text format (default);
  • Rich Text Format (HTML format).

A message body in Plain Text format doesn't support any formatting capabilities; it doesn't support embedded objects either.
A message body in HTML format supports HTML text formatting tags, as well as embedded objects like images and sounds.

There are two values for the BodyType:
If you send a Plain Text message, you can include newlines by including vbCrLf characters inside you message.

If you send a HTML message, you can embed an object inside the message. The object must be added as an attachment (see also: AddAttachment).
Every attachment has a unique identifier. The first attachment has identier 000001, the second one has 000002, etc.
To embed an attached object, you must refer to the object from within the message body. This referal can be made in the following way:
   <img SRC="cid:0000001">
Example: Clear Text formatted body
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    ...
    ' Default body format: plain text, so no need to change objSmtpMail.BodyType
    objSmtpMail.Body      = "This is my body message." & vbCrLf & "Best regards."
Example: HTML formatted body
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    Set objConstants      = CreateObject( "ActiveXperts.EMailConstants" )  ' Create constants object
    ...
    objSmtpMail.BodyType  = objConstants.asMESSAGE_BODY_HTML
    objSmtpMail.Body      = "<html><body>This is my <i>body message</i>.<br>Regards.</body></html>"
Example: HTML formatted body with to embedded objects
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    Set objConstants      = CreateObject( "ActiveXperts.EMailConstants" )  ' Create constants object
    ...
    objSmtpMail.AddAttachment "C:\MySelf.jpg"
    objSmtpMail.AddAttachment "C:\MyWife.jpg"
    objSmtpMail.BodyType  = objConstants.asMESSAGE_BODY_HTML
    objSmtpMail.Body      = "<html><body>This <img SRC="cid:0000001"> is me <br>and <img SRC="cid:0000002"> my wife<br></body></html>

 SmtpMail::LastError property

Description:
This read-only property indicates the result of the last called function. You should always checks the result of your functions. A zero indicates: success. Any non-zero value means an error.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.
Example:
    Set objSmtpMail = CreateObject( "ActiveXperts.SmtpMail" )
    ...
    objSmtpMail.AddAttachment( "C:\File.txt" )
    WScript.Echo "Result code: " & objSmtpMail.LastError

7.4. SmtpMail Object - Functions


 SmtpMail::Clear function

Description:
This function clears all properties of the object. If you send multiple messages in a row, it is recommended to call this function after each call of Send or Queue.
Parameters:
None.
Return value:
Always 0.
Example:
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" ) ' Create SmtpServer object
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    objSmtpServer.Connect( "smtp.domainname.com" )
    If( objSmtpServer.LastError = 0 ) Then
      objSmtpMail.From    = "me@mydomain.com"
      objSmtpMail.AddTo "john@company.com", "My Friend John"
      objSmtpMail.Subject = "This is my subject"
      objSmtpMail.Body = "This is my message to you"
      objSmtpServer.Send( objSmtpMail )
      objSmtpMail.Clear                                               ' Clear mail properties
      objSmtpMail.From    = "me@mydomain.com"
      objSmtpMail.AddTo "michael@company.com", "My Friend Michael"
      objSmtpMail.Subject = "This is my subject"
      objSmtpMail.Body = "This is my message to you"
      objSmtpServer.Send( objSmtpMail )
      objSmtpServer.Disconnect
    End If

 SmtpMail::AddTo, SmtpMail::AddCC and SmtpMail::AddBcc, functions

Description:
Use AddTo to add a normal recipient, use AddCc to add a Carbon Copy recipient, and use AddBcc to add a Blind Carbon Copy recipient.
All three functions can be called multiple times, to add multiple recipients.
Parameters:
  • The e-mail address of the recipient;
  • The friendly name of the recipient (empty string allowed).
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    objSmtpMail.AddTo "roger@thecompany.com", "My friend Roger"
    objSmtpMail.AddTo "mike@thecompany.com", ""
 
    objSmtpMail.AddCc "dennis@thecompany.com", "My friend Dennis"
 
    objSmtpMail.AddBcc "jim@thecompany.com", ""
    objSmtpMail.AddBcc "joe@thecompany.com", "My friend Joe"

 SmtpMail::AddAttachment function

Description:
This function allows you to add one or more file attachment. These attachments can be either ASCII or binary format.
Every attachment has its own unique internal ID. You can use this ID to embed the attachment inside a Body message.
Parameters:
  • The file attachment.
Return value:
Always 0. If you specify an invalid attachment, the Send function will fail.
Example:
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    objSmtpMail.AddAttachment "c:\temp\mypicture.jpg"
    objSmtpMail.AddAttachment "c:\temp\mydocument.doc"

 SmtpMail::LoadMIME function

Description:
This function loads all properties, recipients and attachments from a MIME file. This can be a MIME file that was created by the SaveMIME function, or by another e-mail client including Microsoft Outlook Express and Microsoft Mail.
Parameters:
  • The MIME file.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    Set objSmtpServer     = CreateObject( "ActiveXperts.SmtpServer" )
    objSmtpMail.LoadMIME( "C:\File.mim" )
    WScript.Echo "LoadMIME, result: " & objSmtpMail.LastError
    ...
    objSmtpServer.Connect( "mailserver.company.intra" )
    objSmtpServer.Send( objSmtpMail )
    objSmtpServer.Disconnect()

 SmtpMail::SaveMIME function

Description:
This function saves all properties, recipients and attachments to a MIME file. This MIME file can be used at any time by the LoadMIME function, or by another e-mail client including Microsoft Outlook Express and Microsoft Mail.
Parameters:
  • The MIME file.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objSmtpMail       = CreateObject( "ActiveXperts.SmtpMail" )
    objSmtpMail.From      = "me@mydomain.com"
    objSmtpMail.AddTo "john@company.com", "My Friend John"
    objSmtpMail.Subject   = "This is my subject"
    objSmtpMail.Body      = "This is my message to you"
    objSmtpMail.AddAttachment "c:\temp\mypicture.jpg"
    objSmtpMail.AddAttachment "c:\temp\mydocument.doc"
    objSmtpMail.SaveMIME( "C:\File.mim" )
    WScript.Echo "SaveMIME, result: " & objSmtpMail.LastError



8. Pop3Server Object

8.1. Pop3Server Object - Introduction

The Pop3Server object can be used to connect to an POP3 server and sumbit one or more Pop3Mail messages.
By default, port 25 is used to connect to the remote POP3 server. You can also specify an alternate port.

The following sample demonstrates the use of the 'Pop3Server' object (sample written in VBScript).


Show the first 3 messages in a mailbox

    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )        ' Create Pop3Server object
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )     ' Connect to the POP3 server, and login using
                                                                         ' account 'userid', password 'passwd'
    If( objPop3Server.LastError = 0 ) Then 
       numMessages = objPop3Server.CountMessages()                       ' Count the messages in the mailbox
       WScript.Echo numMessages & " new message(s) in mailbox."
       For i = 1 to 3                                                    ' Iterate over the first 3 messages in the mailbox
          Set objPop3Mail = objPop3Server.GetEmail( i )                  ' Get e-mail
          If ( objPop3Server.LastError = 0 ) Then                        ' If message does exist then show details
 
             WScript.Echo "MessageID       : " & objPop3Mail.ID          ' Show e-mail information
             WScript.Echo "  Size          : " & objPop3Mail.Size
             WScript.Echo "  FromAddress   : " & objPop3Mail.FromAddress
             WScript.Echo "  FromName      : " & objPop3Mail.FromName
             WScript.Echo "  Organization  : " & objPop3Mail.Organization
             WScript.Echo "  Reply Address : " & objPop3Mail.ReplyAddress	
             WScript.Echo "  Read Receipt Address : " & objPop3Mail.ReadReceiptAddress	
             WScript.Echo "  ToAddress     : " & objPop3Mail.ToAddress
             WScript.Echo "  CcAddress     : " & objPop3Mail.CcAddress
             WScript.Echo "  Priority      : " & objPop3Mail.Priority
             WScript.Echo "  Date          : " & objPop3Mail.Date
             WScript.Echo "  Subject       : " & objPop3Mail.Subject
             WScript.Echo "  BodyType      : " & objPop3Mail.BodyType
             WScript.Echo "  Body          : " & Left ( objPop3Mail.Body, InStr ( objPop3Mail.Body, vbCrLf ) )
             WScript.Echo "  Attachments   : " & objPop3Mail.CountAttachments & vbCrLf
    
             numAttachments = objPop3Mail.CountAttachments 
             For i = 1 to numAttachments                                 ' Iterate over all attachments
                WScript.Echo "Attachment Name : " & objPop3Mail.GetAttachmentName(i)
                WScript.Echo "Attachment Size : " & objPop3Mail.GetAttachmentSize(i)
 
                ' NOTE: attachments can be saved using the 'SaveAttachment' function
             Next
          End If
       Next
       objPop3Server.Disconnect                                          ' Disconnect
    End If
List all e-mail headers of a mailbox

    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )        ' Create Pop3Server object
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )     ' Connect to the POP3 server, and login using
                                                                         ' account 'userid', password 'passwd'
    If( objPop3Server.LastError = 0 ) Then 
       numMessages = objPop3Server.CountMessages()                       ' Count the messages in the mailbox
       WScript.Echo numMessages & " new message(s) in mailbox."
       For i = 1 to numMessages                                          ' Iterate over all messages in the mailbox
          Set objPop3Mail = objPop3Server.GetEmailHeader( i )            ' Get the header of the particular e-mail
          If ( objPop3Server.LastError = 0 ) Then                        
             WScript.Echo "MessageID       : " & objPop3Mail.ID          ' Show header information
             WScript.Echo "  Size          : " & objPop3Mail.Size
             WScript.Echo "  FromAddress   : " & objPop3Mail.FromAddress
             WScript.Echo "  FromName      : " & objPop3Mail.FromName
             WScript.Echo "  Organization  : " & objPop3Mail.Organization
             WScript.Echo "  Reply Address : " & objPop3Mail.ReplyAddress	
             WScript.Echo "  Read Receipt Address : " & objPop3Mail.ReadReceiptAddress	
             WScript.Echo "  ToAddress     : " & objPop3Mail.ToAddress
             WScript.Echo "  CcAddress     : " & objPop3Mail.CcAddress
             WScript.Echo "  Priority      : " & objPop3Mail.Priority
             WScript.Echo "  Date          : " & objPop3Mail.Date
             WScript.Echo "  Subject       : " & objPop3Mail.Subject
             WScript.Echo "  BodyType      : " & objPop3Mail.BodyType
 
             ' To retrieve the Body and the Attachments, use 'GetEmailMessage'
          End If
       Next
       objPop3Server.Disconnect                                          ' Disconnect
    End If

8.2. Pop3Server Object - Overview of Properties and Functions

Property Type In/Out Mand/Opt Description
Version String Out n/a Version number of ActiveEmail
ExpirationDate String Out n/a Expiration date of ActiveEmail
LogFile String In/Out n/a Log file, for troubleshooting purposes
HostPort Number In/Out Optional The TCP port of the POP3 server. Default: 110
Authentication Number In/Out Optional The preferred authentication mechanism
Timeout Number In/Out Optional The timeout used when retrieving data
LastError String Out n/a Result of a previously called function
LastPop3Response String Out n/a Reponse of the POP3 server on the last operation

Function Description
Activate Activate the product
Clear Clear all properties
Connect Connect to a POP3 server
Disconnect Disconnect POP3 session
IsConnected Get connection status
CountMessages Count messages in the current mailbox
GetEmailHeader Get the header of a specific message in the mailbox
GetEmailMessage Get the e-mail
DeleteMessage Delete a specific message from the mailbox
GetErrorDescription Lookup error description of the given error code

8.3. Pop3Server Object - Properties


 Pop3Server::Version property

Description:
Version information of ActiveEmail. This property is read-only; you cannot assign a value to it.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )        ' Create Pop3Server object
    ...
    WScript.Echo "Version: " & objPop3Server.Version

 Pop3Server::ExpirationDate property

Description:
ExpirationDate of ActiveEmail. This property is read-only; you cannot assign a value to it. Once you have registered the product, the property holds the empty string ("") value.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )        ' Create Pop3Server object
    ...
    WScript.Echo "ExpirationDate: " & objPop3Server.ExpirationDate

 Pop3Server::LogFile property

Description:
For troubleshooting purposes, you can specify a log file to trace all POP3 operations. By default, the 'LogFile' property holds the empty string. By assigning a valid filename to it, all POP3 server operations will be written to this log file.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )        ' Create Pop3Server object
    ...
    objPop3Server.LogFile = "c:\smtp.log"                                ' Specify log file
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )
    If( objPop3Server.LastError = 0 )
      ...
      objPop3Server.Disconnect()
   End If

 Pop3Server::HostPort property

Description:
The 'HostPort' property specifies the port used by the Connect function to connect to a remote POP3 server. If the remote POP3 server uses a different port than port 110 (default), you can specify it by assigning a value to this property.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    ...
    objPop3Server.HostPort = 8110                                        ' To specify an alternate port other than 110
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )     ' Attempt to connect on port 8110
    ...

 Pop3Server::Authentication property

Description:
The 'Authentication' property specifies the mechanism used by the Connect function to authenticate to a remote POP3 server. By default, the ActiveEmail Toolkit uses auto-detection. For a list of valid authentication identifiers, click here.
Example:
    Set objPop3Server      = CreateObject( "ActiveXperts.Pop3Server" )
    Set objConstants       = CreateObject( "ActiveXperts.EMailConstants" )
    ...
    objPop3Server.Authentication = objConstants.asAUTH_POP3_APOP      
    objPop3Server.Connect( "pop3.myserver.com", "userid", "passwd" )     ' Connect and authenticate using APOP
    ...

 Pop3Server::Timeout property

Description:
The 'Timeout' property indicates the timeout used when retrieving data, in seconds. Default: 60 seconds. This property should suffice in most circumstances. Please note that a virus scanner will first dowload and check the body and attachment database before it will actually delivered the data to ActiveEmail. With a slow internet connection, you may need to increase the 'Timeout' property.
Example:
    Set objPop3Server      = CreateObject( "ActiveXperts.Pop3Server" )
    ...
    objPop3Server.Timeout = 300                                          ' Use a timeout of 5 minutes
    ...

 Pop3Server::LastError property

Description:
This read-only property indicates the result of the last called function. You should always checks the result of your functions. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription function provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    ...
    objPop3Server.GetEmailHeader( 1 )
    WScript.Echo "Result code: " & objPop3Server.LastError
    WScript.Echo "Result description: " & objPop3Server.GetErrorDescription( objPop3Server.LastError )

 Pop3Server::LastPop3Response property

Description:
The last response of the POP3 server. The property is read-only; you cannot assign a value to it. The property can be very useful for troubleshooting purposes.

If you need more advanced trace information, try the LogFile property.
Example:
   Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
   ...
   objPop3Server.GetEmailHeader( 1 )
   WScript.Echo "Result code: " & objPop3Server.LastError
   WScript.Echo "Last POP3 response: " & objPop3Server.LastPop3Response

8.4. Pop3Server Object - Functions


 Pop3Server::Activate function

Description:
This functions activates the ActiveEmail Toolkit product. A valid registration code should be passed as parameter.
Parameters:
  • The registration key
  • Persistent - this optional Boolean variable (default: True) specifies whether you want to add the registration key to the registry.
    If you pass 'True', you need to call the 'Activate' function only once for that computer.
    If you pass 'False', you need to call 'Activate' each time you create the object on that computer. This can be useful for customers who own a Distribution License of the product but do not want to show the registration key to their customers.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objPop3Server  = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Activate "xxxxx-xxxxx-xxxxx", True             ' Use a valid registration code
                                                                 ' Pass True to make the activation persistent, so you need to call
                                                                 ' Activate only once. If you pass False, you need to call Activate  
                                                                 ' each time the product is started.
 Pop3Server::Clear function

Description:
This function clears all properties of the object.
Parameters:
None.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )
    WScript.Echo objPop3Server.LastError
    objPop3Server.Clear()
    WScript.Echo objPop3Server.LastError
 Pop3Server::Connect function

Description:
Connect to an POP3 server on port 110 (unless HostPort is set to a different port) and open a mailbox. After you've established a connection to the mail server, you can receive e-mail messages.
Call Disconnect to disconnect the session after you finished receiving the messages.

A POP3 mailbox requires authentication, so you must specify an user-id and a password as additional parameters.
There are a few different authentication mechanisms for POP3. ActiveEmail auto-detects the way of authentication; if you want to force the toolkit to use a particular authentication mechanism, set the Authentication property before you call 'Connect'.
Parameters:
  • Host - Hostname or IP address of the POP3 server
  • User ID - User ID of the mailbox you want to open
  • Password - Password of the mailbox
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example (no authentication):
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )     ' Connect to the POP3 server, and login using
                                                                         ' account 'userid', password 'passwd'
    If( objPop3Server.LastError = 0 ) Then 
       numMessages = objPop3Server.CountMessages()                       ' Count the messages in the mailbox
       WScript.Echo numMessages & " new message(s) in mailbox."
       objPop3Server.Disconnect                                          ' Disconnect
    End If

 Pop3Server::Disconnect function

Description:
After you've established a connection to the POP3 server, you can receive e-mail messages.
Call 'Disconnect' to disconnect the session.
Parameters:
None.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objPop3Server     = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )     
    If( objPop3Server.LastError = 0 ) Then
      ...
      objPop3.Disconnect                                                 ' Disconnect
    End If

 Pop3Server::IsConnected function

Description:
This function returns True (-1) if the object has a connection to a POP3 server; otherwise, False (0) is returned.
Parameters:
None.
Return value:
True (-1) or False (0).
Example:
    Set objPop3Server     = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )
    WScript.Echo objPop3Server.LastError
    If( objPop3Server.IsConnected() Then )
       WScript.Echo "Connected!"
    Else
       WScript.Echo "Not connected"
    End If
    ...

 Pop3Server::CountMessages function

Description:
This function counts the number of messages in the current mailbox. You must first call the Connect function to open a mailbox on the POP3 server.
Parameters:
None.
Return value:
The number of messages in the mailbox. If the function fails, 0 is returned and the LastError is set.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )     
                                                                         
    If( objPop3Server.LastError = 0 ) Then 
       numMessages = objPop3Server.CountMessages()                       ' Count the messages in the mailbox
       WScript.Echo numMessages & " new message(s) in mailbox."
       objPop3Server.Disconnect                                          
    End If

 Pop3Server::GetEmailHeader function

Description:
This function retrieves the header of the e-mail. If the function completes successfully, a Pop3Mail object is returned with all properties filled except the body and the attachments.
You must first call the Connect function to open a mailbox on the POP3 server.
Parameters:
  • Message ID. This ID must be greater or equal to 1 and less or equal than CountMessages().
Return value:
A new Pop3Mail object (or NULL if the function fails). Check LastError property to see if the function completed successfully.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )
    If( objPop3Server.LastError = 0 ) Then
       If( objPop3Server.CountMessages() > 0 ) Then
          Set objPop3Mail = objPop3Server.GetEmailHeader( 1 )            ' Get header of the e-mail (ID:1)
          If ( objPop3Server.LastError = 0 ) Then                        
             WScript.Echo "MessageID       : " & objPop3Mail.ID          ' Show header information
             WScript.Echo "  Size          : " & objPop3Mail.Size
             WScript.Echo "  FromAddress   : " & objPop3Mail.FromAddress
             WScript.Echo "  FromName      : " & objPop3Mail.FromName
             WScript.Echo "  Organization  : " & objPop3Mail.Organization
             WScript.Echo "  Reply Address : " & objPop3Mail.ReplyAddress	
             WScript.Echo "  Read Receipt Address : " & objPop3Mail.ReadReceiptAddress	
             WScript.Echo "  ToAddress     : " & objPop3Mail.ToAddress
             WScript.Echo "  CcAddress     : " & objPop3Mail.CcAddress
             WScript.Echo "  Priority      : " & objPop3Mail.Priority
             WScript.Echo "  Date          : " & objPop3Mail.Date
             WScript.Echo "  Subject       : " & objPop3Mail.Subject
             WScript.Echo "  BodyType      : " & objPop3Mail.BodyType
          End If
          objPop3Server.Disconnect                                          
       End If
    End If

 Pop3Server::GetEmailMessage function

Description:
This function retrieves the header of the e-mail. If the function completes successfully, a Pop3Mail object is returned with all properties filled.
a You must first call the Connect function to open a mailbox on the POP3 server.
Parameters:
  • Message ID. This ID must be greater or equal to 1 and less or equal than CountMessages().
Return value:
A new Pop3Mail object (or NULL if the function fails). Check LastError property to see if the function completed successfully.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )
    If( objPop3Server.LastError = 0 ) Then
       If( objPop3Server.CountMessages() > 0 ) Then
          Set objPop3Mail = objPop3Server.GetEmailHeader( 1 )            ' Get header of the e-mail (ID:1)
          If ( objPop3Server.LastError = 0 ) Then                        
             WScript.Echo "MessageID       : " & objPop3Mail.ID          ' Show e-mail information
             WScript.Echo "  Size          : " & objPop3Mail.Size
             WScript.Echo "  FromAddress   : " & objPop3Mail.FromAddress
             WScript.Echo "  FromName      : " & objPop3Mail.FromName
             WScript.Echo "  Organization  : " & objPop3Mail.Organization
             WScript.Echo "  Reply Address : " & objPop3Mail.ReplyAddress	
             WScript.Echo "  Read Receipt Address : " & objPop3Mail.ReadReceiptAddress	
             WScript.Echo "  ToAddress     : " & objPop3Mail.ToAddress
             WScript.Echo "  CcAddress     : " & objPop3Mail.CcAddress
             WScript.Echo "  Priority      : " & objPop3Mail.Priority
             WScript.Echo "  Date          : " & objPop3Mail.Date
             WScript.Echo "  Subject       : " & objPop3Mail.Subject
             WScript.Echo "  BodyType      : " & objPop3Mail.BodyType
             WScript.Echo "  Body          : " & Left ( objPop3Mail.Body, InStr ( objPop3Mail.Body, vbCrLf ) )
             WScript.Echo "  Attachments   : " & objPop3Mail.CountAttachments & vbCrLf
    
             numAttachments = objPop3Mail.CountAttachments 
             For i = 1 to numAttachments                                 ' Iterate over all attachments
                WScript.Echo "Attachment Name : " & objPop3Mail.GetAttachmentName(i)
                WScript.Echo "Attachment Size : " & objPop3Mail.GetAttachmentSize(i)
 
                ' NOTE: attachments can be saved using the 'SaveAttachment' function
             Next
          End If
          objPop3Server.Disconnect                                          
       End If
    End If

 Pop3Server::DeleteMessage function

Description:
This function deletes a particular message from the mailbox. You must first call the Connect function to open a mailbox on the POP3 server.
Parameters:
  • Message ID. This ID must be greater or equal to 1 and less or equal than CountMessages().
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )
    If( objPop3Server.LastError = 0 ) Then
       If( objPop3Server.CountMessages() > 0 ) Then
          objPop3Server.DeleteMessage( 1 )                               ' Delete particular e-mail (Message ID:1)
          If ( objPop3Server.LastError = 0 ) Then 
             WScript.Echo "Message successfully deleted."
          Else                       
             WScript.Echo "Message not deleted."
          End If
          objPop3Server.Disconnect                                          
       End If
    End If

 Pop3Server::GetErrorDescription function

Description:
Function to retrieve the explanation of an error code.
Parameters:
  • Error Code.
Return value:
The Error string.
Example:
    Set objPop3Server     = CreateObject( "ActiveXperts.Pop3Server" )
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )
    If( objPop3Server.LastError = 0 ) Then
      ...
      objPop3Server.Disconnect
    Else
      WScript.Echo "Error description: " & objPop3Server.GetErrorDescription( objPop3Server.LastError )
    End If



9. Pop3Mail Object

9.1. Pop3Mail Object - Introduction

The Pop3Mail object holds all properties of a POP3 message, like: recipients, subject, body, priority, attachments, etc..


The following sample demonstrates the use of the 'Pop3Mail' object (sample written in VBScript).

Show the first message in a mailbox

    Set objPop3Server = CreateObject( "ActiveXperts.Pop3Server" )          ' Create Pop3Server object
    objPop3Server.Connect( "pop3.mydomain.com", "userid", "passwd" )       ' Connect to the POP3 server, and login using
                                                                           ' account 'userid', password 'passwd'
    If( objPop3Server.LastError = 0 AND objPop3Server.CountMessages() > 0 ) Then 
       Set objPop3Mail = objPop3Server.GetEmail( 1 )                       ' Retrieve the first message (Message ID:1)
       If( objPop3Server.LastError = 0 ) Then                        
          WScript.Echo "MessageID       : " & objPop3Mail.ID               ' Show e-mail information
          WScript.Echo "  Size          : " & objPop3Mail.Size
          WScript.Echo "  FromAddress   : " & objPop3Mail.FromAddress
          WScript.Echo "  FromName      : " & objPop3Mail.FromName
          WScript.Echo "  Organization  : " & objPop3Mail.Organization
          WScript.Echo "  Reply Address : " & objPop3Mail.ReplyAddress	
          WScript.Echo "  Read Receipt Address : " & objPop3Mail.ReadReceiptAddress	
          WScript.Echo "  ToAddress     : " & objPop3Mail.ToAddress
          WScript.Echo "  CcAddress     : " & objPop3Mail.CcAddress
          WScript.Echo "  Priority      : " & objPop3Mail.Priority
          WScript.Echo "  Date          : " & objPop3Mail.Date
          WScript.Echo "  Subject       : " & objPop3Mail.Subject
          WScript.Echo "  BodyType      : " & objPop3Mail.BodyType
          WScript.Echo "  Body          : " & Left ( objPop3Mail.Body, InStr ( objPop3Mail.Body, vbCrLf ) )
          WScript.Echo "  Attachments   : " & objPop3Mail.CountAttachments & vbCrLf
    
          numAttachments = objPop3Mail.CountAttachments 
          For i = 1 to numAttachments                                      ' Iterate over all attachments
             WScript.Echo "Attachment Name : " & objPop3Mail.GetAttachmentName(i)
             WScript.Echo "Attachment Size : " & objPop3Mail.GetAttachmentSize(i)
 
             ' NOTE: attachments can be saved using the 'SaveAttachment' function
          Next
       End If
    End If
 
    objPop3Server.Disconnect                                               ' Disconnect

9.2. Pop3Mail Object - Overview of Properties and Functions

Property Type In/Out Mand/Opt Description
ID Number Out n/a The Message ID
Size Number Out n/a The size (in bytes) of the message
FromAddress String Out n/al The Sender's e-mail address
FromName String Out n/a The Sender's name
Organization String Out n/a The Sender's organization name
ReplyAddress String Out n/a The Sender's reply-address.
ReadReceiptAddress String Out n/a Read receipt e-mail address
ToAddress String Out n/a The recipient's e-mail address.
CcAddress String Out n/a The recipient's CC address.
Date String Out n/a The date and time the message was sent by the sender
Encoding Number Out n/a The encoding that was used, for instance: Japanese or Chinese
Subject String Out n/a The Subject of the message
Priority Number Out n/a The Priority of the message. There a five different priority-levels
BodyType Number Out n/a The bodytype of the message.
Body String Out n/a The Body of the message
Hash String Out n/a A hash of the message header
LastError Number Out n/a Result of a previously called function

Function Description
Clear Clear all properties
CountAttachments Count the number of attachments in the e-mail
GetAttachmentName Get the plain file name of the attachment as it was sent by the sender
GetAttachmentSize Get the size (bytes) of the attachment
SaveAttachment Save an attachment
SaveMIME Save properties, recipients and attachments to a MIME file
GetErrorDescription Lookup error description of the given error code

9.3. Pop3Server Object - Properties


 Pop3Mail::ID property

Description:
The Message ID of the POP3 message. This ID is greater or equal to 1 and less or equal than CountMessages().
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "MessageID : " & objPop3Mail.ID                         ' Show Message ID

 Pop3Mail::Size property

Description:
The size (in bytes) of the POP3 message.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Size : " & objPop3Mail.Size & " (bytes)"               ' Show message size (in bytes)

 Pop3Mail::FromAddress and FromName properties

Description:
The FromAddress and FromName fields specify the sender. The FromAddress specifies the sender's e-mail address. This is the return-path for your e-mail, unless you specify the ReplyAddress property. The ReplyAddress property always overrides the FromAddress property for it's return path. The FromName field specifies the sender's friendly name.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "From (e-mail) : " & objPop3Mail.FromAddress            ' Show from (e-mail address)
    WScript.Echo "From (name) : "   & objPop3Mail.FromName               ' Show from (friendly name)

 Pop3Mail::Organization property

Description:
The sender's organization name.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "From (organization) : " & objPop3Mail.Organization     ' Show sender's organization name

 Pop3Mail::ReplyAddress property

Description:
The Reply-address of the sender. If not specified, the reply-address will be the address indicated by the FromAddress property.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Reply-address : " & objPop3Mail.ReplyAddress           ' Show sender's reply address

 Pop3Mail::ReadReceiptAddress property

Description:
E-mail address of the person who should receive a 'read receipt'.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Read receipt : " & objPop3Mail.ReadReceiptAddress      ' Show sender's read receipt address

 Pop3Mail::ToAddress property

Description:
The destination e-mail address. This can also be a list of e-mail addresses (separated by a semi-column).
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "To recipient(s) : " & objPop3Mail.ToAddress            ' Show recipient's 'To' address(es)

 Pop3Mail::CcAddress property

Description:
The destination CC e-mail address. This can also be a list of e-mail addresses (separated by a semi-column).
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "CC recipient(s) : " & objPop3Mail.CcAddress            ' Show recipient's 'CC' address(es)

 Pop3Mail::Date property

Description:
The date and time the message was sent by the sender.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Date : " & objPop3Mail.Date                            ' Show Date property

 Pop3Mail::Encoding property

Description:
For a list of valid encoding values, click here.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Encoding : " & objPop3Mail.Encoding                    ' Show Encoding property

 Pop3Mail::Subject property

Description:
The Subject of a message.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Subject : " & objPop3Mail.Subject                      ' Show Subject property

 Pop3Mail::Priority property

Description:
The Priority of the message. There are 5 priority levels, described here.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Priority : " & objPop3Mail.Priority                    ' Show Priority property

 Pop3Mail::BodyType , Pop3Mail::Body properties

Description:
This property tells you how the 'Body' is formatted. There are two possible values for 'BodyType': The 'Body' property holds the full body of the e-mail message
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "BodyType : " & objPop3Mail.BodyType                    ' Show BodyType property
    WScript.Echo "Body (first 100 chars): " & Left( objPop3Mail.Body, 100 )  ' Show first 100 characters of the body

 Pop3Mail::Hash property

Description:
The Hash value of the e-mail header. It's a unique number for an e-mail message
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Hash : " & objPop3Mail.Hash                            ' Show Hash property

 Pop3Mail::LastError property

Description:
This read-only property indicates the result of the last called function. You should always checks the result of your functions. A zero indicates: success. Any non-zero value means an error.
The GetErrorDescription function provides the error description of an error code.
For a complete list of error codes, check out the following page: www.activexperts.com/support/errorcodes.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                   ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "#Attachments" & objPop3Mail.CountAttachments()         
    objPop3Mail.SaveAttachment( 10, "c:\temp\attach100.bin" )       ' Save 10th attachment.
    WScript.Echo "SaveAttachment, result: " & objPop3Mail.LastError

9.4. Pop3Mail Object - Functions


 Pop3Mail::Clear function

Description:
This function clears all properties of the object.
Parameters:
None.
Return value:
Always 0.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "Subject : " & objPop3Mail.Subject                      ' Show Subject property
    objPop3Mail.Clear()                                                  ' Clear all properties
    WScript.Echo "Subject : " & objPop3Mail.Subject                      ' Will show an empty string

 Pop3Mail::CountAttachments function

Description:
Returns the number of attachments in a POP3 message.
Parameters:
Return value:
The number of attachments. If the function fails, 0 is returned an the error code is stored in the LastError property.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "#Attachments : " & objPop3Mail.CountAttachments()      ' Show the number of attachments

 Pop3Mail::GetAttachmentName function

Description:
Returns the name of the attached file as it was sent by the sender.
Parameters:
Return value:
The name of the attached file. If the function fails, 0 is returned an the error code is stored in the LastError property.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    For i = 1 To objPop3Mail.CountAttachments()
       WScript.Echo "Attachment name: " & objPop3Mail.GetAttachmentName(i)  ' Show the name of the attachment
    Next

 Pop3Mail::GetAttachmentSize function

Description:
Returns the size of the attached file.
Parameters:
Return value:
The size if the attached file. If the function fails, 0 is returned an the error code is stored in the LastError property.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    For i = 1 To objPop3Mail.CountAttachments()
       WScript.Echo "Attachment size: " & objPop3Mail.GetAttachmentSize(i)  ' Show the size of the attachment
    Next

 Pop3Mail::SaveAttachment function

Description:
Saves an attached file to save location.
Parameters:
  • The Message ID.
  • Full-path file name of the attachment to be saved.
Return value:
Always 0. If the function fails, the error code is stored in the LastError property.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    For i = 1 To objPop3Mail.CountAttachments()
       strSaveAs = "c:\temp\" & objPop3Mail.GetAttachmentName(i)
       objPop3Mail.SaveAttachment( i, strSaveAs )
       WScript.Echo "Attachment saved as " & strSaveAs & ", result: " & objPop3Mail.LastError
    Next

 Pop3Mail::SaveMIME function

Description:
This function saves all properties, recipients and attachments to a MIME file. This MIME file can be used at any time by the SmtpMail::LoadMIME function, or by another e-mail client including Microsoft Outlook Express and Microsoft Mail.
Parameters:
  • The MIME file.
Return value:
Always 0. Check LastError property to see if the function completed successfully.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    objPop3Mail.SaveMIME( "C:\File.mim" )                                     ' Save MIME file
    WScript.Echo "SaveMIME, result: " & objPop3Mail.LastError                 ' Show the result

 Pop3Mail::GetErrorDescription function

Description:
Function to retrieve the explanation of an error code.
Parameters:
  • Error Code.
Return value:
The Error string.
Example:
    Set objPop3Mail = objPop3Server.GetEmail( 1 )                        ' Retrieve the first message (Message ID:1)
    ...
    WScript.Echo "#Attachments" & objPop3Mail.CountAttachments()         
    objPop3Mail.SaveAttachment( 10, "c:\temp\attach100.bin" )            ' Save 10th attachment.
    WScript.Echo "SaveAttachment, result: " & objPop3Mail.LastError & _
                                          " (" & objPop3Mail.GetErrorDescription( objPop3Mail.LastError ) & ")"



10. ActiveEmail Queue Server

10.1. Introduction

With ActiveEmail, people usually send SMTP messages directly to an SMTP server. There are two drawbacks of sending directly to the SMTP server:

ActiveEmail can overcome these problems, using a queue mechanism: the client application/script connects to a network share service and drops the e-mail mime information in a file, and the control in the script or application is relinguished immediately.
The ActiveEmail Queue Service picks up the mime information from the network share and sends the e-mail(s) to the smtp server.
To make use of queuing, the should call the Queue function instead of the Send function.
The ActiveEmail Queue Service has enhanced logging capabilities.

The Queue is just a directory. If you use ActiveEmail on one machine only, it can be just a local directory. If you use ActiveEmail on more than one machine, the directory must be a shared directory, somewhere on the network.

You don't need an extra license to use the ActiveEmail Queue Server; licensing is only based on the number of PCs where the ActiveEmail COM component is registered.

The installation of the ActiveEmail Queue Server service creates some subdirectories in the installation directory of ActiveEmail:

10.2. Hosting the ActiveEmail Queue

The ActiveEmail Queue Service is not installed by default. To install the ActiveEmail Queue Server service, you must do the following:

10.3. Connecting to an ActiveEmail Queue Server from any network computer

Once you have configured one of your network server as 'ActiveEmail Queue Server', you can connect to it from other network computers. These computer must have ActiveEmail installed. To connect to an ActiveEmail Queue Server, you must do the following:

10.4. ActivQueue Configuration Settings

All configuration settings are made in the HKEY_LOCALMACHINE\Software\ActiveXperts\ActiveEmail key of the registry. Use REGEDT32.EXE to make changes to the registry.
The following settings are defined:

Registry Value Type Explanation.
LogDir REG_SZ Directory where logfiles are stored. Emails are only logged if EnableLogging is set to 1 (default).
EnableLogging REG_DWORD Logging is enabled if this value is set to 1 (default). Log files are located in the LogDir directory.
PickupMailDir REG_SZ The 'ActiveEmail Queue Service' can service more than one client. There's one central directory where it can pickup it's e-mails. PickupMailDir points to this directory.
KeepFailedMails REG_DWORD In case of 0, a failed e-mail will be removed from the PickupMailDir directory. In case of 1, a failed e-mail will be moved from the PickupMailDir directory to the FailedMailDir directory.
FailedMailDir REG_SZ A failed e-mail will be moved to this directory, but only if KeepFailedMails is 1.
KeepSentMails REG_DWORD In case of 0, a sent e-mail will be removed from the PickupMailDir directory. In case of 1, a sent e-mail will be moved from the PickupMailDir directory to the SentMailDir directory.
SentMailDir REG_SZ A sent e-mail will be moved to this directory, but only if KeepSentMails is 1.

NOTE: You must restart the ActiveEmail Queue Service after you change the configuration parameters in the registry!

10.5. Errors and Warnings

All information about particalr e-mails are logged in the logdirectory (unless logging is disabled). Information about the ActiveEmail Queue Service itself, is logged in the Windows Event Log.
This information can be viewed by using the Event Viewer.
All errors and warnings are logged in the Application Log in the Event Log. So, if the service doesn't start, or e-mails are not logged, check out the Application Log using the Event Viewer.



11. Samples

Samples for Visual Basic, Visual Basic .NET, Visual C++, Visual C# .NET, ASP and VBScript are included as part of the installation. You can also find the samples on our ftp site at ftp.activexperts-labs.com/samples/aemail/



12. Troubleshooting

12.1. FAQ's

Visit our website for a complete list of FAQ's at: www.activexperts.com/support/activemail

12.2. Contact us

Please contact our website for support questions about this product, or send an e-mail to our support-staff:
Website: http://www.activexperts.com/support
Email: support@activexperts.com



13. Purchase and Product Activation

13.1 Purchase

Please visit www.activexperts.com/sales to buy the product. Here, you can also find the latest prices.

You can also contact us via e-mail: sales@activexperts.com

After you purchase the product, you will receive one or more product registration keys.

13.2 Product Activation

After you purchase the product, you will receive a registration code. This code must be entered on your machine(s). You can do this by using the actual ActiveEmail component:
  Set objSmtp = CreateObject( "ActiveXperts.SmtpServer" ) 
  objSmtp.Activate XXXXX-XXXXX-XXXXX", True           ' Substitute XXXXX-XXXXX-XXXXX by your own registration code
                                                      ' Pass True to make the activation persistent, so you need to call Activate 
                                                      ' only once. If you pass False, you need to call Activate each time the 
                                                      ' product is started.

Or you can activate by (re)installing the product using the Setup program. The InstallShield wizard will prompt for the registration code.

Or you can activate by editing the registry:

For information about how to use the registration code with a Distribution License, please read the following document: How to distribute an ActiveXperts Toolkit.



Appendix A - About Mime

The basic Internet standard for message format, defined in RFC 1521 and RFC 1522, and the Simple Mail Transport Protocol (SMTP), defined in RFC 821 and RFC 822, are widely used around the world these days.

RFC 821 and 822 describe:
Mime is an e-mail message protocol, that is being described in RFC 1521 and RFC 1522. These RFC's facilitate to send non-character e-mails, being still compliant with the RFC 821 and RFC 822 standards.
The non-character information can be embedded, but can also be sent as binary attachments.

MIME conversions

A message body is only a compilation of text. By conversion of the attachments to text, the message is still compliant with RFC 821 and RFC822.
The transport system (MTA) expects, according to RFC 821 and RFC 822, chunks of a 7-bit text. The transport system does not know whether it is a normal text, or executables, or images, etc.
Obviously, it is important for the recipient clients to be able to translate the 7bit chunks to executable, image, etc.

MIME Headers

MIME defines five header lines, explaining the client how the message body has to be interpreted:
  • Content-Type: specifies the type of data in a message;
  • Content-Transfer-Encoding: specifies how data can be converted to 7bits;
  • MIME-version: specifies MIME-version;
  • Content-ID: Can be used to split a bigger message body to multiple, smaller parts;
  • Content-Description: is not used by MIME application. It gives an idea of the content to the user.

Content-Type

The Content-Type header tells the MIME-decoder (the receiver) which data are held in the message-body.
This is done in two parts, seperated by " / " : a rougher indication and a specified type, for example image/jpeg. Optionally, this can be followed by a series expressions, seperated by a semicolon (';').

There are seven Content-types specified:
  • Text - to represent textual information in a number of character sets;
  • Image - for transmitting still image (picture) data;
  • Audio - for transmitting audio or voice data;
  • Video - for transmitting video or moving image data;
  • Message - for encapsulating a mail message;
  • Multipart - to combine several body parts, possibly of different types of data, into a single message;
    • Application - to transmit application data or binary data.

For example:
    Content-Type: text/plain; charset="iso-8859-1"
The more Content-Types are being supported by your mail-client, the more message types can be read. Outlook Express does support for example text/html, so that it can handle embedded html. A content-Type which is NOT being supported by a mail client, will be dealt with by the mail client with a 'Save as' dialogbox, and as such being saved on disk as an attachment. The attached application (.EXE) will be sent as 'Content-Type: application/octet-stream'.


Content-Transfer-Encoding

SMTP restricts mail messages to 7-bit ASCII data with lines no longer than 1000 characters.
The Content-Transfer-Encoding specifies the mechanism to be used by the mail client to decode a message back to its original. It is essential that messages can be decoded, being even more important than the Content-Type. It is nice when your mail-client can handle a image/gif Content-Type, but when it can not decode the message, it is of no use. The most frequent types of Content-TRansfer-Encoding are:
  • 7bit;
  • 8bit;
  • Binary;
  • Quoted-Printable;
  • Base64.

Content-ID

The optional Content-ID header field may be desirable to allow one body to reference another. The value may be used for uniquely identifying MIME entities in several contexts.


Content-Description

The optional Content-Description header field gives the ability to associate some descriptive information with a given body.



Appendix B - License Agreement

PLEASE READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY BEFORE 
DOWNLOADING OR USING THE SOFTWARE.  BY CLICKING ON THE 
"ACCEPT" BUTTON, OPENING THE PACKAGE, DOWNLOADING THE PRODUCT, 
OR USING THE EQUIPMENT THAT CONTAINS THIS PRODUCT, YOU ARE 
CONSENTING TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE 
TO ALL OF THE TERMS OF THIS AGREEMENT, CLICK THE "DO NOT 
ACCEPT" BUTTON AND THE INSTALLATION PROCESS WILL NOT CONTINUE, 
RETURN THE PRODUCT TO THE PLACE OF PURCHASE FOR A FULL REFUND, 
OR DO NOT DOWNLOAD THE PRODUCT.

GENERAL
In this Software License Agreement:
(i) "ActiveXperts" means ActiveXperts Software B.V.
(ii) "Customer" means the individual(s), organization or business entity 
buying a license of the Software from ActiveXperts or its Distributors 
or its Resellers.
(iii) "Software" means computer programs (and their storage medium) 
supplied by ActiveXperts and known collectively as "ActiveEmail" 
in which ActiveXperts has property rights and any user manuals, 
operating instructions, brochures and all other documentation relating 
to the said computer programs (the expression "Software" to include all 
or any part or any combination of Software).

1. LICENSE GRANT
ActiveXperts grants Customer the following rights provided that you 
comply with all terms and conditions of this License Agreement:

(a) Installation and use. Customer may install, use, access, display and 
run one copy of the Software on a single computer, such as a 
workstation, terminal or other device ("Workstation Computer"). A 
"License Pack" allows you to install, use, access, display and run 
additional copies of the Software up to the number of "Licensed Copies" 
specified above.

(b) Reservation of Rights. ActiveXperts reserves all rights not 
expressly granted to you in this License Agreement.

2. UPGRADES AND SUPPLEMENTS
To use a product identified as an upgrade, you must first be licensed 
for the Software as eligible for the upgrade. After upgrading, Customer 
may no longer use the product that formed the basis for Customer's 
upgrade eligibility.

This License Agreement applies to updates or supplements to the original 
Software provided by ActiveXperts, unless we provide other terms along 
with the update or supplement.

3. LIMITATION ON REVERSE ENGINEERING,DECOMPILATION, AND DISASSEMBLY
Customer may not reverse engineer, decompile, or disassemble the 
Software, except and only to the extent that it is expressly permitted 
by applicable law notwithstanding this limitation.

4. TERMINATION
Without prejudice to any other rights, ActiveXperts may cancel this 
License Agreement if Customer does not abide by the terms and conditions 
of this License Agreement, in which case you must destroy all copies of 
the Software and all of its component parts.

5. NOT FOR RESALE SOFTWARE
Software identified as "Not for Resale" or "NFR," may not be resold, 
transferred or used for any purpose other than demonstration, test or 
evaluation.

6. LIMITED WARRANTY
ActiveXperts warrants that for a period of ninety (90) days from the 
date of shipment from ActiveXperts: (i) the media on which the Software 
is furnished will be free of defects in materials and workmanship under 
normal use; and (ii) the Software substantially conforms to its 
published specifications. Except for the foregoing, the Software is 
provided AS IS. This limited warranty extends only to Customer as the 
original licensee. Customer's exclusive remedy and the entire liability 
of ActiveXperts and its suppliers under this limited warranty will be, 
at ActiveXperts or its service center's option, repair, replacement, or 
refund of the Software if reported (or, upon request, returned) to the 
party supplying the Software to Customer. In no event does ActiveXperts 
warrant that the Software is error free or that Customer will be able to 
operate the Software without problems or interruptions.
This warranty does not apply if the software (a) has been altered, 
except by ActiveXperts, (b) has not been installed, operated, repaired, 
or maintained in accordance with instructions supplied by ActiveXperts, 
(c) has been subjected to abnormal physical or electrical stress, 
misuse, negligence, or accident, or (d) is used in ultrahazardous 
activities.


7. LIMITATION OF LIABILITY AND REMEDIES.
Notwithstanding any damages that you might incur for any reason 
whatsoever (including, without limitation, all damages referenced above 
and all direct or general damages), the entire liability of ActiveXperts 
and any of its suppliers under any provision of this License Agreement 
and your exclusive remedy for all of the foregoing (except for any 
remedy of repair or replacement elected by ActiveXperts with respect to 
any breach of the Limited Warranty) shall be limited to the greater of 
the amount actually paid by you for the Software or U.S.$5.00. The 
foregoing limitations, exclusions and disclaimers (including Sections 4, 
5 and 6 above) shall apply to the maximum extent permitted by applicable 
law, even if any remedy fails its essential purpose.

8. ENTIRE AGREEMENT

This License Agreement (including any addendum or amendment to this 
License Agreements which is included with the Software) are the entire 
agreement between you and ActiveXperts relating to the Software and the 
support services (if any) and they supersede all prior or 
contemporaneous oral or written communications, proposals and 
representations with respect to the Software or any other subject matter 
covered by this License Agreement. To the extent the terms of any 
ActiveXperts policies or programs for support services conflict with the 
terms of this License Agreement, the terms of this License Agreement 
shall control.

This Agreement shall be construed in accordance with the laws of The 
Netherlands and the Dutch courts shall have sole jurisdiction in any 
dispute relating to these conditions. If any part of these conditions 
shall be or become invalid or unenforceable in any way and to any extent 
by any existing or future rule of law, order, statute or regulation 
applicable thereto, then the same shall to the extent of such invalidity 
or enforceability be deemed to have been deleted from the conditions 
which shall remain in full force and effect as regards all other 
provisions.

9. Copyright
The Software is protected by copyright and other intellectual property 
laws and treaties. ActiveXperts or its suppliers own the title, 
copyright, and other intellectual property rights in the Software. The 
Software is licensed, not sold.