http://www.zorba-xquery.com/modules/email/imap

View as XML or JSON.

This module provides functions for accessing and manipulating emails on mail servers through the IMAP protocol. All functions in this module receive as the first argument the IMAP host and user information. This is an element with the type hostInfoType as defined in the email schema: http://www.zorba-xquery.com/modules/email. For example:

 <email:hostInfo>
   <email:hostName>imap.example.com</email:hostName>
   <email:userName>myuser</email:userName>
   <email:password>mypassword</email:password>
 </email:hostInfo>

The hostInfoType only needs to be in the email schema namespace (http://www.zorba-xquery.com/modules/email). It does not need to be validated since it's validated by the module.

Function Summary


                                        
                                        copy
                                        ($host-info as element(email:hostInfo), $mailbox-from as xs:string, $mailbox-to as xs:string, $messages as xs:long+, $uid as xs:boolean?) as empty-sequence()

Copies messages between mailboxes.


                                        
                                        create
                                        ($host-info as element(email:hostInfo), $mailbox-name as xs:string) as empty-sequence()

Creates a new mailbox for the given user.


                                        
                                        delete
                                        ($host-info as element(email:hostInfo), $mailbox-name as xs:string) as empty-sequence()

Deletes a mailbox for the given user.


                                        
                                        expunge
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string) as empty-sequence()

Permanently deletes all messages of the given mailbox that have the "deleted" flag set.


                                        
                                        fetch-envelope
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $uid as xs:boolean?) as element(email:envelope)

Fetches the envelope of a message.


                                        
                                        fetch-flags
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $uid as xs:boolean?) as element(email:flags)

Fetches the flags of a message.


                                        
                                        fetch-from
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:string

Fetches the 'from' string of a message.


                                        
                                        fetch-message-sequence-number
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:long

Fetches the message sequence number for a given unique identifier.


                                        
                                        fetch-message
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $uid as xs:boolean) as element(email:message)

Fetches a whole message.


                                        
                                        fetch-subject
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:string

Fetches the subject for a message.


                                        
                                        fetch-uid
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:long

Fetches the unique identifier for a given message sequence number.


                                        
                                        list
                                        ($host-info as element(email:hostInfo), $mailbox-ref as xs:string, $pattern as xs:string, $only-subscribed as xs:boolean) as element(email:mailbox)*

Lists IMAP folders for the specified user on the host that match the pattern.


                                        
                                        move
                                        ($host-info as element(email:hostInfo), $mailbox-from as xs:string, $mailbox-to as xs:string, $messages as xs:long+, $uid as xs:boolean?) as empty-sequence()

Moves messages between mailboxes.


                                        
                                        rename
                                        ($host-info as element(email:hostInfo), $mailbox-old as xs:string, $mailbox-new as xs:string) as empty-sequence()

Renames a mailbox.


                                        
                                        search
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $criteria as xs:string, $uid as xs:boolean?) as xs:long*

Searches a mailbox for messages that match the given criteria.


                                        
                                        set-flags
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $flags as element(email:flags), $uid as xs:boolean?) as empty-sequence()

Sets the flags for a given message.


                                        
                                        status
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string) as element(email:status)

Returns the status of the given mailbox.


                                        
                                        subscribe
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string) as empty-sequence()

Subscribes the user to the specified mailbox.


                                        
                                        unsubscribe
                                        ($host-info as element(email:hostInfo), $mailbox as xs:string) as empty-sequence()

Unsubscribes the user from the specified mailbox.

Functions

copy#5

declare  %an:sequential function imap:copy($host-info as element(email:hostInfo), $mailbox-from as xs:string, $mailbox-to as xs:string, $messages as xs:long+, $uid as xs:boolean?) as empty-sequence()

Copies messages between mailboxes. Depending on the value of $uid, the messages are either specified through their sequence number or through their unique id. Both mailboxes must exist.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox-from as xs:string: The mailbox in which the messages reside.

mailbox-to as xs:string: The mailbox in to which the messages are copied.

messages as xs:long: The messages to be copied, specified either by their sequence number or their unique id.

uid as xs:boolean: If true, $messages are treated as sequence numbers. Else as unique identifiers.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

create#2

declare  %an:sequential function imap:create($host-info as element(email:hostInfo), $mailbox-name as xs:string) as empty-sequence()

Creates a new mailbox for the given user.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox-name as xs:string: The name for the new mailbox.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

delete#2

declare  %an:sequential function imap:delete($host-info as element(email:hostInfo), $mailbox-name as xs:string) as empty-sequence()

