AxEmail.Imap

Introduction

The Internet Message Action Protocol (IMAP) is a standard and much used protocol to retrieve email messages and manage mailboxes that exist on a remote server. This Imap object is a quick and easy way to access IMAP servers.

Normally IMAP refers to IMAP4rev1. This is the most used version of the standard and is fully supported by this component.

This is an example that quickly connects and retrieves any unseen emails from the default mailbox on the server:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.SetSecure
  objImap.Connect "imap.gmail.com", "username", "password"
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
 
  objImap.Select "INBOX"
  Set objEmail = objImap.FetchFirstEmail(objConstants.IMAP_SK_UNSEEN)
  While objImap.LastError = 0
    
    WScript.Echo "MessageID        : " & objEmail.ImapUID
    WScript.Echo "   From          : " & objEmail.FromAddress
    WScript.Echo "   From Name     : " & objEmail.FromName
    WScript.Echo "   To            : " & objEmail.ToAddress
    WScript.Echo "   Subject       : " & objEmail.Subject
    WScript.Echo "   Date          : " & objEmail.Date  
    WScript.Echo vbCrLf 
  
    Set objEmail = objImap.FetchNextEmail
  WEnd
  
  objImap.Disconnect

How to run this example

This is an example that lists all mailboxes in the root of the mail account on the mail server:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.SetSecure
  objImap.Connect "imap.gmail.com", "username", "password"
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
 
  objImap.List "", "%"
  WScript.Echo "List, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  WScript.Echo
  
  nCount = objImap.ListCount
  WScript.Echo "Found " & objImap.ListCount & " mailboxes:"
  If nCount > 0 Then
    For i = 0 To nCount - 1
      strMailboxName = objImap.ListName(i)
      strMailboxAttributes = objImap.ListAttributes(i)
      
      WScript.Echo "  "  & strMailboxName & ": " & strMailboxAttributes
    Next
  End If
  
  objImap.Disconnect

How to run this example

Properties and Methods

Property	Type	Read/Write	Description
Version	String	Read	Version number of the Auron Email Component
Build	String	Read	Build number of the Auron Email Component
Module	String	Read	Module name of the Auron Email Component
LicenseStatus	String	Read	License Status
LicenseKey	String	Read/Write	License Key
LastError	Number	Read	Result of the last called method
LogFile	String	Read/Write	The path to a logfile which can be used for troubleshooting
HostPort	Number	Read/Write	Port number to connect to
Authentication	Number	Read/Write	Preferred authentication method
BearerToken	String	Read/Write	OAuth2 bearer token
UseStartTls	Boolean	Read/Write	Use STARTTLS capability when available
AutoClose	Boolean	Read/Write	Automatically close the mailbox before disconnect
IpVersion	Number	Read/Write	IP Version to use (IPv4 or IPv6)
Secure	Number	Read/Write	Enable secure connect
LastImapResponse	String	Read	Last response text from server
HierarchySeparator	String	Read	Path separator used by server
Capabilities	String	Read	List of server capabilities
Exists	Number	Read	Number of messages in the selected mailbox
Recent	Number	Read	Number of ‘Recent’ messages in the selected mailbox
Unseen	Number	Read	Number of ‘Unseen’ messages in the selected mailbox
UidNext	Number	Read	Next UID the server is going to use
IdleResetTimeMin	Number	Read/Write	The reset timeout for the Idle command
TimeoutConnect	Number	Read/Write	Timeout while connecting in milliseconds
TimeoutCommand	Number	Read/Write	Command timeout for any command in milliseconds
TimeoutAppend	Number	Read/Write	Timeout while appending a new email to a mailbox in milliseconds
FetchMaxNumItemsAtOnce	Number	Read/Write	Maximum number of items to fetch at once
MaximumPendingFetchData	Number	Read/Write	Maximum number of pending fetch items
MaximumPendingExpunged	Number	Read/Write	Maximum number of pending expunged notifications
UseSequenceNumForStoreAndCopy	Boolean	Read/Write	Use sequence number instead of UID for store and copy

Method	Description
Clear	Reset all properties to their default values
SaveLicenseKey	Save the License Key in the registry
GetErrorDescription	Get the description of the given error
Sleep	Sleep for the specified number of milliseconds
SetSecure	Enable TLS/SSL and set the correct port number
Connect	Connect to the specified IMAP server
Disconnect	Disconnect from the IMAP server
IsConnected	Returns the connected state
Select	Select a mailbox to manipulate
Examine	Select a mailbox to inspect without making changes
Status	Update this Imap object to reflect the status of the given mailbox
Close	Close the selected mailbox and make any changes permanent
Create	Create a new mailbox
Delete	Delete the given mailbox
Rename	Rename the given mailbox
Subscribe	Subscribe to the given mailbox
Unsubscribe	Unsubscribe from the given mailbox
Copy	Copy email messages to a different mailbox
Store	Set, remove or alter mail flags for the given email message(s)
Noop	No Operation (Use to gather unsolicited server responses)
Check	Request server to do any implementation dependent internal housekeeping
Expunge	Permanently removes messages that are flagged for deletion
Idle	Go to IDLE state to receive real-time notifications
IdleDone	Exits the IDLE state
GetPendingExpunged	Get next sequence number of message that was deleted
GetPendingFetchData	Get next unsolicited fetch data response (e.g. Message flags update)
List	List mailboxes
ListSubscribed	List subscribed mailboxes
ListCount	Number of mailboxes listed
ListAttributes	Mailbox flags for the given list index
ListHasAttribute	Check if mailbox with given list index has the given flag set
ListName	Name of the mailbox at the given list index
FetchFirstEmail	Fetch the first email that matches the given search criteria
FetchNextEmail	Fetch the next email
FetchFirstEmailHeader	Fetch the first email header that matches the given search criteria
FetchNextEmailHeader	Fetch the next email header
FetchFirst	Build a custom fetch request for specific fetch data from the server
FetchNext	Fetch next according to custom fetch request
Append	Append a new email message to the given mailbox
HasCapability	Check if the IMAP server supports the given capability
FormatDate	Helper to format a date such that it can be used as a parameter or as an expression
FormatTime	Helper to format a time such that it can be used as a parameter or as an expression

