CkImap Python Programming
Reference Documentation
CkImap
IMAP email component.
Object Creation
obj = chilkat.CkImap()
Properties
# Returns a boolean value
get_AppendSeen( )
# alreadySeen is a boolean (input)
put_AppendSeen( alreadySeen )
When True (the default) the Append method will mark the email appended to a mailbox as already seen. Otherwise an appended email will be initialized to have a status of unseen.
# Returns an integer value
get_AppendUid( )
The UID of the last email appended to a mailbox via an Append* method. (Not all IMAP servers report back the UID of the email appended.)
# str is a CkString object (output)
get_AuthMethod( str )
# str is a string (input)
put_AuthMethod( str )
Can be set to "CRAM-MD5", "NTLM", "PLAIN", or "LOGIN" to select the authentication method. NTLM is the most secure, and is a synonym for "Windows Integrated Authentication". The default is "LOGIN" (or the empty string) which is simple plain-text username/password authentication. Not all IMAP servers support all authentication methods.
# str is a CkString object (output)
get_AuthzId( str )
# newVal is a string (input)
put_AuthzId( newVal )
Applies to the PLAIN authentication method. May be set to an authorization ID that is to be sent along with the Login and Password for authentication.
# Returns a boolean value
get_AutoFix( )
# newVal is a boolean (input)
put_AutoFix( newVal )
If True, then the following will occur when a connection is made to an IMAP server:
1) If the Port property = 993, then sets StartTls = False and Ssl = True
2) If the Port property = 143, sets Ssl = False
The default value of this property is True.
# str is a CkString object (output)
get_ClientIpAddress( str )
# newVal is a string (input)
put_ClientIpAddress( newVal )
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124". Important Bind to Adapter Notes for Windows
# Returns an integer value
get_ConnectTimeout( )
# numSec is an integer (input)
put_ConnectTimeout( numSec )
Maximum number of seconds to wait when connecting to an IMAP server. The default value is 30 (units are in seconds).
# str is a CkString object (output)
get_ConnectedToHost( str )
Contains the IMAP server's domain name (or IP address) if currently connected. Otherwise returns an empty string.
# str is a CkString object (output)
get_DebugLogFilePath( str )
# newVal is a string (input)
put_DebugLogFilePath( newVal )
Used for debugging in cases where a Chilkat method call hangs and never returns. This should generally never happen. The only causes for this are (1) a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired, (2) the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or (3) there is an internal problem (bug) in the Chilkat code that causes the hang.
This property allows one to specifiy a debug file path that will be created (or appended if it already exists) and information will be logged to it as the Chilkat methods are called. If a hang occurs, the log file may be viewed to get information about what happened.
# str is a CkString object (output)
get_Domain( str )
# str is a string (input)
put_Domain( str )
The Windows Domain to use for Windows Integrated Authentication (also known as NTLM). This may be empty.
# str is a CkString object (output)
get_HttpProxyAuthMethod( str )
# newVal is a string (input)
put_HttpProxyAuthMethod( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "LOGIN" or "NTLM".
# str is a CkString object (output)
get_HttpProxyHostname( str )
# newVal is a string (input)
put_HttpProxyHostname( newVal )
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation).
# str is a CkString object (output)
get_HttpProxyPassword( str )
# newVal is a string (input)
put_HttpProxyPassword( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password.
# Returns an integer value
get_HttpProxyPort( )
# newVal is an integer (input)
put_HttpProxyPort( newVal )
If an HTTP proxy is to be used, set this property to the HTTP proxy port number. (Two commonly used HTTP proxy ports are 8080 and 3128.)
# str is a CkString object (output)
get_HttpProxyUsername( str )
# newVal is a string (input)
put_HttpProxyUsername( newVal )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name.
# Returns a boolean value
get_KeepSessionLog( )
# newVal is a boolean (input)
put_KeepSessionLog( newVal )
Turns the in-memory session logging on or off. If on, the session log can be obtained via the SessionLog property. The default value is False.
The SessionLog contains the raw commands sent to the IMAP server, and the raw responses received from the IMAP server.
# str is a CkString object (output)
get_LastAppendedMime( str )
The MIME source of the email last appended during a call to AppendMail, or AppendMime.
# str is a CkString object (output)
get_LastCommand( str )
The last raw command sent to the IMAP server. (This information can be used for debugging if problems occur.)
# str is a CkString object (output)
LastErrorHtml( str )
Returns the error log in HTML format for the last method called.Error information in HTML format for the last method called.
# str is a CkString object (output)
LastErrorText( str )
Returns the error log in plain-text format for the last method called.Error information in plain-text format for the last method called.
# str is a CkString object (output)
LastErrorXml( str )
Returns the error log in XML format for the last method called.Error information in XML format for the last method called.
# str is a CkString object (output)
get_LastIntermediateResponse( str )
The last intermediate response received from the IMAP server. (This information can be used for debugging if problems occur.)
# str is a CkString object (output)
get_LastResponse( str )
The raw data of the last response from the IMAP server. (Useful for debugging if problems occur.)
# str is a CkString object (output)
get_LoggedInUser( str )
If logged into an IMAP server, the logged-in username.
# Returns an integer value
get_NumMessages( )
After selecting a mailbox (by calling SelectMailbox), this property will
be updated to reflect the total number of emails in the mailbox.
# Returns a boolean value
get_PeekMode( )
# bPeek is a boolean (input)
put_PeekMode( bPeek )
Set to true to prevent the mail flags (such as the "Seen" flag) from being set when email is retrieved. The default value of this property is false.
# Returns an integer value
get_Port( )
# port is an integer (input)
put_Port( port )
The IMAP port number. If using SSL, be sure to set this to the IMAP SSL port number, which is typically port 993. (If this is the case, make sure you also set the Ssl property = True.
# Returns an integer value
get_ReadTimeout( )
# numSec is an integer (input)
put_ReadTimeout( numSec )
The amount of time in seconds to wait during a stall before timing out when reading from an IMAP server. The ReadTimeout is the amount of time that needs to elapse while no additional data is forthcoming. During a long data transfer, if the data stream halts for more than this amount, it will timeout.
The default value is 30 seconds.
# str is a CkString object (output)
get_SelectedMailbox( str )
The currently selected mailbox, or an empty string if none.
# Returns an integer value
get_SendBufferSize( )
# newVal is an integer (input)
put_SendBufferSize( newVal )
The buffer size to be used with the underlying TCP/IP socket for sending. The default value is 32767.
# Returns a char
get_SeparatorChar( )
# c is a char (input)
put_SeparatorChar( c )
The separator character used by the IMAP server for the mailbox hierarchy.
# str is a CkString object (output)
get_SessionLog( str )
Contains an in-memory log of the raw commands sent to the IMAP server, and the raw responses received from the IMAP server. The KeepSessionLog property must be set to True to enable session logging. Call ClearSessionLog to reset the log.
# str is a CkString object (output)
get_SocksHostname( str )
# newVal is a string (input)
put_SocksHostname( newVal )
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
# str is a CkString object (output)
get_SocksPassword( str )
# newVal is a string (input)
put_SocksPassword( newVal )
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
# Returns an integer value
get_SocksPort( )
# newVal is an integer (input)
put_SocksPort( newVal )
The SOCKS4/SOCKS5 proxy port. The default value is 1080.
This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).
# str is a CkString object (output)
get_SocksUsername( str )
# newVal is a string (input)
put_SocksUsername( newVal )
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
# Returns an integer value
get_SocksVersion( )
# newVal is an integer (input)
put_SocksVersion( newVal )
SocksVersion
May be set to one of the following integer values:
0 - No SOCKS proxy is used. This is the default.
4 - Connect via a SOCKS4 proxy.
5 - Connect via a SOCKS5 proxy.
# Returns a boolean value
get_Ssl( )
# s is a boolean (input)
put_Ssl( s )
True if the IMAP connection should be TLS/SSL.
Note: The typical IMAP TLS/SSL port number is 993. If you set this property = True, it is likely that you should also set the Port property = 993.
# str is a CkString object (output)
get_SslProtocol( str )
# newVal is a string (input)
put_SslProtocol( newVal )
Selects the secure protocol to be used for secure (SSL/TLS) implicit and explicit (StartTls) connections . Possible values are:
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "TLS 1.0".
# Returns a boolean value
get_SslServerCertVerified( )
Read-only property that returns True if the IMAP server's digital certificate was verified when connecting via SSL / TLS.
# Returns a boolean value
get_StartTls( )
# newVal is a boolean (input)
put_StartTls( newVal )
If True, then the Connect method will (internallly) convert the connection to TLS/SSL via the STARTTLS IMAP command. This is called "explict SSL/TLS" because the client explicitly requests the connection be transformed into a TLS/SSL secure channel. The alternative is "implicit SSL/TLS" where the "Ssl" property is set to True and the IMAP client connects to the well-known TLS/SSL IMAP port of 993.
# Returns an integer value
get_UidNext( )
A positive integer value containing the UIDNEXT of the currently selected folder, or 0 if it's not available or no folder is selected.
# Returns an integer value
get_UidValidity( )
An integer value containing the UIDVALIDITY of the currently selected mailbox, or 0 if no mailbox is selected.
A client can save the UidValidity value for a mailbox and then compare it with the UidValidity on a subsequent session. If the new value is larger, the IMAP server is not keeping UID's unchanged between sessions. Most IMAP servers maintain UID's between sessions.
# Returns a boolean value
get_Utf8( )
# b is a boolean (input)
put_Utf8( b )
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
# str is a CkString object (output)
get_Version( str )
The version of the component, such as "1.0.0".
Methods
# pfxBytes is a CkByteData object (output)
# pfxPassword is a string (input)
# Returns a boolean value
AddPfxSourceData( pfxBytes, pfxPassword )
Adds a PFX to the object's internal list of sources to be searched for certificates and private keys when decrypting. Multiple PFX sources can be added by calling this method once for each. (On the Windows operating system, the registry-based certificate stores are also automatically searched, so it is commonly not required to explicitly add PFX sources.)
The pfxBytes contains the bytes of a PFX file (also known as PKCS12 or .p12).
# pfxFilePath is a string (input)
# pfxPassword is a string (input)
# Returns a boolean value
AddPfxSourceFile( pfxFilePath, pfxPassword )
Adds a PFX file to the object's internal list of sources to be searched for certificates and private keys when decrypting. Multiple PFX files can be added by calling this method once for each. (On the Windows operating system, the registry-based certificate stores are also automatically searched, so it is commonly not required to explicitly add PFX sources.)
The pfxFilePath contains the bytes of a PFX file (also known as PKCS12 or .p12).
# mailbox is a string (input)
# email is a CkEmail object (output)
# Returns a boolean value
AppendMail( mailbox, email )
Appends an email to an IMAP mailbox. Returns True for success, False for failure. Send Email and Save Copy to "Sent" Mailbox
# mailbox is a string (input)
# mimeText is a string (input)
# Returns a boolean value
AppendMime( mailbox, mimeText )
Appends an email (represented as MIME text) to an IMAP mailbox. Returns True for success, False for failure.
# mailbox is a string (input)
# mimeText is a string (input)
# internalDate is a SYSTEMTIME object (output)
# Returns a boolean value
AppendMimeWithDate( mailbox, mimeText, internalDate )
The same as AppendMime, but with an extra argument to allow the internal date of the email on the server to be explicitly specified.
# mailbox is a string (input)
# mimeText is a string (input)
# seen is a boolean (input)
# flagged is a boolean (input)
# answered is a boolean (input)
# draft is a boolean (input)
# Returns a boolean value
AppendMimeWithFlags( mailbox, mimeText, seen, flagged, answered, draft )
Same as AppendMime, but allows the flags associated with the email to be set at the same time. A flag is on if True, and off if False. Returns True for success, False for failure.
ClearSessionLog( )
Clears the contents of the SessionLog property.
# domainName is a string (input)
# Returns a boolean value
Connect( domainName )
Connects to an IMAP server, but does not login. The domainName is the domain name of the IMAP server. (May also use the IPv4 or IPv6 address in string format.) Returns True for success, False for failure.
# msgId is an integer (input)
# bUid is a boolean (input)
# copyToMailbox is a string (input)
# Returns a boolean value
Copy( msgId, bUid, copyToMailbox )
Copies a message from the selected mailbox to copyToMailbox.
If bUid is True, then msgId represents a UID. If bUid is False, then msgId represents a sequence number. Returns True for success, False for failure.
# messageSet is a CkMessageSet object (output)
# copyToMailbox is a string (input)
# Returns a boolean value
CopyMultiple( messageSet, copyToMailbox )
Same as the Copy method, except an entire set of emails is copied at once. The set of emails is specified in messageSet. Returns True for success, False for failure.
# startSeqNum is an integer (input)
# count is an integer (input)
# copyToMailbox is a string (input)
# Returns a boolean value
CopySequence( startSeqNum, count, copyToMailbox )
Copies one or more emails from one mailbox to another. The emails are specified as a range of sequence numbers. The 1st email in a mailbox is always at sequence number 1. Returns True for success, False for failure.
# mailbox is a string (input)
# Returns a boolean value
CreateMailbox( mailbox )
Creates a new mailbox. Returns True for success, False for failure.
# mailbox is a string (input)
# Returns a boolean value
DeleteMailbox( mailbox )
Deletes an existing mailbox. Returns True for success, False for failure.
# Returns a boolean value
Disconnect( )
Disconnects cleanly from the IMAP server. A non-success return from this method only indicates that the disconnect was not clean -- and this can typically be ignored. Returns True for success, False for failure.
# mailbox is a string (input)
# Returns a boolean value
ExamineMailbox( mailbox )
Selects a mailbox such that only read-only transactions are allowed. This method would be called instead of SelectMailbox if the logged-on user has read-only permission. Returns True for success, False for failure.
# Returns a boolean value
Expunge( )
Permanently removes from the currently selected mailbox all messages that have the Deleted flag set. Returns True for success, False for failure.
# Returns a boolean value
ExpungeAndClose( )
Permanently removes from the currently selected mailbox all messages that have the Deleted flag set, and closes the mailbox. Returns True for success, False for failure.
# messageSet is a CkMessageSet object (input)
# Returns a CkEmailBundle object
FetchBundle( messageSet )
Retrieves a set of messages from the IMAP server and returns them in an email bundle object. If the method fails, it may return a NULL reference. Returns a null reference on failure
# messageSet is a CkMessageSet object (input)
FetchBundleAsMime( messageSet )
Retrieves a set of messages from the IMAP server and returns them in a string array object (NOTE: it does not return a string array, but an object that represents a string array.) Each string within the returned object is the complete MIME source of an email. On failure, a NULL object reference is returned. Returns a null reference on failure
# startSeqNum is an integer (input)
# fetchCount is an integer (input)
# failedSet is a CkMessageSet object (output)
# fetchedSet is a CkMessageSet object (output)
# Returns a CkEmailBundle object
FetchChunk( startSeqNum, fetchCount, failedSet, fetchedSet )
Fetches a chunk of emails starting at a specific sequence number. A bundle of fetched emails is returned. The last two arguments are message sets that are updated with the ids of messages successfully/unsuccessfully fetched. Returns a null reference on failure
# msgId is an integer (input)
# bUid is a boolean (input)
# strFlags is a CkString object (output)
# Returns a boolean value
FetchFlags( msgId, bUid, strFlags )
Fetches the flags for an email. The bUid argument determines whether the msgId argument is a UID or sequence number. Returns True for success, False for failure.
# messageSet is a CkMessageSet object (input)
# Returns a CkEmailBundle object
FetchHeaders( messageSet )
Retrieves a set of message headers from the IMAP server and returns them in an email bundle object. If the method fails, it may return a NULL reference. The following methods are useful for retrieving information about attachments and flags after email headers are retrieved: GetMailNumAttach, GetMailAttachSize, GetMailAttachFilename, GetMailFlag. Returns a null reference on failure Read IMAP Email Headers
# startSeqNum is an integer (input)
# numMessages is an integer (input)
# Returns a CkEmailBundle object
FetchSequence( startSeqNum, numMessages )
Downloads email for a range of sequence numbers. The 1st email in a mailbox is always at sequence number 1. The total number of emails in the currently selected mailbox is available in the NumMessages property. If the numMessages is too large, the method will still succeed, but will return a bundle of emails from startSeqNum to the last email in the mailbox. Returns a null reference on failure
# startSeqNum is an integer (input)
# count is an integer (input)
FetchSequenceAsMime( startSeqNum, count )
Same as FetchSequence, but instead of returning email objects in a bundle, the raw MIME of each email is returned. Returns a null reference on failure
# startSeqNum is an integer (input)
# numMessages is an integer (input)
# Returns a CkEmailBundle object
FetchSequenceHeaders( startSeqNum, numMessages )
Same as FetchSequence, but only the email headers are returned. The email objects within the bundle will be lacking bodies and attachments. Returns a null reference on failure
# msgId is an integer (input)
# bUid is a boolean (input)
# Returns a CkEmail object
FetchSingle( msgId, bUid )
Retrieves a single message from the IMAP server. If the method fails, it may return a NULL reference.
If bUid is true, then msgID represents a UID. If bUid is false, then msgID represents a sequence number. Returns a null reference on failure IMAP Download All Email as MIME One at a Time
# msgId is an integer (input)
# bUid is a boolean (input)
# strMime is a CkString object (output)
# Returns a boolean value
FetchSingleAsMime( msgId, bUid, strMime )
Retrieves a single message from the IMAP server and returns a string containing the complete MIME source of the email. If the method fails, it returns a NULL reference. If bUid is true, then msgID represents a UID. If bUid is false, then msgID represents a sequence number. Returns True for success, False for failure. IMAP Download All Email as MIME One at a Time
# msgId is an integer (input)
# bUid is a boolean (input)
# Returns a CkEmail object
FetchSingleHeader( msgId, bUid )
Retrieves a single message header from the IMAP server. If the method fails, it may return a NULL reference. The following methods are useful for retrieving information about attachments and flags after an email header is retrieved: GetMailNumAttach, GetMailAttachSize, GetMailAttachFilename, GetMailFlag.
If bUid is true, then msgID represents a UID. If bUid is false, then msgID represents a sequence number. Returns a null reference on failure
# msgId is an integer (input)
# bUID is a boolean (input)
# outStr is a CkString object (output)
# Returns a boolean value
FetchSingleHeaderAsMime( msgId, bUID, outStr )
Fetches and returns the MIME of a single email header. Returns True for success, False for failure.
# Returns a CkMessageSet object
GetAllUids( )
Returns a message set object containing all the UIDs in the currently selected mailbox. A NULL object reference is returned on failure. Returns a null reference on failure
# email is a CkEmail object (input)
# attachIndex is an integer (input)
# strFilename is a CkString object (output)
# Returns a boolean value
GetMailAttachFilename( email, attachIndex, strFilename )
Returns the Nth attachment filename. Indexing begins at 0. Returns True for success, False for failure.
# email is a CkEmail object (input)
# attachIndex is an integer (input)
# Returns an integer value
GetMailAttachSize( email, attachIndex )
Returns the Nth attachment size in bytes. Indexing begins at 0.
# email is a CkEmail object (input)
# flagName is a string (input)
# Returns an integer value
GetMailFlag( email, flagName )
Returns the value of a flag (True = yes, False = no) for an email.
Valid flag names are "Seen", "Answered", "Draft", "Flagged", and "Deleted".
# email is a CkEmail object (input)
# Returns an integer value
GetMailNumAttach( email )
Returns the number of email attachments.
# email is a CkEmail object (input)
# Returns an integer value
GetMailSize( email )
Returns the size (in bytes) of the entire email including attachments.
# Returns a CkCert object
GetSslServerCert( )
Returns the IMAP server's digital certificate (for SSL / TLS connections).
# Returns a boolean value
IsConnected( )
Returns the last known "connected" state with the IMAP server. IsConnected does not send a message to the IMAP server to determine if it is still connected. The Noop method may be called to specifically send a no-operation message to determine actual connectivity.
The IsConnected method is useful for checking to see if the component is already in a known disconnected state.
# Returns a boolean value
IsLoggedIn( )
Returns True if already logged into an IMAP server, otherwise returns False.
# Returns a boolean value
IsUnlocked( )
Returns True if the component is unlocked, False if not.
# reference is a string (input)
# wildcardedMailbox is a string (input)
# Returns a CkMailboxes object
ListMailboxes( reference, wildcardedMailbox )
Returns a subset of the complete list of mailboxes available on the IMAP server. The reference and wildcardedMailbox parameters are passed unaltered to the IMAP LIST command:
FROM RFC 3501 (IMAP Protocol)
The LIST command returns a subset of names from the complete set
of all names available to the client. Zero or more untagged LIST
replies are returned, containing the name attributes, hierarchy
delimiter, and name; see the description of the LIST reply for
more detail.
An empty ("" string) reference name argument indicates that the
mailbox name is interpreted as by SELECT. The returned mailbox
names MUST match the supplied mailbox name pattern. A non-empty
reference name argument is the name of a mailbox or a level of
mailbox hierarchy, and indicates the context in which the mailbox
name is interpreted.
An empty ("" string) mailbox name argument is a special request to
return the hierarchy delimiter and the root name of the name given
in the reference. The value returned as the root MAY be the empty
string if the reference is non-rooted or is an empty string. In
all cases, a hierarchy delimiter (or NIL if there is no hierarchy)
is returned. This permits a client to get the hierarchy delimiter
(or find out that the mailbox names are flat) even when no
mailboxes by that name currently exist.
The reference and mailbox name arguments are interpreted into a
canonical form that represents an unambiguous left-to-right
hierarchy. The returned mailbox names will be in the interpreted
form.
Note: The interpretation of the reference argument is
implementation-defined. It depends upon whether the
server implementation has a concept of the "current
working directory" and leading "break out characters",
which override the current working directory.
For example, on a server which exports a UNIX or NT
filesystem, the reference argument contains the current
working directory, and the mailbox name argument would
contain the name as interpreted in the current working
directory.
If a server implementation has no concept of break out
characters, the canonical form is normally the reference
name appended with the mailbox name. Note that if the
server implements the namespace convention (section
5.1.2), "#" is a break out character and must be treated
as such.
If the reference argument is not a level of mailbox
hierarchy (that is, it is a \NoInferiors name), and/or
the reference argument does not end with the hierarchy
delimiter, it is implementation-dependent how this is
interpreted. For example, a reference of "foo/bar" and
mailbox name of "rag/baz" could be interpreted as
"foo/bar/rag/baz", "foo/barrag/baz", or "foo/rag/baz".
A client SHOULD NOT use such a reference argument except
at the explicit request of the user. A hierarchical
browser MUST NOT make any assumptions about server
interpretation of the reference unless the reference is
a level of mailbox hierarchy AND ends with the hierarchy
delimiter.
Any part of the reference argument that is included in the
interpreted form SHOULD prefix the interpreted form. It SHOULD
also be in the same form as the reference name argument. This
rule permits the client to determine if the returned mailbox name
is in the context of the reference argument, or if something about
the mailbox argument overrode the reference argument. Without
this rule, the client would have to have knowledge of the server's
naming semantics including what characters are "breakouts" that
override a naming context.
For example, here are some examples of how references
and mailbox names might be interpreted on a UNIX-based
server:
Reference Mailbox Name Interpretation
------------ ------------ --------------
~smith/Mail/ foo.* ~smith/Mail/foo.*
archive/ % archive/%
#news. comp.mail.* #news.comp.mail.*
~smith/Mail/ /usr/doc/foo /usr/doc/foo
archive/ ~fred/Mail/* ~fred/Mail/*
The first three examples demonstrate interpretations in
the context of the reference argument. Note that
"~smith/Mail" SHOULD NOT be transformed into something
like "/u2/users/smith/Mail", or it would be impossible
for the client to determine that the interpretation was
in the context of the reference.
The character "*" is a wildcard, and matches zero or more
characters at this position. The character "%" is similar to "*",
but it does not match a hierarchy delimiter. If the "%" wildcard
is the last character of a mailbox name argument, matching levels
of hierarchy are also returned. If these levels of hierarchy are
not also selectable mailboxes, they are returned with the
\Noselect mailbox name attribute (see the description of the LIST
response for more details).
Server implementations are permitted to "hide" otherwise
accessible mailboxes from the wildcard characters, by preventing
certain characters or names from matching a wildcard in certain
situations. For example, a UNIX-based server might restrict the
interpretation of "*" so that an initial "/" character does not
match.
The special name INBOX is included in the output from LIST, if
INBOX is supported by this server for this user and if the
uppercase string "INBOX" matches the interpreted reference and
mailbox name arguments with wildcards as described above. The
criteria for omitting INBOX is whether SELECT INBOX will return
failure; it is not relevant whether the user's real INBOX resides
on this or some other server.
Returns a null reference on failure
# login is a string (input)
# password is a string (input)
# Returns a boolean value
Login( login, password )
Logs into the IMAP server. The component must first be connected to an IMAP server by calling Connect. Non-standard Yahoo! IMAP Server Requirements
# Returns a boolean value
Logout( )
Logs out of the IMAP server.
# Returns a boolean value
Noop( )
Sends a NOOP command to the IMAP server and receives the response. The component must be connected and authenticated for this to succeed. Sending a NOOP is a good way of determining whether the connection to the IMAP server is up and active. Returns True for success, False for failure.
# emailInOut is a CkEmail object (output)
# Returns a boolean value
RefetchMailFlags( emailInOut )
Fetches the flags for an email and updates the flags in the email's header. When an email is retrieved from the IMAP server, it embeds the flags into the header in fields beginning with "ckx-". Methods such as GetMailFlag and GetWebMailFlag read these header fields.
# fromMailbox is a string (input)
# toMailbox is a string (input)
# Returns a boolean value
RenameMailbox( fromMailbox, toMailbox )
Renames a mailbox.
# filename is a string (input)
# Returns a boolean value
SaveLastError( filename )
Saves the last error information to an XML formatted file.
# criteria is a string (input)
# bUid is a boolean (input)
# Returns a CkMessageSet object
Search( criteria, bUid )
Searches the selected mailbox for messages that meet a given criteria and returns a message set of all matching messages. If bUid is true, then UIDs are returned in the message set, otherwise sequence numbers are returned.
The criteria is passed through to the low-level IMAP protocol unmodified, so the rules for the IMAP SEARCH command (RFC 3501) apply and are reproduced here:
FROM RFC 3501 (IMAP Protocol)
The SEARCH command searches the mailbox for messages that match
the given searching criteria. Searching criteria consist of one
or more search keys. The untagged SEARCH response from the server
contains a listing of message sequence numbers corresponding to
those messages that match the searching criteria.
When multiple keys are specified, the result is the intersection
(AND function) of all the messages that match those keys. For
example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers
to all deleted messages from Smith that were placed in the mailbox
since February 1, 1994. A search key can also be a parenthesized
list of one or more search keys (e.g., for use with the OR and NOT
keys).
Server implementations MAY exclude [MIME-IMB] body parts with
terminal content media types other than TEXT and MESSAGE from
consideration in SEARCH matching.
The OPTIONAL [CHARSET] specification consists of the word
"CHARSET" followed by a registered [CHARSET]. It indicates the
[CHARSET] of the strings that appear in the search criteria.
[MIME-IMB] content transfer encodings, and [MIME-HDRS] strings in
[RFC-2822]/[MIME-IMB] headers, MUST be decoded before comparing
text in a [CHARSET] other than US-ASCII. US-ASCII MUST be
supported; other [CHARSET]s MAY be supported.
If the server does not support the specified [CHARSET], it MUST
return a tagged NO response (not a BAD). This response SHOULD
contain the BADCHARSET response code, which MAY list the
[CHARSET]s supported by the server.
In all search keys that use strings, a message matches the key if
the string is a substring of the field. The matching is
case-insensitive.
The defined search keys are as follows. Refer to the Formal
Syntax section for the precise syntactic definitions of the
arguments.
Messages with message sequence numbers corresponding to the
specified message sequence number set.
ALL
All messages in the mailbox; the default initial key for
ANDing.
ANSWERED
Messages with the \Answered flag set.
BCC
Messages that contain the specified string in the envelope
structure's BCC field.
BEFORE
Messages whose internal date (disregarding time and timezone)
is earlier than the specified date.
BODY
Messages that contain the specified string in the body of the
message.
CC
Messages that contain the specified string in the envelope
structure's CC field.
DELETED
Messages with the \Deleted flag set.
DRAFT
Messages with the \Draft flag set.
FLAGGED
Messages with the \Flagged flag set.
FROM
Messages that contain the specified string in the envelope
structure's FROM field.
HEADER
Messages that have a header with the specified field-name (as
defined in [RFC-2822]) and that contains the specified string
in the text of the header (what comes after the colon). If the
string to search is zero-length, this matches all messages that
have a header line with the specified field-name regardless of
the contents.
KEYWORD
Messages with the specified keyword flag set.
LARGER
Messages with an [RFC-2822] size larger than the specified
number of octets.
NEW
Messages that have the \Recent flag set but not the \Seen flag.
This is functionally equivalent to "(RECENT UNSEEN)".
NOT
Messages that do not match the specified search key.
OLD
Messages that do not have the \Recent flag set. This is
functionally equivalent to "NOT RECENT" (as opposed to "NOT
NEW").
ON
Messages whose internal date (disregarding time and timezone)
is within the specified date.
OR
Messages that match either search key.
RECENT
Messages that have the \Recent flag set.
SEEN
Messages that have the \Seen flag set.
SENTBEFORE
Messages whose [RFC-2822] Date: header (disregarding time and
timezone) is earlier than the specified date.
SENTON
Messages whose [RFC-2822] Date: header (disregarding time and
timezone) is within the specified date.
SENTSINCE
Messages whose [RFC-2822] Date: header (disregarding time and
timezone) is within or later than the specified date.
SINCE
Messages whose internal date (disregarding time and timezone)
is within or later than the specified date.
SMALLER
Messages with an [RFC-2822] size smaller than the specified
number of octets.
SUBJECT
Messages that contain the specified string in the envelope
structure's SUBJECT field.
TEXT
Messages that contain the specified string in the header or
body of the message.
TO
Messages that contain the specified string in the envelope
structure's TO field.
UID
Messages with unique identifiers corresponding to the specified
unique identifier set. Sequence set ranges are permitted.
UNANSWERED
Messages that do not have the \Answered flag set.
UNDELETED
Messages that do not have the \Deleted flag set.
UNDRAFT
Messages that do not have the \Draft flag set.
UNFLAGGED
Messages that do not have the \Flagged flag set.
UNKEYWORD
Messages that do not have the specified keyword flag set.
UNSEEN
Messages that do not have the \Seen flag set.
Returns a null reference on failure
# mailbox is a string (input)
# Returns a boolean value
SelectMailbox( mailbox )
Selects a mailbox. A mailbox must be selected before some methods, such as Search or FetchSingle, can be called. If the logged-on user does not have write-access to the mailbox, call ExamineMailbox instead. Returns True for success, False for failure. Selecting Public Folders
# rawCommand is a string (input)
# rawResponse is a CkString object (output)
# Returns a boolean value
SendRawCommand( rawCommand, rawResponse )
Allows for the sending of arbitrary commands to the IMAP server. Returns True for success, False for failure.
# Returns a boolean value
SetCSP( csp )
(Only applies to the Microsoft Windows OS) Sets the Cryptographic Service Provider (CSP) to be used for encryption or digital signing, or decryption / signature verification.
This is not commonly used becaues the default Microsoft CSP is typically appropriate.
One instance where SetCSP is necessary is when using the Crypto-Pro CSP for the GOST R 34.10-2001 and GOST R 34.10-94 providers. Returns True for success, False for failure.
# Returns a boolean value
SetDecryptCert2( cert, key )
Used to explicitly specify the certificate and associated private key to be used for decrypting S/MIME (PKCS7) email.
# msgId is an integer (input)
# bUid is a boolean (input)
# flagName is a string (input)
# value is an integer (input)
# Returns a boolean value
SetFlag( msgId, bUid, flagName, value )
Sets a flag for a single message on the IMAP server. If value = 1, the flag is turned on, if value = 0, the flag is turned off. Valid flag names are "Seen", "Answered", "Draft", "Flagged", and "Deleted".
If bUid is True, then msgId represents a UID. If bUid is False, then msgId represents a sequence number. Returns True for success, False for failure.
# messageSet is a CkMessageSet object (input)
# flagName is a string (input)
# value is an integer (input)
# Returns a boolean value
SetFlags( messageSet, flagName, value )
Sets a flag for each message in the message set on the IMAP server. If value = 1, the flag is turned on, if value = 0, the flag is turned off. Valid flag names are "Seen", "Answered", "Draft", "Flagged", and "Deleted". Returns True for success, False for failure.
# email is a CkEmail object (input)
# flagName is a string (input)
# value is an integer (input)
# Returns a boolean value
SetMailFlag( email, flagName, value )
Sets a flag for a single message on the IMAP server. The UID of the email object is used to find the message on the IMAP server that is to be affected. If value = 1, the flag is turned on, if value = 0, the flag is turned off.
Valid flag names are "Seen", "Answered", "Draft", "Flagged", and "Deleted".
Note: When the Chilkat IMAP component downloads an email from an IMAP server, it inserts a "ckx-imap-uid" header field in the email object. This is subsequently used by this method to get the UID associated with the email. The "ckx-imap-uid" header must be present for this method to be successful. Returns True for success, False for failure.
# Returns a boolean value
SetSslClientCert( cert )
Specifies a client-side certificate to be used for the SSL / TLS connection. In most cases, servers do not require client-side certificates for SSL/TLS. A client-side certificate is typically used in high-security situations where the certificate is an additional means to indentify the client to the server. Returns True for success, False for failure.
# pemDataOrFilename is a string (input)
# pemPassword is a string (input)
# Returns a boolean value
SetSslClientCertPem( pemDataOrFilename, pemPassword )
(Same as SetSslClientCert, but allows a .pfx/.p12 file to be used directly) Specifies a client-side certificate to be used for the SSL / TLS connection. In most cases, servers do not require client-side certificates for SSL/TLS. A client-side certificate is typically used in high-security situations where the certificate is an additional means to indentify the client to the server.
The pemDataOrFilename may contain the actual PEM data, or it may contain the path of the PEM file. This method will automatically recognize whether it is a path or the PEM data itself. Returns True for success, False for failure.
# pfxFilename is a string (input)
# pfxPassword is a string (input)
# certSubjectCN is a string (input)
# Returns a boolean value
SetSslClientCertPfx( pfxFilename, pfxPassword, certSubjectCN )
(Same as SetSslClientCert, but allows a .pfx/.p12 file to be used directly) Specifies a client-side certificate to be used for the SSL / TLS connection. In most cases, servers do not require client-side certificates for SSL/TLS. A client-side certificate is typically used in high-security situations where the certificate is an additional means to indentify the client to the server. Returns True for success, False for failure.
# sshLogin is a string (input)
# Returns a boolean value
SshAuthenticatePk( sshLogin, privateKey )
Authenticates with the SSH server using public-key authentication. The corresponding public key must have been installed on the SSH server for the sshLogin. Authentication will succeed if the matching privateKey is provided.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns True for success, False for failure.
# sshLogin is a string (input)
# sshPassword is a string (input)
# Returns a boolean value
SshAuthenticatePw( sshLogin, sshPassword )
Authenticates with the SSH server using a sshLogin and sshPassword.
An SSH tunneling (port forwarding) session always begins by first calling SshTunnel to connect to the SSH server, then calling either AuthenticatePw or AuthenticatePk to authenticate. Following this, your program should call Connect to connect with the IMAP server (via the SSH tunnel) and then Login to authenticate with the IMAP server.
Note: Once the SSH tunnel is setup by calling SshTunnel and SshAuthenticatePw (or SshAuthenticatePk), all underlying communcations with the IMAP server use the SSH tunnel. No changes in programming are required other than making two initial calls to setup the tunnel.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns True for success, False for failure. IMAP SSH Tunneling (Port Forwarding)
# sshServerHostname is a string (input)
# sshPort is an integer (input)
# Returns a boolean value
SshTunnel( sshServerHostname, sshPort )
Connects to an SSH server and creates a tunnel for IMAP. The sshServerHostname is the hostname (or IP address) of the SSH server. The sshPort is typically 22, which is the standard SSH port number.
An SSH tunneling (port forwarding) session always begins by first calling SshTunnel to connect to the SSH server, followed by calling either AuthenticatePw or AuthenticatePk to authenticate. Your program would then call Connect to connect with the IMAP server (via the SSH tunnel) and then Login to authenticate with the IMAP server.
Note: Once the SSH tunnel is setup by calling SshTunnel and SshAuthenticatePw (or SshAuthenticatePk), all underlying communcations with the IMAP server use the SSH tunnel. No changes in programming are required other than making two initial calls to setup the tunnel.
Important: When reporting problems, please send the full contents of the LastErrorText property to support@chilkatsoft.com. Returns True for success, False for failure. IMAP SSH Tunneling (Port Forwarding)
# msgId is an integer (input)
# bUid is a boolean (input)
# flagNames is a string (input)
# value is an integer (input)
# Returns a boolean value
StoreFlags( msgId, bUid, flagNames, value )
Sets one or more flags to a specific value for an email. The email is indicated by either a UID or sequence number, depending on whether bUid is True (UID) or False (sequence number).
flagNames should be a space separated string of flag names, where each flag name begins with a backslash character. For example: "\Seen \Answered". Possible flag names are \Seen, \Answered, \Flagged, \Deleted, and \Draft.
Note: The other methods, such as SetFlag, SetFlags, and SetMailFlag, require flag names without the leading backslash.
value should be 1 to turn the flags on, or 0 to turn the flags off. Returns True for success, False for failure.
# mailbox is a string (input)
# Returns a boolean value
Subscribe( mailbox )
Subscribe to an IMAP mailbox. Returns True for success, False for failure.
# unlockCode is a string (input)
# Returns a boolean value
UnlockComponent( unlockCode )
Unlocks the component. This must be called once at the beginning of your program to unlock the component. A permanent unlock code is provided when the IMAP component is licensed. Any string, such as "Hello World", may be passed to this method to automatically begin a fully-functional 30-day trial.
A valid permanent unlock code for this object will always included the substring "IMAP".
Note: A permanent unlock code for IMAP will also always include the substring "MAIL", and therefore it may be used for the MailMan (or CkMailMan) object/class. The IMAP license includes POP3/SMTP functionality, and therefore the MailMan object/class may be unlocked using the same unlock code. Returns True for success, False for failure. Diagnosing UnlockComponent Problems UnlockComponent LastErrorText shows exact string passed to it. Verify UnlockComponent Success w/ Permanent Unlock Code LastErrorText Standard Information How UnlockComponent Works
# mailbox is a string (input)
# Returns a boolean value
Unsubscribe( mailbox )
Unsubscribe from an IMAP mailbox. Returns True for success, False for failure.
# Returns a string
authMethod( )
Can be set to "CRAM-MD5", "NTLM", "PLAIN", or "LOGIN" to select the authentication method. NTLM is the most secure, and is a synonym for "Windows Integrated Authentication". The default is "LOGIN" (or the empty string) which is simple plain-text username/password authentication. Not all IMAP servers support all authentication methods. Returns a null on failure
# Returns a string
authzId( )
Applies to the PLAIN authentication method. May be set to an authorization ID that is to be sent along with the Login and Password for authentication. Returns a null on failure
# Returns a string
clientIpAddress( )
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124". Returns a null on failure Important Bind to Adapter Notes for Windows
# Returns a string
connectedToHost( )
Contains the IMAP server's domain name (or IP address) if currently connected. Otherwise returns an empty string. Returns a null on failure
# Returns a string
debugLogFilePath( )
Used for debugging in cases where a Chilkat method call hangs and never returns. This should generally never happen. The only causes for this are (1) a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired, (2) the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or (3) there is an internal problem (bug) in the Chilkat code that causes the hang.
This property allows one to specifiy a debug file path that will be created (or appended if it already exists) and information will be logged to it as the Chilkat methods are called. If a hang occurs, the log file may be viewed to get information about what happened. Returns a null on failure
# Returns a string
domain( )
The Windows Domain to use for Windows Integrated Authentication (also known as NTLM). This may be empty. Returns a null on failure
# msgId is an integer (input)
# bUid is a boolean (input)
# Returns a string
fetchFlags( msgId, bUid )
Fetches the flags for an email. The bUid argument determines whether the msgId argument is a UID or sequence number. Returns a null on failure
# msgId is an integer (input)
# bUid is a boolean (input)
# Returns a string
fetchSingleAsMime( msgId, bUid )
Retrieves a single message from the IMAP server and returns a string containing the complete MIME source of the email. If the method fails, it returns a NULL reference. If bUid is true, then msgID represents a UID. If bUid is false, then msgID represents a sequence number. Returns a null on failure IMAP Download All Email as MIME One at a Time
# msgId is an integer (input)
# bUID is a boolean (input)
# Returns a string
fetchSingleHeaderAsMime( msgId, bUID )
Fetches and returns the MIME of a single email header. Returns a null on failure
# email is a CkEmail object (input)
# attachIndex is an integer (input)
# Returns a string
getMailAttachFilename( email, attachIndex )
Returns the Nth attachment filename. Indexing begins at 0. Returns a null on failure
# Returns a string
httpProxyAuthMethod( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "LOGIN" or "NTLM". Returns a null on failure
# Returns a string
httpProxyHostname( )
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation). Returns a null on failure
# Returns a string
httpProxyPassword( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password. Returns a null on failure
# Returns a string
httpProxyUsername( )
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name. Returns a null on failure
# Returns a string
lastAppendedMime( )
The MIME source of the email last appended during a call to AppendMail, or AppendMime. Returns a null on failure
# Returns a string
lastCommand( )
The last raw command sent to the IMAP server. (This information can be used for debugging if problems occur.) Returns a null on failure
# Returns a string
lastErrorHtml( )
Error information in HTML format for the last method called.Returns a null on failure
# Returns a string
lastErrorText( )
Error information in plain-text format for the last method called.Returns a null on failure
# Returns a string
lastErrorXml( )
Error information in XML format for the last method called.Returns a null on failure
# Returns a string
lastIntermediateResponse( )
The last intermediate response received from the IMAP server. (This information can be used for debugging if problems occur.) Returns a null on failure
# Returns a string
lastResponse( )
The raw data of the last response from the IMAP server. (Useful for debugging.) Returns a null on failure
# Returns a string
loggedInUser( )
If logged into an IMAP server, the logged-in username. Returns a null on failure
# Returns a string
selectedMailbox( )
The currently selected mailbox, or an empty string if none. Returns a null on failure
# rawCommand is a string (input)
# Returns a string
sendRawCommand( rawCommand )
Allows for the sending of arbitrary commands to the IMAP server. Returns a null on failure
# Returns a string
sessionLog( )
Contains an in-memory log of the raw commands sent to the IMAP server, and the raw responses received from the IMAP server. The KeepSessionLog property must be set to True to enable session logging. Call ClearSessionLog to reset the log. Returns a null on failure
# Returns a string
socksHostname( )
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5). Returns a null on failure
# Returns a string
socksPassword( )
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4. Returns a null on failure
# Returns a string
socksUsername( )
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5). Returns a null on failure
# Returns a string
sslProtocol( )
Selects the secure protocol to be used for secure (SSL/TLS) implicit and explicit (StartTls) connections . Possible values are:
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "TLS 1.0".Returns a null on failure
# Returns a string
version( )
The version of the component, such as "1.0.0". Returns a null on failure
|