Deletes a mailbox for the given user.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox-name as xs:string: The name of the mailbox to delete.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

expunge#2

declare  %an:sequential function imap:expunge($host-info as element(email:hostInfo), $mailbox as xs:string) as empty-sequence()

Permanently deletes all messages of the given mailbox that have the "deleted" flag set.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox for which all messages that have the \Deleted flag set should be permanently deleted.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

fetch-envelope#4

declare  %an:nondeterministic function imap:fetch-envelope($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $uid as xs:boolean?) as element(email:envelope)

Fetches the envelope of a message.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox in which to search for the message.

message-number as xs:long: The message for which to fetch the envelope (depending on $uid either as message sequence number or unique identifier).

uid as xs:boolean: If true, $message-number is treated as sequence number. Else as unique identifier.

Returns

element(email:envelope): The envelope of the requested message. The result is validated against the schema: http://www.zorba-xquery.com/modules/email.

fetch-flags#4

declare  %an:nondeterministic function imap:fetch-flags($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $uid as xs:boolean?) as element(email:flags)

Fetches the flags of a message.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox containing the specified message.

message-number as xs:long: Either the message sequence number or the unique identifier of the message.

uid as xs:boolean: If true, $message-number is treated as sequence number. Else as unique identifier.

Returns

element(email:flags): The flags of the specified message. The result is validated against the schema: http://www.zorba-xquery.com/modules/email.

fetch-from#3