Version property

Return the version number of the Auron Email Component

Example:

Set objImap = CreateObject("AxEmail.Imap")
Wscript.Echo "Auron Email Component Version"  & objImap.Version & "; Build"  & _
  objImap.Build & "; Module"  & objImap.Module
WScript.Echo "License Status:"  & objImap.LicenseStatus & vbCrLf
...

Build property

Return the build number of the Auron Email Component.

Example:

Set objImap = CreateObject("AxEmail.Imap")
Wscript.Echo "Auron Email Component Version"  & objImap.Version & "; Build"  & _
  objImap.Build & "; Module"  & objImap.Module
WScript.Echo "License Status:"  & objImap.LicenseStatus & vbCrLf
...

Module property

Return the module name of the Auron Email Component.

Example:

Set objImap = CreateObject("AxEmail.Imap")
Wscript.Echo "Auron Email Component Version"  & objImap.Version & "; Build"  & _
  objImap.Build & "; Module"  & objImap.Module
WScript.Echo "License Status:"  & objImap.LicenseStatus & vbCrLf
...

LicenseStatus property

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objImap = CreateObject("AxEmail.Imap")                 ' Create new instance
WScript.Echo "License Status:"  & objImap.LicenseStatus
WScript.Echo "License Key:"  & objImap.LicenseKey

LicenseKey property

A license key is required to unlock this component after the trial period has expired. Assign the LicenseKey property every time a new instance of this component is created (see code below). Alternatively, the LicenseKey property can be set automatically. This requires the license key to be stored in the registry. For details, see Product Activation.

Example:

Set objImap = CreateObject("AxEmail.Imap")                 ' Create new instance
objImap.LicenseKey = "XXXXX-XXXXX-XXXXX"                ' Assign your license key 
WScript.Echo "LicenseKey:"  & objImap.LicenseKey

LastError property

Completion code of the last called function. To find the error description of a given error code, go to the online error codes page.

Example:

Set objImap = CreateObject("AxEmail.Imap")
objImap.Connect "imap.example.com", "me@example.com", "password"
If objImap.LastError <> 0 Then
  WScript.Echo "Error:"  & objImap.GetErrorDescription(objImap.LastError)  
  WScript.Quit
End If
...

LogFile property

By default, LogFile holds an empty string and nothing is logged. If a valid file name is assigned to it, the Auron Email Component will write debug information to this file.
Output data is written at the end of the file, the file is not cleared.

By default the log file uses the UTF16LE character encoding. To use UTF8 please prefix the log file name with the text: ‘UTF8:’ (e.g.: ‘UTF8:logfile.txt’).

Example:

Set objImap = CreateObject("AxEmail.Imap")
objImap.LogFile = "C:\Temp\Imap.log"
objImap.Connect "imap.example.com", "me@example.com", "password"
If objImap.LastError <> 0 Then
  WScript.Echo "Error:"  & objImap.GetErrorDescription(objImap.LastError)  
  WScript.Quit
End If
...

HostPort property

The port number on the server to connect to.

This is set to 143 by default and set to 993 after calling SetSecure. Use this property when the IMAP server is configured on a different port number.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.HostPort = 993
  objImap.Secure = True
  objImap.Authentication = objConstants.IMAP_AUTH_AUTO
  objImap.Connect strServer, strServerAccount, strServerPassword 
  
  ' ...  
  
  objImap.Disconnect

Authentication property

Preferred authentication method to use when logging into the IMAP server. Find the possible options here. By default this is set to ‘auto’.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.HostPort = 993
  objImap.Secure = True
  objImap.Authentication = objConstants.IMAP_AUTH_AUTO
  objImap.Connect strServer, strServerAccount, strServerPassword 
  
  ' ...  
  
  objImap.Disconnect

BearerToken property

Set the bearer token to use OAuth2 authentication. If the bearer token is set then the user password can be left blank.

Obtain the bearer token by using the OAuth2 object.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.HostPort = 993
  objImap.Secure = True
  objImap.BearerToken = "12345678901234567890"
  objImap.Authentication = objConstants.IMAP_AUTH_OAUTH2
  objImap.Connect strServer, strServerAccount
  
  ' ...  
  
  objImap.Disconnect

UseStartTls property

User STARTTLS when this capability is available and the connection is not secured.

STARTTLS is used to secure an insecure connection right after connecting to the server before authenticating.

By default this is enabled.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.HostPort = 143
  objImap.Secure = False
  objImap.UseStartTls = True
  objImap.Connect strServer, strServerAccount, strServerPassword 
  
  ' ...  
  
  objImap.Disconnect

AutoClose property

Automatically close the currently selected mailbox before disconnecting.

Closing the mailbox will finalize all operations for that mailbox.

This is enabled by default.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.AutoClose = False
  objImap.IpVersion = objConstants.IPVERSION_6
  objImap.Connect strServer, strServerAccount, strServerPassword 
  
  ' ...  
  
  objImap.Close
  objImap.Disconnect

IpVersion property

Set the IP version to be used when connecting to the server.

Find the possible values here.

By default this is version 4

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.AutoClose = False
  objImap.IpVersion = objConstants.IPVERSION_6
  objImap.Connect strServer, strServerAccount, strServerPassword 
  
  ' ...  
  
  objImap.Close
  objImap.Disconnect

Secure property

Enabled secure (SSL/TLS) connecting to the server.

Set this value before calling connect to setup a secured connection to the server.

If this value is set to False the client will automatically try ‘STARTTLS’ right after connecting to secure the connection before sending the user name and password.

The default value is ‘False’.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.HostPort = 993
  objImap.Secure = True
  objImap.Authentication = objConstants.IMAP_AUTH_AUTO
  objImap.Connect strServer, strServerAccount, strServerPassword 
  
  ' ...  
  
  objImap.Disconnect

LastImapResponse property

Contains the last response from the server.

Right after connecting this will contain the server welcome message.