declare  %an:nondeterministic function imap:fetch-from($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:string

Fetches the 'from' string of a message. Please note that this function only words with message sequence numbers, not with unique identifiers. Only the first 255 characters of a 'from' string are fetched.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox for which we want to get the 'from' string of a message.

message-number as xs:long: Denotes the message for which we want the 'from' string.

Returns

xs:string: The 'from' string of the specified message.

fetch-message-sequence-number#3

declare  %an:nondeterministic function imap:fetch-message-sequence-number($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:long

Fetches the message sequence number for a given unique identifier.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox for which we want to get the message sequence number of an unique identifier.

message-number as xs:long: The unique identifier for which we want the message sequence number.

Returns

xs:long: The message sequence number of the of the given unique identifier.

fetch-message#4

declare  %an:nondeterministic function imap:fetch-message($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $uid as xs:boolean) as element(email:message)

Fetches a whole message.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox in which to search for the message.

message-number as xs:long: The message to fetch, denoted either by its sequence number or unique identifier.

uid as xs:boolean: If true, $message-number is treated as sequence number. Else as unique identifier.

Returns

element(email:message): the message with the given $message-number. The result is validated against the schema: http://www.zorba-xquery.com/modules/email.

fetch-subject#3

declare  %an:nondeterministic function imap:fetch-subject($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:string

Fetches the subject for a message. Please note that this function only works with message sequence numbers, not with unique identifiers. Only the first 255 characters of a subject are fetched.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox for which we want to get the subject of a message.

message-number as xs:long: Denotes the message for which we want the subject.

Returns

xs:string: The subject of the specified message.

fetch-uid#3

declare  %an:nondeterministic function imap:fetch-uid($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long) as xs:long

Fetches the unique identifier for a given message sequence number.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox for which we want to get the unique identifier of a message sequence number.

message-number as xs:long: The message sequence number for which we want the unique identifier.

Returns

xs:long: The unique identifier of the given message sequence number.

list#4

declare  %an:nondeterministic function imap:list($host-info as element(email:hostInfo), $mailbox-ref as xs:string, $pattern as xs:string, $only-subscribed as xs:boolean) as element(email:mailbox)*

Lists IMAP folders for the specified user on the host that match the pattern.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox-ref as xs:string: is applied to pattern in an implementation dependent fashion to search for matching mailbox names.

pattern as xs:string: The pattern for mailboxes to look for (can include wildcards '*' and '%').

only-subscribed as xs:boolean: If set true, only mailboxes are listed to which the user is subscribed.

Returns

element(email:mailbox)*: A sequence of mailbox elements. The result elements are validated against the schema: http://www.zorba-xquery.com/modules/email.

move#5

declare  %an:sequential function imap:move($host-info as element(email:hostInfo), $mailbox-from as xs:string, $mailbox-to as xs:string, $messages as xs:long+, $uid as xs:boolean?) as empty-sequence()

Moves messages between mailboxes. Depending on the value of $uid, the messages are either specified through their sequence number or through their unique id. Both mailboxes must exist.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox-from as xs:string: The mailbox in which the messages reside.

mailbox-to as xs:string: The mailbox in to which the messages should be moved.

messages as xs:long: The messages to be copied, specified either by their sequence number or their unique id.

uid as xs:boolean: If true, $messages are treated as sequence numbers. Else as unique identifiers.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

rename#3

declare  %an:sequential function imap:rename($host-info as element(email:hostInfo), $mailbox-old as xs:string, $mailbox-new as xs:string) as empty-sequence()

Renames a mailbox.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox-old as xs:string: The name of the mailbox we want to rename.

mailbox-new as xs:string: The new name for the mailbox.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

search#4

declare  %an:nondeterministic function imap:search($host-info as element(email:hostInfo), $mailbox as xs:string, $criteria as xs:string, $uid as xs:boolean?) as xs:long*

Searches a mailbox for messages that match the given criteria. The criteria should be a string as defined in the RFC3501 (IMAP4rev1). A valid example would be: 'FROM zorba@gmail.com OR NOT SUBJECT Bug'. Depending on the value of $uid, the function will either return matching sequence numbers or unique identifiers.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox to search.

criteria as xs:string: The searching criteria.

uid as xs:boolean: If true, the function returns the sequence of unique identifiers corresponding to the matching mails, else the corresponding sequence numbers are returned.

Returns

xs:long*: Either the sequence of matching sequence numbers or the sequence of matching unique identifiers.

set-flags#5

declare  %an:sequential function imap:set-flags($host-info as element(email:hostInfo), $mailbox as xs:string, $message-number as xs:long, $flags as element(email:flags), $uid as xs:boolean?) as empty-sequence()

Sets the flags for a given message. The flags are set and unset according to the passed $flags.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox containing the specified message.

message-number as xs:long: Either the message sequence number or the unique identifier of the message (depending on the value of $uid).

flags as element(email:flags): Defines which flags should be set for this message. The possibilities are "seen", "deleted", "flagged", "answered", and "draft". Setting all flags at once is done by passing the element: <email:flags> <email:seen/> <email:deleted/> <email:flagged/> <email:answered/> <email:draft/> </email:flags> . Setting "flagged" only and unsetting all other at once can be done by passing: <email:flags> <email:flagged/> </email:flags> .

uid as xs:boolean: If true, $message-number is treated as sequence number. Else as unique identifier.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

status#2

declare  %an:nondeterministic function imap:status($host-info as element(email:hostInfo), $mailbox as xs:string) as element(email:status)

Returns the status of the given mailbox. The status of a mailbox contains:

messages: the number of messages in the mailbox
recent: the number of messages flagged as recent
unseen: the number of messages flagged as unseen
uidnext: the next unique identifier that will be assigned to a message
uidvalidity: a value that, together with the uidnext value forms a 64 bit number that must be unique for the server

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox for which we want to have the status.

Returns

element(email:status): The status of the specified $mailbox. The result is validated against the schema: http://www.zorba-xquery.com/modules/email.

subscribe#2

declare  %an:sequential function imap:subscribe($host-info as element(email:hostInfo), $mailbox as xs:string) as empty-sequence()

Subscribes the user to the specified mailbox.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox the user wants to subscribe to.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

unsubscribe#2

declare  %an:sequential function imap:unsubscribe($host-info as element(email:hostInfo), $mailbox as xs:string) as empty-sequence()

Unsubscribes the user from the specified mailbox.

Parameters

host-info as element(email:hostInfo): The IMAP host, user name, and password.

mailbox as xs:string: The mailbox the user wants to unsubscribe from.

Returns

empty-sequence(): The function is declared as sequential and has side-effects. It returns the empty sequence.

http://www.zorba-xquery.com/modules/email/imap

Function Summary

Variable Summary

Functions

copy#5

Parameters

Returns

create#2

Parameters

Returns

delete#2

Parameters

Returns

expunge#2

Parameters

Returns

fetch-envelope#4

Parameters

Returns

fetch-flags#4

Parameters

Returns

fetch-from#3

Parameters

Returns

fetch-message-sequence-number#3

Parameters

Returns

fetch-message#4

Parameters

Returns

fetch-subject#3

Parameters

Returns

fetch-uid#3

Parameters

Returns

list#4

Parameters

Returns

move#5

Parameters

Returns

rename#3

Parameters

Returns

search#4

Parameters

Returns

set-flags#5

Parameters

Returns

status#2

Parameters

Returns

subscribe#2

Parameters

Returns

unsubscribe#2

Parameters

Returns

Variables