The last IMAP response may sometimes contain extra information that will be useful in case of troubleshooting.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  WScript.Echo objImap.LastImapResponse
  WScript.Echo objImap.Capabilities
  
  ' ...  
  
  objImap.Disconnect

HierarchySeparator property

Contains the path separator used by the server. This string should always be a single character.

The IMAP server may decide what it uses as a path separator. For instance: ‘/’ (Departments/Sales), ‘.’ (Departments.Sales), or even ” when no sub-mailboxes are supported.

Any call to the List method will update the hierarchy separator.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  objImap.List "", ""
  WScript.Echo objImap.HierarchySeperator
  
  ' ...  
  
  objImap.Disconnect

Capabilities property

Contains a space (‘ ‘) separated string of capabilities supported by the server.

The capabilities represent extensions on the default IMAP protocol that are supported by the server.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  WScript.Echo objImap.LastImapResponse
  WScript.Echo objImap.Capabilities
  
  ' ...  
  
  objImap.Disconnect

Exists property

Total number of emails that exist in the currently selected mailbox.

The Imap component automatically updates this information based on unsolicited fetch data that may be sent by the IMAP server as a response to any command.

To make sure this information is always current try to periodically call the Noop method.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  objImap.Select "INBOX"
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  WScript.Echo "Total: " & objImap.Exists
  WScript.Echo "Unseen: " & objImap.Unseen
  WScript.Echo "Recent: " & objImap.Recent
  WScript.Echo "Next UID: " & objImap.UidNext
  
  ' ...  
  
  objImap.Disconnect

Recent property

The number of recent messages in the currently selected mailbox.

The Imap component automatically updates this information based on unsolicited fetch data that may be sent by the IMAP server as a response to any command.

To make sure this information is always current try to periodically call the Noop method.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  objImap.Select "INBOX"
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  WScript.Echo "Total: " & objImap.Exists
  WScript.Echo "Unseen: " & objImap.Unseen
  WScript.Echo "Recent: " & objImap.Recent
  WScript.Echo "Next UID: " & objImap.UidNext
  
  ' ...  
  
  objImap.Disconnect

Unseen property

The number of unseen emails that exist in the currently selected mailbox.

The Imap component automatically updates this information based on unsolicited fetch data that may be sent by the IMAP server as a response to any command.

To make sure this information is always current try to periodically call the Noop method.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  objImap.Select "INBOX"
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  WScript.Echo "Total: " & objImap.Exists
  WScript.Echo "Unseen: " & objImap.Unseen
  WScript.Echo "Recent: " & objImap.Recent
  WScript.Echo "Next UID: " & objImap.UidNext
  
  ' ...  
  
  objImap.Disconnect

UidNext property

The next UID that will be used by the IMAP server.

The Imap component automatically updates this information based on unsolicited fetch data that may be sent by the IMAP server as a response to any command.

To make sure this information is always current try to periodically call the Noop method.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  objImap.Select "INBOX"
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If
  
  WScript.Echo "Total: " & objImap.Exists
  WScript.Echo "Unseen: " & objImap.Unseen
  WScript.Echo "Recent: " & objImap.Recent
  WScript.Echo "Next UID: " & objImap.UidNext
  
  ' ...  
  
  objImap.Disconnect

IdleResetTimeMin property

Contains the reset timeout for the Idle command.

The Idle command automatically resets every couple of minutes to prevent the IMAP server from disconnecting this Imap client because of inactivity.

Set this value to 0 to disable automatically resetting the idle state.

The default value is 25 minutes.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' ... setup connection
  
  objImap.IdleResetTimeMin = 25
  
  objImap.Select "INBOX"
  nOldExists = objImap.Exists
  While objImap.IsConnected
  
    objImap.Idle    
    If objImap.Exists <> nOldExists Then
      objImap.IdleDone
      nOldExists = objImap.Exists
      
      ' ... fetch unseen e-mails
      
    End If  
  
    objImap.Sleep 100
  WEnd
  
  ' ... Disconnect

TimeoutConnect property

Contains the connection timeout. If a connection could not be established within this time the connection is aborted.

The default value is 5000 milliseconds.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.TimeoutConnect = 5000
  objImap.TimeoutCommand = 5000
  objImap.TimeoutAppend = 60000
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If  
  
  ' ...  
  
  objImap.Disconnect

TimeoutCommand property

Contains the command timeout. If an IMAP server does not respond to any command within this time the command as well as the connection is aborted.
This goes for any command except for Append which has its own TimeoutAppend property.

The default value is 5000 milliseconds.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.TimeoutConnect = 5000
  objImap.TimeoutCommand = 5000
  objImap.TimeoutAppend = 60000
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If  
  
  ' ...  
  
  objImap.Disconnect

TimeoutAppend property

Contains the timeout for appending a new message to the currently selected mailbox. This timeout is only relevant to the Append method.

Set this value to 0 to disable the timeout and wait forever for the append method to complete.

The default value is 0.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.TimeoutConnect = 5000
  objImap.TimeoutCommand = 5000
  objImap.TimeoutAppend = 60000
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If  
  
  ' ...  
  
  objImap.Disconnect

FetchMaxNumItemsAtOnce property

This setting is used by all fetch commands: FetchFirst/FetchNext, FetchFirstEmail/FetchNextEmail, FetchFirstEmailHeader/FetchNextEmailHeader.

It determines the number of fetch items that are cached by the Imap component.

Generally speaking a higher number will increase the speed of the Imap component at the expense of memory usage. When fetching small items, like envelope data, a higher value is recommended. When fetching large items, like full email messages, a smaller number is recommended.

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' ... Connect to IMAP Server

  objImap.FetchMaxNumItemsAtOnce = 100
  Set objFetchData = objImap.FetchFirst(objConstants.IMAP_SK_ALL, objConstants.IMAP_FM_ALL)
  While objImap.LastError = 0
    
    WScript.Echo objFetchData.Text
  
    Set objFetchData = objImap.FetchNext
  WEnd
    
  ' ... Other stuff
  
  objImap.Disconnect

MaximumPendingFetchData property

The maximum number of unsolicited fetch items that will be kept by the Imap component.

Unsolicited fetch data can be collected and removed from the queue by calling GetPendingFetchData.

Unsolicited fetch data will normally only be email flag updates that are sent by the IMAP server when a different client changes or causes changes in the flags of messages in a mailbox that is currently selected.

The default setting is 256 fetch items

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.MaximumPendingFetchData = 100
  objImap.MaximumPendingExpunged = 100
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If  
  
  ' ...  
  
  objImap.Disconnect

MaximumPendingExpunged property

The maximum number of pending expunged notification that are kept by the Imap component

Expunge notifications are sent by the IMAP Server when an email message is deleted from the currently selected mailbox. Expunge notifications are always sent for the current session as well as any other session that may be running at the same time on the same mailbox.

The default setting is 1024 expunge notifications

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.MaximumPendingFetchData = 100
  objImap.MaximumPendingExpunged = 100
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If  
  
  ' ...  
  
  objImap.Disconnect

UseSequenceNumForStoreAndCopy property

Use sequence numbers instead of UID’s to identify messages with the Store and Copy methods.

The default value is ‘False’

Example

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  objImap.UseSequenceNumForStoreAndCopy = False  
  objImap.Connect strServer, strServerAccount, strServerPassword 
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If  
  
  ' ...  
  
  objImap.Disconnect

Clear method

This function resets all properties to their default values.

Parameters:

None

Return value:

Always 0.

Example:

Set objImap = CreateObject("AxEmail.Imap")   
....
objPop3.Clear
...

SaveLicenseKey method

Description:

Use SaveLicenseKey to store the license key permanently in the registry.
When a license key is saved, it is restored automatically every time a new instance of the object is created.
It is not recommended to save the license key if you distribute the component with your own software,
because the key can be easily used by others.

Parameters:

None.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objImap = CreateObject("AxEmail.Imap")                 ' Create new instance
objImap.LicenseKey = "XXXXX-XXXXX-XXXXX"
objImap.SaveLicenseKey                                     ' Save license key to registry

For more information, see Product Activation.

GetErrorDescription method

GetErrorDescription provides the error description of a given error code.

Parameters:

The error code

Return value:

The error string.

Example:

Set objImap = CreateObject("AxEmail.Imap")
...
WScript.Echo" result:"  & objImap.LastError &" ,"  & _
  objImap.GetErrorDescription(objImap.LastError)

Sleep method

This function suspends the current thread for the specified number of milliseconds.

Parameters:

Milliseconds to sleep

Return value:

Always 0.

Example:

Set objImap = CreateObject("AxEmail.Imap")
...
objImap.Sleep 1000
...

SetSecure method

This function enables TLS/SSL and sets the correct port number.

Parameters:

Port number. Default: 993

Return value:

Always 0.

Example:

Set objImap = CreateObject("AxEmail.Imap")
Set objMail = CreateObject("AxEmail.Message")
...
objImap.SetSecure
objImap.Connect "imap.gmail.com", "me@gmail.com", "password"
If objImap.LastError <> 0 Then
  WScript.Echo "Error:"  & objImap.GetErrorDescription(objImap.LastError)  
  WScript.Quit
End If
...

Connect method

This function connects to the IMAP server.

Parameters:

Hostname
Account
Password

Return value:

Always 0.

Example:

Set objImap = CreateObject("AxEmail.Imap")
Set objMail = CreateObject("AxEmail.Message")
...  
objImap.Connect "imap.gmail.com", "me@gmail.com", "password"
If objImap.LastError <> 0 Then
  WScript.Echo "Error:"  & objImap.GetErrorDescription(objImap.LastError)  
  WScript.Quit
End If
...

Disconnect method

This function disconnects from the IMAP server.

Parameters:

None

Return value:

Always 0.

Example:

Set objImap = CreateObject("AxEmail.Imap")
Set objMail = CreateObject("AxEmail.Message")
...  
objImap.Connect "imap.gmail.com", "me@gmail.com", "password"
If objImap.LastError <> 0 Then
  WScript.Echo "Error:"  & objImap.GetErrorDescription(objImap.LastError)  
  WScript.Quit
End If
...
objImap.Disconnect

IsConnected method

This function returns the connected state. True is connected, False if not connected.

Parameters:

None

Return value:

Always 0.

Example:

Set objImap = CreateObject("AxEmail.Imap")
Set objMail = CreateObject("AxEmail.Message")
...  
objImap.Connect "imap.gmail.com", "me@gmail.com", "password"
If objImap.LastError <> 0 Then
  WScript.Echo "Error:"  & objImap.GetErrorDescription(objImap.LastError)  
  WScript.Quit
End If
...
WScript.Echo objImap.IsConnected
...
objImap.Disconnect

Select method

Select a mailbox to manipulate.

The properties Exists, Recent Unseen and UidNext
are updated according to the selected/examined mailbox. Unsolicited fetch and expunge responses will always be related to the selected/examined mailbox.

Use Close or Select/Examine a different mailbox to close a selected/examined mailbox.

Closing a mailbox will cause the server make any changes permanent if they have not been made permanent already by the server.

The mailbox: ‘INBOX’ is the default mailbox for incoming email that should always be present.

Parameters

Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  ' ... 
    
  objImap.SetSecure
  objImap.Connect strServer, strAccount, strPassword
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If

  objImap.Select "INBOX"
  WScript.Echo "Total: " & objImap.Exists
  WScript.Echo "Unseen: " & objImap.Unseen
  WScript.Echo "Recent: " & objImap.Recent
  WScript.Echo "Next UID: " & objImap.UidNext
  
  ' ...
  
  objImap.Disconnect

Examine method

Select a mailbox to inspect without making changes

Use Close or Select/Examine a different mailbox to close a selected/examined mailbox.

It’s not possible to make changes to the mailbox when it is examined. To make changes please use Select.

The mailbox: ‘INBOX’ is the default mailbox for incoming email that should always be present.

Parameters

Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  ' ... 
    
  objImap.SetSecure
  objImap.Connect strServer, strAccount, strPassword
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If

  objImap.Examine "INBOX"
  WScript.Echo "Total: " & objImap.Exists
  WScript.Echo "Unseen: " & objImap.Unseen
  WScript.Echo "Recent: " & objImap.Recent
  WScript.Echo "Next UID: " & objImap.UidNext
  
  ' ...
  
  objImap.Disconnect

Status method

Update this Imap object to reflect the status of the given mailbox without selecting to that mailbox.

The propeties Exists, Recent Unseen and UidNext
will be updated but the selected/examined mailbox is not changed. Unsolicited fetch and expunge responses
will still be related to the previously selected/examined mailbox.

Parameters

Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
    
  ' ... 
    
  objImap.SetSecure
  objImap.Connect strServer, strAccount, strPassword
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If

  objImap.Status "INBOX"
  WScript.Echo "Total: " & objImap.Exists
  WScript.Echo "Unseen: " & objImap.Unseen
  WScript.Echo "Recent: " & objImap.Recent
  WScript.Echo "Next UID: " & objImap.UidNext
  
  ' ...
  
  objImap.Disconnect

Close method

Close the selected mailbox and make any changes permanent

Parameters

None

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Select "Drafts"  
     
  ' .. delete the message referenced by nUid and close the mailbox
  objImap.Store nUid, objConstants.IMAP_MAIL_FLAG_DELETED, objConstants.IMAP_STO_ADD  
  objImap.Close
    
  ' .. do other stuff

Create method

Create a new mailbox.

It’s possible to use the HierarchySeparator to create sub-mailboxes to existing mailboxes.

Parameters

Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Create "Drafts" & objImap.HierarchySeparator & "Test"
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Delete method

Delete the given mailbox

Parameters

Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Delete "Drafts" & objImap.HierarchySeparator & "Test"
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Rename method

Rename the given mailbox

Parameters

Original mailbox name
New mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Rename "Drafts" & objImap.HierarchySeparator & "Test", _
    "Drafts" & objImap.HierarchySeparator & "Test_Renamed"
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Subscribe method

Subscribe to the given mailbox

Parameters

Mailbox name

The subscribe option is intended to make managing easier when there are a large number of mailboxes present or when IMAP is used for browsing Usenet servers.

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Subscribe "comp.programming"
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Unsubscribe method

Unsubscribe from the given mailbox

Parameters

Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Unsubscribe "comp.lang.java"
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Copy method

Copy email messages in ID set to target mailbox

The ID set is composed of either UID’s or sequence numbers depending on the value of UseSequenceNumForStoreAndCopy.

Multiple ID’s are separated by a ‘,’. Ranges are indicated with a ‘:’. No whitespace is allowed. Example: 3,10:15 will copy messages 3 and 10 to 15.

Parameters

ID set
Target mailbox name

Return Value

Always 0

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Copy "3,10:15", "INBOX"
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Store method

Use store to update the email flags of a given set of messages.

The ID set is composed of either UID’s or sequence numbers depending on the value of UseSequenceNumForStoreAndCopy.

Multiple ID’s are separated by a ‘,’. Ranges are indicated with a ‘:’. No whitespace is allowed. Example: 3,10:15 will copy messages 3 and 10 to 15.

Applicable flags can be found here.

Applicable options can be found here.

NOTE: To delete an email set the flag IMAP_MAIL_FLAG_DELETED and call Expunge

Parameters

ID set
Flags
Option

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Store "3,10:15", objConstants.IMAP_MAIL_FLAG_DELETED, objConstants.IMAP_STO_ADD  
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Noop method

No Operation. This operation does nothing on the server.

The Noop method is intended to be used to retrieve unsolicited fetch data as well as unsolicited expunge ID’s.

When the connection is idle. Periodically call the Noop method and subsequently call GetPendingFetchData and GetPendingExpunged
until LastError is set after calling either of those functions.

The properties Exists, Recent Unseen and UidNext are updated after calling Noop.

Parameters

None

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  While objImap.IsConnected    

    objImap.Noop
    
    ' get all fetch data; they will be email flags that are updated
    Set objFetchData = objImap.GetPendingFetchData
    While objImap.LastError = 0
      WScript.echo objFetchData.Text
      Set objFetchData = objImap.GetPendingFetchData
    WEnd
  
    ' get all expunged data; they will be sequence numbers of deleted messages
    nExpunged = objImap.GetPendingExpunged
    While objImap.LastError = 0
      WScript.Echo nExpunged
      nExpunged = objImap.GetPendingExpunged
    WEnd
  
    ' ... do other stuff ... 
  
    objImap.Sleep 5000
  WEnd  
  
  ' ... disconnect

Check method

Requests the server to do any implementation depended internal housekeeping

The use of this command depends on the IMAP server implementation.

Parameters

None

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Check
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If
         
  ' .. do other stuff

Expunge method

Permanently removes messages that are flagged for deletion using the Store method.

Use GetPendingExpunged to find the sequence numbers of messages that have been deleted.

Parameters

None

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Store "3,10:15", objConstants.IMAP_MAIL_FLAG_DELETED, objConstants.IMAP_STO_ADD  
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If

  objImap.Expunge
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If

  nExpunged = objImap.GetPendingExpunged
  While objImap.LastError = 0
    WScript.Echo nExpunged
    nExpunged = objImap.GetPendingExpunged
  WEnd
  
  ' .. do other stuff

Idle method

Go to IDLE state to receive real-time notifications. While in IDLE state the remote IMAP server automatically keeps this Imap object up-to-date.

This feature is optional in the IMAP protocol. Use the HasCapability function to make sure the server has support for the ‘IDLE’ capability.

Call this function for the first time to go to IDLE state and check the LastError property to make sure it succeeded.

Continue to call this function regularly to automatically update the Exists and Recent properties.

Calling this function may also result in pending fetch data and pending expunged sequences.

Continuously calling this function will automatically reset the IDLE state after ‘PropIdleResetTimeMin‘ minutes. This prevents the IMAP server from disconnecting due to inactivity.

Make sure to call IdleDone before doing anything else.

Parameters

None

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' ... setup connection
  
  objImap.IdleResetTimeMin = 25
  
  objImap.Select "INBOX"
  nOldExists = objImap.Exists
  While objImap.IsConnected
  
    objImap.Idle    
    If objImap.Exists <> nOldExists Then
      objImap.IdleDone
      nOldExists = objImap.Exists
      
      ' ... fetch unseen e-mails
      
    End If  
  
    objImap.Sleep 100
  WEnd
  
  ' ... Disconnect

IdleDone method

Call this function to exit from the IDLE state.

While in IDLE the server cannot accept any other commands such as ‘List’ or ‘Fetch’ commands.

Parameters

None

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' ... setup connection
  
  objImap.IdleResetTimeMin = 25
  
  objImap.Select "INBOX"
  nOldExists = objImap.Exists
  While objImap.IsConnected
  
    objImap.Idle    
    If objImap.Exists <> nOldExists Then
      objImap.IdleDone
      nOldExists = objImap.Exists
      
      ' ... fetch unseen e-mails
      
    End If  
  
    objImap.Sleep 100
  WEnd
  
  ' ... Disconnect

GetPendingExpunged method

Get the next sequence number of a message that was deleted.

NOTE: After every sequence number that was retrieved all of the sequence numbers on the server are updated.
Example: The mailbox has messages with sequence number: 1, 2, 3. Messages 2 and 3 are deleted. GetPendingExpunged will return 2, 2 subsequently.

Parameters

None

Return Value

Sequence number of deleted message

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' .. setup connection .. 
  
  objImap.Store "3,10:15", objConstants.IMAP_MAIL_FLAG_DELETED, objConstants.IMAP_STO_ADD  
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If

  objImap.Expunge
  If objImap.LastError <> Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1  
  End If

  nExpunged = objImap.GetPendingExpunged
  While objImap.LastError = 0
    WScript.Echo nExpunged
    nExpunged = objImap.GetPendingExpunged
  WEnd
  
  ' .. do other stuff

GetPendingFetchData method

Returns the next unsolicited pending ImapFetchData object.

These fetch data packets may be sent by the server to notify a client that a different client caused the server to update message flags.

Parameters

None

Return Value

ImapFetchData

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  While objImap.IsConnected    

    objImap.Noop
    
    ' get all fetch data; they will be email flags that are updated
    Set objFetchData = objImap.GetPendingFetchData
    While objImap.LastError = 0
      WScript.echo objFetchData.Text
      Set objFetchData = objImap.GetPendingFetchData
    WEnd
  
    ' get all expunged data; they will be sequence numbers of deleted messages
    nExpunged = objImap.GetPendingExpunged
    While objImap.LastError = 0
      WScript.Echo nExpunged
      nExpunged = objImap.GetPendingExpunged
    WEnd
  
    ' ... do other stuff ... 
  
    objImap.Sleep 5000
  WEnd  
  
  ' ... disconnect

List method

List mailboxes on the server.

To access the mailbox information use the methods ListCount, ListName and ListAttributes.

The reference path is the like the working directory on a file system. The mailbox name is like the file specification after the ‘dir’ command on a file system.

Leave the reference empty (“”) to use an absolute mailbox name like used in the Select method.

The following wild cards are supported:

* – Maches zero or more characters at this position. Including the hierarchy separator
% – Maches zero or more characters at this position. Not including the hierarchy separator

NOTE: Since the server may support symbolic linking sub-mailboxes to super mailboxes infinitely recursive mailboxes may exist. Therefore the client must guard against this by prefering to use ‘%’ over ‘*’ and limiting recurse depth.

Parameters

Reference path
Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.List "", "%"      ' list all emails directly in the root
  WScript.Echo "List, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  WScript.Echo
  
  nCount = objImap.ListCount
  WScript.Echo "Found " & objImap.ListCount & " mailboxes:"
  If nCount > 0 Then
    For i = 0 To nCount - 1
      strMailboxName = objImap.ListName(i)
      strMailboxAttributes = objImap.ListAttributes(i)
      
      WScript.Echo "  "  & strMailboxName & ": " & strMailboxAttributes
    Next
  End If

  ' ... do other stuff

ListSubscribed method

Works the same as MethList only on the subscribed mailboxes.

Parameters

Reference path
Mailbox name

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.ListSubscribed "", "%"      ' list all emails directly in the root
  WScript.Echo "List, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  WScript.Echo
  
  nCount = objImap.ListCount
  WScript.Echo "Found " & objImap.ListCount & " mailboxes:"
  If nCount > 0 Then
    For i = 0 To nCount - 1
      strMailboxName = objImap.ListName(i)
      strMailboxAttributes = objImap.ListAttributes(i)
      
      WScript.Echo "  "  & strMailboxName & ": " & strMailboxAttributes
    Next
  End If

  ' ... do other stuff

ListCount method

Use this method after calling either List or ListSubscribed to get the number of items listed.

Parameters

None

Return Value

Number of mailboxes listed

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.ListSubscribed "", "%"      ' list all emails directly in the root
  WScript.Echo "List, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  WScript.Echo
  
  nCount = objImap.ListCount
  WScript.Echo "Found " & objImap.ListCount & " mailboxes:"
  If nCount > 0 Then
    For i = 0 To nCount - 1
      strMailboxName = objImap.ListName(i)
      strMailboxAttributes = objImap.ListAttributes(i)
      
      WScript.Echo "  "  & strMailboxName & ": " & strMailboxAttributes
    Next
  End If

  ' ... do other stuff

ListAttributes method

Use this method after calling either List or ListSubscribed to get the attributes of the item listed at the given index.

Find a list of possible mailbox flags here.

Parameters

List index

Return Value

Mailbox flags

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.ListSubscribed "", "%"      ' list all emails directly in the root
  WScript.Echo "List, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  WScript.Echo
  
  nCount = objImap.ListCount
  WScript.Echo "Found " & objImap.ListCount & " mailboxes:"
  If nCount > 0 Then
    For i = 0 To nCount - 1
      strMailboxName = objImap.ListName(i)
      strMailboxAttributes = objImap.ListAttributes(i)
      
      WScript.Echo "  "  & strMailboxName & ": " & strMailboxAttributes
    Next
  End If

  ' ... do other stuff

ListHasAttribute method

Use this method after calling either List or ListSubscribed to find out if an attribute is present on the item listed at the given index.

Find a list of possible mailbox flags here.

Parameters

List index
Mailbox flag

Return Value

True if the flag was set else false

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.ListSubscribed "", "%"      ' list all emails directly in the root
  WScript.Echo "List, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  WScript.Echo
  
  nCount = objImap.ListCount
  WScript.Echo "Found " & objImap.ListCount & " mailboxes:"
  If nCount > 0 Then
    For i = 0 To nCount - 1
      strMailboxName = objImap.ListName(i)
      strMailboxAttributes = objImap.ListAttributes(i)
      
      WScript.Echo "  "  & strMailboxName & ": " & strMailboxAttributes
      WScript.Echo "Cannot select: " & objImap.ListHasAttribute(i, objConstants.IMAP_MBX_FLAG_NOSELECT)
    Next
  End If

  ' ... do other stuff

ListName method

Use this method after calling either List or ListSubscribed to find out if an attribute is present on the item listed at the given index.

Parameters

List index

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.ListSubscribed "", "%"      ' list all emails directly in the root
  WScript.Echo "List, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  WScript.Echo
  
  nCount = objImap.ListCount
  WScript.Echo "Found " & objImap.ListCount & " mailboxes:"
  If nCount > 0 Then
    For i = 0 To nCount - 1
      strMailboxName = objImap.ListName(i)
      strMailboxAttributes = objImap.ListAttributes(i)
      
      WScript.Echo "  "  & strMailboxName & ": " & strMailboxAttributes
    Next
  End If

  ' ... do other stuff

FetchFirstEmail method

Fetch the first email that matches the given search criteria use FetchNextEmail to find subsequent messages based on the same query message.

The search command is a query string. Search keywords can be found here.

Searching for all, unseen or recent messages can be done by simply using ‘IMAP_SK_ALL’, ‘IMAP_SK_UNSEEN’ or ‘IMAP_SK_RECENT’ constants.

Some queries may require a date. To make sure the date is formatted in the right way use the helper function FormatDate.

Find more detailed information on how to formulate more complicated queries here.

Parameters

Search criteria

Return Value

Message

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  Set objEmail = objImap.FetchFirstEmail(objConstants.IMAP_SK_UNSEEN)
  While objImap.LastError = 0
    
    WScript.Echo "MessageID        : " & objEmail.ImapUID
    WScript.Echo "   From          : " & objEmail.FromAddress
    WScript.Echo "   From Name     : " & objEmail.FromName
    WScript.Echo "   To            : " & objEmail.ToAddress
    WScript.Echo "   Subject       : " & objEmail.Subject
    WScript.Echo "   Date          : " & objEmail.Date  
    WScript.Echo vbCrLf 
  
    Set objEmail = objImap.FetchNextEmail
  WEnd

  ' ... do other stuff

FetchNextEmail method

Fetch any subsequent email messages matching the query from FetchFirstEmail.

Parameters

None

Return Value

Message

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  Set objEmail = objImap.FetchFirstEmail(objConstants.IMAP_SK_UNSEEN)
  While objImap.LastError = 0
    
    WScript.Echo "MessageID        : " & objEmail.ImapUID
    WScript.Echo "   From          : " & objEmail.FromAddress
    WScript.Echo "   From Name     : " & objEmail.FromName
    WScript.Echo "   To            : " & objEmail.ToAddress
    WScript.Echo "   Subject       : " & objEmail.Subject
    WScript.Echo "   Date          : " & objEmail.Date  
    WScript.Echo vbCrLf 
  
    Set objEmail = objImap.FetchNextEmail
  WEnd

  ' ... do other stuff

FetchFirstEmailHeader method

Fetch the first email header that matches the given search criteria use FetchNextEmailHeader to find subsequent email headers based on the same query message.

This returns an email object that only contains the headers of the message. So the will be no message body or attachments available.

Parameters

Search criteria

Return Value

Message

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  Set objEmail = objImap.FetchFirstEmailHeader(objConstants.IMAP_SK_UNSEEN)
  While objImap.LastError = 0
    
    WScript.Echo "MessageID        : " & objEmail.ImapUID
    WScript.Echo "   From          : " & objEmail.FromAddress
    WScript.Echo "   From Name     : " & objEmail.FromName
    WScript.Echo "   To            : " & objEmail.ToAddress
    WScript.Echo "   Subject       : " & objEmail.Subject
    WScript.Echo "   Date          : " & objEmail.Date  
    WScript.Echo vbCrLf 
  
    Set objEmail = objImap.FetchNextEmailHeader
  WEnd

  ' ... do other stuff

FetchNextEmailHeader method

Fetch any subsequent email headers matching the query from FetchFirstEmailHeader.

Parameters

None

Parameters

None

Return Value

Message

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  Set objEmail = objImap.FetchFirstEmailHeader(objConstants.IMAP_SK_UNSEEN)
  While objImap.LastError = 0
    
    WScript.Echo "MessageID        : " & objEmail.ImapUID
    WScript.Echo "   From          : " & objEmail.FromAddress
    WScript.Echo "   From Name     : " & objEmail.FromName
    WScript.Echo "   To            : " & objEmail.ToAddress
    WScript.Echo "   Subject       : " & objEmail.Subject
    WScript.Echo "   Date          : " & objEmail.Date  
    WScript.Echo vbCrLf 
  
    Set objEmail = objImap.FetchNextEmailHeader
  WEnd

  ' ... do other stuff

FetchFirst method

Build a custom fetch request consisting of search criteria as well as a fetch specification. Find subsequent items using FetchNext.

Refer to FetchFirstEmail to find more information about the search criteria that are possible.

The fetch specification can be defined using either these constants or one of these fetch macros.

For more complicated fetch specification options have a look here.

Parameters

Search criteria
Fetch items specification

Return Value

ImapFetchData

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  Set objFetchData = objImap.FetchFirst(objConstants.IMAP_SK_ALL, objConstants.IMAP_FM_ALL)
  While objImap.LastError = 0
    
    ' Get the top-level envelope element from the fetch data
    Set objEnvelope = objFetchData.GetSubDataByName("ENVELOPE")
    Set objFrom = objEnvelope.GetSubData(2).GetSubData(0)
    Set objTo = objEnvelope.GetSubData(4).GetSubData(0)
    
    WScript.Echo "Email UID: " & objFetchData.GetSubDataByName("UID").Value
    WScript.Echo "  Date: "    & objEnvelope.GetSubData(0).Value
    WScript.Echo "  From: "    & objFrom.GetSubData(2).Value & "@" & objFrom.GetSubData(3).Value
    WScript.Echo "  To: "      & objTo.GetSubData(2).Value & "@" & objTo.GetSubData(3).Value
    WScript.Echo "  Subject: " & objEnvelope.GetSubData(1).Value
    WScript.Echo
    
    Set objFetchData = objImap.FetchNext
  WEnd

  ' ... do other stuff

FetchNext method

Fetch any subsequent items that match the query specified in FetchFirst.

Parameters

None

Return Value

ImapFetchData

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objConstants = CreateObject("AxEmail.Constants")
  
  ' ... connect
  
  objImap.Select "INBOX"
  Set objFetchData = objImap.FetchFirst(objConstants.IMAP_SK_ALL, objConstants.IMAP_FM_ALL)
  While objImap.LastError = 0
    
    ' Get the top-level envelope element from the fetch data
    Set objEnvelope = objFetchData.GetSubDataByName("ENVELOPE")
    Set objFrom = objEnvelope.GetSubData(2).GetSubData(0)
    Set objTo = objEnvelope.GetSubData(4).GetSubData(0)
    
    WScript.Echo "Email UID: " & objFetchData.GetSubDataByName("UID").Value
    WScript.Echo "  Date: "    & objEnvelope.GetSubData(0).Value
    WScript.Echo "  From: "    & objFrom.GetSubData(2).Value & "@" & objFrom.GetSubData(3).Value
    WScript.Echo "  To: "      & objTo.GetSubData(2).Value & "@" & objTo.GetSubData(3).Value
    WScript.Echo "  Subject: " & objEnvelope.GetSubData(1).Value
    WScript.Echo
    
    Set objFetchData = objImap.FetchNext
  WEnd

  ' ... do other stuff

Append method

Append a new email message to the given mailbox.

NOTE: This will not send an email but just append it to a given mailbox.

Parameters

Mailbox name
Message
Flags
Date/Time

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")
  Set objEmail = CreateObject("AxEmail.Message")
  Set objConstants = CreateObject("AxEmail.Constants")

  ' ... connect ...
  
  objEmail.FromAddress = "bill.gates@microsoft.com"
  objEmail.AddTo strAccount & "@" & strServer
  objEmail.Subject = "I desperately need your opinion"
  objEmail.BodyPlainText = "Where should we go next with Microsoft?"  
   
  objImap.Append "Travel", objEmail
  WScript.Echo "Append, result: " & objImap.LastError & _
    " (" & objImap.GetErrorDescription( objImap.LastError ) & ")"
  
  ' ... do other stuff ...

HasCapability method

Find out if the server supports the given capability.

Parameters

Capability name

Return Value

True if the given capability is supported else False

Example:

  Set objImap = CreateObject("AxEmail.Imap")  
  Set objConstants = CreateObject("AxEmail.Constants")
  
  objImap.SetSecure
  objImap.Connect strServer, strAccount, strPassword
  If objImap.LastError <> 0 Then 
    WScript.Echo objImap.GetErrorDescription(objImap.LastError)
    WScript.Quit 1
  End If

  WScript.Echo objImap.HasCapability("SPECIAL-USE")
  
  ' ...
  
  objImap.Disconnect

FormatDate method

Helper to format a date. This can be used in all of the fetch methods in the search criteria.

Parameters

Year
Month
Day

Return Value

Date string

Example:

  Set objImap = CreateObject("AxEmail.Imap")  

  ' ...
  
  WScript.Echo objImap.FormatDate(2018, 11, 27)
  
  ' ...

FormatTime method

Helper to format a time. This can be used, together with FormatDate in Append.

Parameters

Hour
Minute
Second
Timezone + Daylight saving offset in minutes

Return Value

Always 0

Example:

  Set objImap = CreateObject("AxEmail.Imap")  

  ' ...
  
  WScript.Echo objImap.FormatTime(14, 25, 00, 60)
  
  ' ...

How can we help?

AxEmail.Imap

Introduction

Properties and Methods

Version property

Build property

Module property

LicenseStatus property

LicenseKey property

LastError property

LogFile property

HostPort property

Authentication property

BearerToken property

UseStartTls property

AutoClose property

IpVersion property

Secure property

LastImapResponse property

HierarchySeparator property

Capabilities property

Exists property

Recent property

Unseen property

UidNext property

IdleResetTimeMin property

TimeoutConnect property

TimeoutCommand property

TimeoutAppend property

FetchMaxNumItemsAtOnce property

MaximumPendingFetchData property

MaximumPendingExpunged property

UseSequenceNumForStoreAndCopy property

Clear method

SaveLicenseKey method

GetErrorDescription method

Sleep method

SetSecure method

Connect method

Disconnect method

IsConnected method

Select method

Examine method

Status method

Close method

Create method

Delete method

Rename method

Subscribe method

Unsubscribe method

Copy method

Store method

Noop method

Check method

Expunge method

Idle method

IdleDone method

GetPendingExpunged method

GetPendingFetchData method

List method

ListSubscribed method

ListCount method

ListAttributes method

ListHasAttribute method

ListName method

FetchFirstEmail method

FetchNextEmail method

FetchFirstEmailHeader method

FetchNextEmailHeader method

FetchFirst method

FetchNext method

Append method

HasCapability method

FormatDate method

FormatTime method