## Apache Zeta Components Manual :: Docs For Class ezcMailImapTransport

### Mail::ezcMailImapTransport

### Class ezcMailImapTransport

The class ezcMailImapTransport implements functionality for handling IMAP mail servers.

The implementation supports most of the commands specified in:

- http://www.faqs.org/rfcs/rfc1730.html (IMAP4)
- http://www.faqs.org/rfcs/rfc2060.html (IMAP4rev1)

Each user account on the IMAP server has it's own folders (mailboxes). Mailboxes can be created, renamed or deleted. All accounts have a special mailbox called Inbox which cannot be deleted or renamed.

Messages are organized in mailboxes, and are identified by a message number (which can change over time) and a unique ID (which does not change under normal circumstances). The commands operating on messages can handle both modes (message numbers or unique IDs).

Messages are marked by certain flags (SEEN, DRAFT, etc). Deleting a message actually sets it's DELETED flag, and a later call to expunge() will delete all the messages marked with the DELETED flag.

The IMAP server can be in different states. Most IMAP commands require that a connection is established and a user is authenticated. Certain commands require in addition that a mailbox is selected.

The IMAP transport class allows developers to interface with an IMAP server. The commands which support unique IDs to refer to messages are marked with [*] (see ezcMailImapTransportOptions to find out how to enable unique IDs referencing):

Basic commands:

- connect to an IMAP server (__construct())
- authenticate a user with a username and password (authenticate())
- select a mailbox (selectMailbox())
- disconnect from the IMAP server (disconnect())

Work with mailboxes:

- get the list of mailboxes of the user (listMailboxes())
- create a mailbox (createMailbox())
- rename a mailbox (renameMailbox())
- delete a mailbox (deleteMailbox())
- append a message to a mailbox (append())
- select a mailbox (selectMailbox())
- get the status of messages in the current mailbox (status())
- get the number of messages with a certain flag (countByFlag())

Work with message numbers (on the currently selected mailbox):

- get the message numbers and sizes of all the messages (listMessages())
- get the message numbers and IDs of all the messages (listUniqueIdentifiers())
- [*] get the headers of a certain message (top())
- [*] delete a message (delete() and expunge())
- [*] copy messages to another mailbox (copyMessages())
- [*] get the sizes of the specified messages (fetchSizes())

Work with flags (on the currently selected mailbox):

- [*] get the flags of the specified messages (fetchFlags())
- [*] set a flag on the specified messages (setFlag())
- [*] clear a flag from the specified messages (clearFlag())

Work with ezcMailImapSet sets (parseable with ezcMailParser) (on the currently selected mailbox):

- [*] create a set from all messages (fetchAll())
- [*] create a set from a certain message (fetchByMessageNr())
- [*] create a set from a range of messages (fetchFromOffset())
- [*] create a set from messages with a certain flag (fetchByFlag())
- [*] create a set from a sorted range of messages (sortFromOffset())
- [*] create a set from a sorted list of messages (sortMessages())
- [*] create a set from a free-form search (searchMailbox())

Miscellaneous commands:

- get the capabilities of the IMAP server (capability())
- get the hierarchy delimiter (useful for nested mailboxes) (getHierarchyDelimiter())
- issue a NOOP command to keep the connection alive (noop())

The usual operation with an IMAP server is illustrated by this example:

1. // create a new IMAP transport object by specifying the server name, optional port
2. // and optional SSL mode
3. $options=new ezcMailImapTransportOptions ();
4. $options->ssl=true;
5. $imap=new ezcMailImapTransport ('imap.example.com',null,$options);
7. // Authenticate to the IMAP server
8. $imap-> authenticate ('username','password');
10. // Select a mailbox (here 'Inbox')
11. $imap-> selectMailbox ('Inbox');
13. // issue commands to the IMAP server
14. // for example get the number of RECENT messages
15. $recent=$imap-> countByFlag ('RECENT');
17. // see the above list of commands or consult the online documentation for
18. // the full list of commands you can issue to an IMAP server and examples
20. // disconnect from the IMAP server
21. $imap-> disconnect ();

See ezcMailImapTransportOptions for other options you can specify for IMAP.

Source for this file: /Mail/src/transports/imap/imap_transport.php

Version: | //autogen//
Todo: | ignore messages of a certain size?
Todo: | // support for signing?
Todo: | listUniqueIdentifiers(): add UIVALIDITY value to UID (like in POP3). (if necessary).

### Properties

ezcMailImapTransportOptions | read/write | `$options` Holds the options you can set to the IMAP transport.

### Member Variables

protected static array(string)

`$basicFlags`
Basic flags are used by setFlag() and clearFlag()

Basic flags:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- SEEN - message has been read

protected static array(string)

`$extendedFlags`
Extended flags are used by searchByFlag()

Basic flags:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- RECENT - message is recent
- SEEN - message has been read

Opposites of the above flags:

- UNANSWERED
- UNDELETED
- UNDRAFT
- UNFLAGGED
- OLD
- UNSEEN

Composite flags:

- NEW - equivalent to RECENT + UNSEEN
- ALL - all the messages

protected ezcMailTransportConnection | `$connection = null` Holds the connection to the IMAP server.
protected string | `$currentTag = 'A0000'` Used to generate a tag for sending commands to the IMAP server.
protected string | `$selectedMailbox = null` Holds the currently selected mailbox.
protected string | `$serverType = null` Holds the string which identifies the IMAP server type. Used for fixing problems with Google IMAP (see issue #14360). Possible values are self::SERVER_GIMAP or null for all other servers.
protected int | `$state = self::STATE_NOT_CONNECTED` Holds the connection state.

### Method Summary

public ezcMailImapTransport | `__construct( $server , [ $port = null] , [ $options = array()] )` Creates a new IMAP transport and connects to the $server at $port.
public void | `__destruct( )` Destructs the IMAP transport.
public void | `append( $mailbox , $mail , [ $flags = null] )` Appends $mail to the $mailbox mailbox.
public bool | `authenticate( $user , $password )` Authenticates the user to the IMAP server with $user and $password.
public array(string) | `capability( )` Returns an array with the capabilities of the IMAP server.
public bool | `clearFlag( $messages , $flag )` Clears $flag from $messages.
public bool | `copyMessages( $messages , $destination )` Copies message(s) from the currently selected mailbox to mailbox $destination.
public int | `countByFlag( $flag )` Wrapper function to fetch count of messages by a certain flag.
public bool | `createMailbox( $mailbox )` Creates the mailbox $mailbox.
public bool | `delete( $msgNum )` Deletes the message with the message number $msgNum from the current mailbox.
public bool | `deleteMailbox( $mailbox )` Deletes the mailbox $mailbox.
public void | `disconnect( )` Disconnects the transport from the IMAP server.
public void | `expunge( )` Sends an EXPUNGE command to the server.
public ezcMailParserSet | `fetchAll( [ $deleteFromServer = false] )` Returns an ezcMailImapSet with all the messages from the current mailbox.
public ezcMailImapSet | `fetchByFlag( $flag )` Returns an ezcMailImapSet containing messages with a certain flag from the current mailbox.
public ezcMailImapSet | `fetchByMessageNr( $number , [ $deleteFromServer = false] )` Returns an ezcMailImapSet containing only the $number -th message in the current mailbox.
public array(mixed) | `fetchFlags( $messages )` Fetches IMAP flags for messages $messages.
public ezcMailImapSet | `fetchFromOffset( $offset , [ $count = 0] , [ $deleteFromServer = false] )` Returns an ezcMailImapSet with $count messages starting from $offset from the current mailbox.
public array(int) | `fetchSizes( $messages )` Fetches the sizes in bytes for messages $messages.
public string | `getHierarchyDelimiter( )` Returns the hierarchy delimiter of the IMAP server, useful for handling nested IMAP folders.
protected int | `getMessageSectionSize( $response )` Returns the size of a FETCH section in bytes.
protected string | `getNextTag( )` Generates the next IMAP tag to prepend to client commands.
protected string | `getResponse( $tag , [ $response = null] )` Reads the responses from the server until encountering $tag.
public array(string) | `listMailboxes( [ $reference = ''] , [ $mailbox = '*'] )` Returns an array with the names of the available mailboxes for the user currently authenticated on the IMAP server.
public array(int) | `listMessages( [ $contentType = null] )` Returns a list of the not deleted messages in the current mailbox.
public array(string) | `listUniqueIdentifiers( [ $msgNum = null] )` Returns the unique identifiers for the messages from the current mailbox.
public void | `noop( )` Sends a NOOP command to the server, use it to keep the connection alive.
protected string | `normalizeFlag( $flag )` Clears $flag of unwanted characters and makes it uppercase.
public bool | `renameMailbox( $mailbox , $newName )` Renames the mailbox $mailbox to $newName.
protected int | `responseType( $line )` Parses $line to return the response code.
protected array(int) | `searchByFlag( $flag )` Returns an array of message numbers from the selected mailbox which have a certain flag set.
public ezcMailImapSet | `searchMailbox( [ $criteria = null] )` Returns an ezcMailImapSet containing the messages which match the provided $criteria from the current mailbox.
public void | `selectMailbox( $mailbox , [ $readOnly = false] )` Selects the mailbox $mailbox, which will be the active mailbox for the subsequent commands until it is changed.
public bool | `setFlag( $messages , $flag )` Sets $flag on $messages.
protected array(string) | `sort( $messages , $sortCriteria , [ $reverse = false] )` Sorts message numbers array $messages by the specified $sortCriteria.
public ezcMailImapSet | `sortFromOffset( $offset , [ $count = 0] , $sortCriteria , [ $reverse = false] )` Returns an ezcMailImapSet containing $count messages starting from $offset sorted by $sortCriteria from the current mailbox.
public ezcMailImapSet | `sortMessages( $messages , $sortCriteria , [ $reverse = false] )` Returns an ezcMailImapSet containing messages $messages sorted by $sortCriteria from the current mailbox.
public bool | `status( &$numMessages , &$sizeMessages , [ &$recent = 0] , [ &$unseen = 0] )` Returns information about the messages in the current mailbox.
public string | `top( $msgNum , [ $chars = 0] )` Returns the headers and the first characters from message $msgNum, without setting the SEEN flag.

### Methods

#### __construct

ezcMailImapTransport __construct( string $server , [int $port = null] , [ezcMailImapTransportOptions|array(string=>mixed) $options = array()] )

Creates a new IMAP transport and connects to the $server at $port.

You can specify the $port if the IMAP server is not on the default port 993 (for SSL connections) or 143 (for plain connections). Use the $options parameter to specify an SSL connection.

See ezcMailImapTransportOptions for options you can specify for IMAP.

Example of creating an IMAP transport:

1. // replace with your IMAP server address
2. $imap=new ezcMailImapTransport ('imap.example.com');
4. // if you want to use SSL:
5. $options=new ezcMailImapTransportOptions ();
6. $options->ssl=true;
8. $imap=new ezcMailImapTransport ('imap.example.com',null,$options);

##### Parameters:

Name | Type | Description
--- | --- | ---
`$server` | string |
`$port` | int |
`$options` | ezcMailImapTransportOptions|array(string=>mixed) |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if it was not possible to connect to the server
`ezcBaseValueException` | if $options contains a property with a value not allowed
`ezcBaseExtensionNotFoundException` | if trying to use SSL and the extension openssl is not installed
`ezcBasePropertyNotFoundException` | if $options contains a property not defined

#### __destruct

void __destruct( )

Destructs the IMAP transport.

If there is an open connection to the IMAP server it is closed.

#### append

void append( string $mailbox , string $mail , [array(string) $flags = null] )

Appends $mail to the $mailbox mailbox.

Use this method to create email messages in a mailbox such as Sent or Draft.

$flags is an array of flags to be set to the $mail (if provided):

$flag can be one of:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- SEEN - message has been read

This function automatically adds the '\' in front of each flag when calling the server command.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mailbox` | string |
`$mail` | string |
`$flags` | array(string) |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if user is not authenticated or if the server sent a negative response or if $mailbox does not exists

#### authenticate

bool authenticate( string $user , string $password )

Authenticates the user to the IMAP server with $user and $password.

This method should be called directly after the construction of this object.

If the server is waiting for the authentication process to respond, the connection with the IMAP server will be closed, and false is returned, and it is the application's task to reconnect and reauthenticate.

Example of creating an IMAP transport and authenticating:

1. // replace with your IMAP server address
2. $imap=new ezcMailImapTransport ('imap.example.com');
4. // replace the values with your username and password for the IMAP server
5. $imap-> authenticate ('username','password');

##### Parameters:

Name | Type | Description
--- | --- | ---
`$user` | string |
`$password` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if already authenticated or if the provided username/password combination did not work

#### capability

array(string) capability( )

Returns an array with the capabilities of the IMAP server.

The returned array will be something like this:

1. array('IMAP4rev1','SASL-IR SORT','THREAD=REFERENCES','MULTIAPPEND',
2. 'UNSELECT','LITERAL+','IDLE','CHILDREN','NAMESPACE',
3. 'LOGIN-REFERRALS'
4. );

Before calling this method, a connection to the IMAP server must be established.

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if there was no connection to the server or if the server sent a negative response

#### clearFlag

bool clearFlag( string $messages , string $flag )

Clears $flag from $messages.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages can be:

- a single message number (eg. '1')
- a message range (eg. '1:4')
- a message list (eg. '1,2,4')

$flag can be one of:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- SEEN - message has been read

This function automatically adds the '\' in front of the flag when calling the server command.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. $imap-> clearFlag ('1:4','DRAFT');

##### Parameters:

Name | Type | Description
--- | --- | ---
`$messages` | string |
`$flag` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response or if $flag is not valid

#### copyMessages

bool copyMessages( string $messages , string $destination )

Copies message(s) from the currently selected mailbox to mailbox $destination.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

Warning! When using unique IDs referencing and trying to copy a message with an ID that does not exist, this method will not throw an exception.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$messages` | string |
`$destination` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if the current server state is not accepted or if the server sent a negative response

#### countByFlag

int countByFlag( string $flag )

Wrapper function to fetch count of messages by a certain flag.

$flag can be one of:

Basic flags:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- RECENT - message is recent
- SEEN - message has been read

Opposites of the above flags:

- UNANSWERED
- UNDELETED
- UNDRAFT
- UNFLAGGED
- OLD
- UNSEEN

Composite flags:

- NEW - equivalent to RECENT + UNSEEN
- ALL - all the messages

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$flag` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response or if $flag is not valid

#### createMailbox

bool createMailbox( string $mailbox )

Creates the mailbox $mailbox.

Inbox cannot be created.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mailbox` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if the current server state is not accepted or if the server sent a negative response

#### delete

bool delete( int $msgNum )

Deletes the message with the message number $msgNum from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

The message number $msgNum must be a valid identifier fetched with e.g. listMessages().

The message is not physically deleted, but has its DELETED flag set, and can be later undeleted by clearing its DELETED flag with clearFlag().

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$msgNum` | int |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### deleteMailbox

bool deleteMailbox( string $mailbox )

Deletes the mailbox $mailbox.

Inbox and the the currently selected mailbox cannot be deleted.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mailbox` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if the current server state is not accepted or if trying to delete the currently selected mailbox or if the server sent a negative response

#### disconnect

void disconnect( )

Disconnects the transport from the IMAP server.

#### expunge

void expunge( )

Sends an EXPUNGE command to the server.

This method permanently deletes the messages marked for deletion by the method delete().

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox was not selected or if the server sent a negative response

#### fetchAll

ezcMailParserSet fetchAll( [bool $deleteFromServer = false] )

Returns an ezcMailImapSet with all the messages from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

If $deleteFromServer is set to true the mail will be marked for deletion after retrieval. If not it will be left intact.

The set returned can be parsed with ezcMailParser.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('Inbox');
5. $set=$imap-> fetchAll ();
7. // parse $set with ezcMailParser
8. $parser=new ezcMailParser ();
9. $mails=$parser->parseMail($set);
10. foreach($mailsas$mail)
11. {
12. // process $mail which is an ezcMail object
13. }

##### Parameters:

Name | Type | Description
--- | --- | ---
`$deleteFromServer` | bool |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### fetchByFlag

ezcMailImapSet fetchByFlag( string $flag )

Returns an ezcMailImapSet containing messages with a certain flag from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$flag can be one of:

Basic flags:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- RECENT - message is recent
- SEEN - message has been read

Opposites of the above flags:

- UNANSWERED
- UNDELETED
- UNDRAFT
- UNFLAGGED
- OLD
- UNSEEN

Composite flags:

- NEW - equivalent to RECENT + UNSEEN
- ALL - all the messages

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. // Fetch the messages marked with the RECENT flag
6. $set=$imap-> fetchByFlag ('RECENT');
8. // $set can be parsed with ezcMailParser

##### Parameters:

Name | Type | Description
--- | --- | ---
`$flag` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response or if $flag is not valid

#### fetchByMessageNr

ezcMailImapSet fetchByMessageNr( int $number , [bool $deleteFromServer = false] )

Returns an ezcMailImapSet containing only the $number -th message in the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

If $deleteFromServer is set to true the mail will be marked for deletion after retrieval. If not it will be left intact.

Note: for IMAP the first message is 1 (so for $number = 0 an exception will be thrown).

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('Inbox');
5. $set=$imap-> fetchByMessageNr (1);
7. // $set can be parsed with ezcMailParser

##### Parameters:

Name | Type | Description
--- | --- | ---
`$number` | int |
`$deleteFromServer` | bool |

##### Exceptions:

Type | Description
--- | ---
`ezcMailNoSuchMessageException` | if the message $number is out of range
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### fetchFlags

array(mixed) fetchFlags( array $messages )

Fetches IMAP flags for messages $messages.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1. array(1,2,4);

The format of the returned array is:

1. array(message_number=>array(flags) )

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. $flags=$imap-> fetchFlags (array(1,2,4) );

The returned array $flags will be something like:

1. array(1=>array('\Seen'),
2. 2=>array('\Seen'),
3. 4=>array('\Seen','NonJunk')
4. );

##### Parameters:

Name | Type | Description
--- | --- | ---
`$messages` | array |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### fetchFromOffset

ezcMailImapSet fetchFromOffset( int $offset , [int $count = 0] , [bool $deleteFromServer = false] )

Returns an ezcMailImapSet with $count messages starting from $offset from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

Fetches $count messages starting from the $offset and returns them as a ezcMailImapSet. If $count is not specified or if it is 0, it fetches all messages starting from the $offset.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('Inbox');
5. $set=$imap-> fetchFromOffset (1,10);
7. // $set can be parsed with ezcMailParser

##### Parameters:

Name | Type | Description
--- | --- | ---
`$offset` | int |
`$count` | int |
`$deleteFromServer` | bool |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response
`ezcMailInvalidLimitException` | if $count is negative
`ezcMailOffsetOutOfRangeException` | if $offset is outside of the existing range of messages

#### fetchSizes

array(int) fetchSizes( array $messages )

Fetches the sizes in bytes for messages $messages.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1. array(1,2,4);

The format of the returned array is:

1. array(message_number=>size)

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. $sizes=$imap-> fetchSizes (array(1,2,4) );

The returned array $sizes will be something like:

1. array(1=>1043,
2. 2=>203901,
3. 4=>14277
4. );

##### Parameters:

Name | Type | Description
--- | --- | ---
`$messages` | array |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### getHierarchyDelimiter

string getHierarchyDelimiter( )

Returns the hierarchy delimiter of the IMAP server, useful for handling nested IMAP folders.

For more information about the hierarchy delimiter, consult the IMAP RFCs http://www.faqs.org/rfcs/rfc1730.html or http://www.faqs.org/rfcs/rfc2060.html, section 6.3.8.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

Example of returning the hierarchy delimiter:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
4. $delimiter=$imap->getDelimiter();

After running the above code, $delimiter should be something like "/".

##### Exceptions:

Type | Description
--- | ---
`ezcMailMailTransportException` | if the current server state is not accepted or if the server sent a negative response

#### getMessageSectionSize

int getMessageSectionSize( $response )

Returns the size of a FETCH section in bytes.

The section header looks like: * id FETCH (BODY[TEXT] {size} where size is the size in bytes and id is the message number or ID.

Example: for " * 2 FETCH (BODY[TEXT] {377}" this function returns 377.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$response` |  |

#### getNextTag

string getNextTag( )

Generates the next IMAP tag to prepend to client commands.

The structure of the IMAP tag is Axxxx, where:

- A is a letter (uppercase for conformity)
- x is a digit from 0 to 9

example of generated tag: T5439

It uses the class variable $this->currentTag.

Everytime it is called, the tag increases by 1.

If it reaches the last tag, it wraps around to the first tag.

By default, the first generated tag is A0001.

#### getResponse

string getResponse( string $tag , [string $response = null] )

Reads the responses from the server until encountering $tag.

In IMAP, each command sent by the client is prepended with a alphanumeric tag like 'A1234'. The server sends the response to the client command as lines, and the last line in the response is prepended with the same tag, and it contains the status of the command completion ('OK', 'NO' or 'BAD').

Sometimes the server sends alerts and response lines from other commands before sending the tagged line, so this method just reads all the responses until it encounters $tag.

It returns the tagged line to be processed by the calling method.

If $response is specified, then it will not read the response from the server before searching for $tag in $response.

Before calling this method, a connection to the IMAP server must be established.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$tag` | string |
`$response` | string |

#### listMailboxes

array(string) listMailboxes( [string $reference = ''] , [string $mailbox = '*'] )

Returns an array with the names of the available mailboxes for the user currently authenticated on the IMAP server.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

For more information about $reference and $mailbox, consult the IMAP RFCs documents (http://www.faqs.org/rfcs/rfc1730.html or http://www.faqs.org/rfcs/rfc2060.html, section 7.2.2.).

By default, $reference is "" and $mailbox is "*".

The array returned contains the mailboxes available for the connected user on this IMAP server. Inbox is a special mailbox, and it can be specified upper-case or lower-case or mixed-case. The other mailboxes should be specified as they are (to the selectMailbox() method).

Example of listing mailboxes:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
4. $mailboxes=$imap-> listMailboxes ();

##### Parameters:

Name | Type | Description
--- | --- | ---
`$reference` | string |
`$mailbox` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailMailTransportException` | if the current server state is not accepted or if the server sent a negative response

#### listMessages

array(int) listMessages( [string $contentType = null] )

Returns a list of the not deleted messages in the current mailbox.

It returns only the messages with the flag DELETED not set.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

The format of the returned array is

1. array(message_id=>size);

Example:

1. array(2=>1700,5=>1450,6=>21043);

If $contentType is set, it returns only the messages with $contentType in the Content-Type header.

For example $contentType can be "multipart/mixed" to return only the messages with attachments.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$contentType` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### listUniqueIdentifiers

array(string) listUniqueIdentifiers( [int $msgNum = null] )

Returns the unique identifiers for the messages from the current mailbox.

You can fetch the unique identifier for a specific message by providing the $msgNum parameter.

The unique identifier can be used to recognize mail from servers between requests. In contrast to the message numbers the unique numbers assigned to an email usually never changes.

The format of the returned array is:

1. array(message_num=>unique_id);

Example:

1. array(1=>216,2=>217,3=>218,4=>219);

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$msgNum` | int |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### noop

void noop( )

Sends a NOOP command to the server, use it to keep the connection alive.

Before calling this method, a connection to the IMAP server must be established.

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if there was no connection to the server or if the server sent a negative response

#### normalizeFlag

string normalizeFlag( string $flag )

Clears $flag of unwanted characters and makes it uppercase.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$flag` | string |

#### renameMailbox

bool renameMailbox( string $mailbox , string $newName )

Renames the mailbox $mailbox to $newName.

Inbox cannot be renamed.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mailbox` | string |
`$newName` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if the current server state is not accepted or if trying to rename the currently selected mailbox or if the server sent a negative response

#### responseType

int responseType( string $line )

Parses $line to return the response code.

Returns one of the following:

- RESPONSE_OK
- RESPONSE_NO
- RESPONSE_BAD
- RESPONSE_UNTAGGED
- RESPONSE_FEEDBACK

##### Parameters:

Name | Type | Description
--- | --- | ---
`$line` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if the IMAP response ($line) is not recognized

#### searchByFlag

array(int) searchByFlag( string $flag )

Returns an array of message numbers from the selected mailbox which have a certain flag set.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$flag can be one of:

Basic flags:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- RECENT - message is recent
- SEEN - message has been read

Opposites of the above flags:

- UNANSWERED
- UNDELETED
- UNDRAFT
- UNFLAGGED
- OLD
- UNSEEN

Composite flags:

- NEW - equivalent to RECENT + UNSEEN
- ALL - all the messages

The returned array is something like this:

1. array(0=>1,1=>5);

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$flag` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response or if $flag is not valid

#### searchMailbox

ezcMailImapSet searchMailbox( [string $criteria = null] )

Returns an ezcMailImapSet containing the messages which match the provided $criteria from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

See http://www.faqs.org/rfcs/rfc1730.html

- 6.4.4. (or http://www.faqs.org/rfcs/rfc1730.html - 6.4.4.) for criterias

which can be used for searching. The criterias can be combined in the same search string (separate the criterias with spaces).

If $criteria is null or empty then it will default to 'ALL' (returns all messages in the mailbox).

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Examples:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. // return an ezcMailImapSet containing all messages flagged as 'SEEN'
6. $set=$imap-> searchMailbox ('SEEN');
8. // return an ezcMailImapSet containing messages with 'release' in their Subject
9. $set=$imap-> searchMailbox ('SUBJECT "release"');
11. // criterias can be combined:
12. // return an ezcMailImapSet containing messages flagged as 'SEEN' and
13. // with 'release' in their Subject
14. $set=$imap-> searchMailbox ('SEEN SUBJECT "release"');
16. // $set can be parsed with ezcMailParser

##### Parameters:

Name | Type | Description
--- | --- | ---
`$criteria` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### selectMailbox

void selectMailbox( string $mailbox , [bool $readOnly = false] )

Selects the mailbox $mailbox, which will be the active mailbox for the subsequent commands until it is changed.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

Inbox is a special mailbox and can be specified with any case.

This method should be called after authentication, and before fetching any messages.

Example of selecting a mailbox:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
4. $imap-> selectMailbox ('Reports 2006');

##### Parameters:

Name | Type | Description
--- | --- | ---
`$mailbox` | string |
`$readOnly` | bool |

##### Exceptions:

Type | Description
--- | ---
`ezcMailMailTransportException` | if the current server state is not accepted or if the server sent a negative response

#### setFlag

bool setFlag( string $messages , string $flag )

Sets $flag on $messages.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages can be:

- a single message number (eg. 1)
- a message range (eg. 1:4)
- a message list (eg. 1,2,4)

$flag can be one of:

- ANSWERED - message has been answered
- DELETED - message is marked to be deleted by later EXPUNGE
- DRAFT - message is marked as a draft
- FLAGGED - message is "flagged" for urgent/special attention
- SEEN - message has been read

This function automatically adds the '\' in front of the flag when calling the server command.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. $imap-> setFlag ('1:4','DRAFT');

##### Parameters:

Name | Type | Description
--- | --- | ---
`$messages` | string |
`$flag` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response or if $flag is not valid

#### sort

array(string) sort( array(int) $messages , string $sortCriteria , [bool $reverse = false] )

Sorts message numbers array $messages by the specified $sortCriteria.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1. array(1,2,4);

$sortCriteria is an email header like: Subject, To, From, Date, Sender.

The sorting is done with the php function natcasesort().

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$messages` | array(int) |
`$sortCriteria` | string |
`$reverse` | bool |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response or if the array $messages is empty

#### sortFromOffset

ezcMailImapSet sortFromOffset( int $offset , [int $count = 0] , string $sortCriteria , [bool $reverse = false] )

Returns an ezcMailImapSet containing $count messages starting from $offset sorted by $sortCriteria from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

It is useful for paging through a mailbox.

Fetches $count messages starting from the $offset and returns them as a ezcMailImapSet. If $count is is 0, it fetches all messages starting from the $offset.

$sortCriteria is an email header like: Subject, To, From, Date, Sender, etc.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. // Fetch a range of messages sorted by Date
6. $set=$imap-> sortFromOffset (1,10,"Date");
8. // $set can be parsed with ezcMailParser

##### Parameters:

Name | Type | Description
--- | --- | ---
`$offset` | int |
`$count` | int |
`$sortCriteria` | string |
`$reverse` | bool |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response
`ezcMailInvalidLimitException` | if $count is negative
`ezcMailOffsetOutOfRangeException` | if $offset is outside of the existing range of messages

#### sortMessages

ezcMailImapSet sortMessages( array(int) $messages , string $sortCriteria , [bool $reverse = false] )

Returns an ezcMailImapSet containing messages $messages sorted by $sortCriteria from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1. array(1,2,4);

$sortCriteria is an email header like: Subject, To, From, Date, Sender, etc.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('mailbox');// Inbox or another mailbox
5. // Fetch the list of messages sorted by Date
6. $set=$imap-> sortMessages (1,10,"Date");
8. // $set can be parsed with ezcMailParser

##### Parameters:

Name | Type | Description
--- | --- | ---
`$messages` | array(int) |
`$sortCriteria` | string |
`$reverse` | bool |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response or if array $messages is empty

#### status

bool status( int &$numMessages , int &$sizeMessages , [int &$recent = 0] , [int &$unseen = 0] )

Returns information about the messages in the current mailbox.

The information returned through the parameters is:

- $numMessages = number of not deleted messages in the selected mailbox
- $sizeMessages = sum of the not deleted messages sizes
- $recent = number of recent and not deleted messages
- $unseen = number of unseen and not deleted messages

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example of returning the status of the currently selected mailbox:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('Inbox');
5. $imap-> status ($numMessages,$sizeMessages,$recent,$unseen);

After running the above code, $numMessages, $sizeMessages, $recent and $unseen will be populated with values.

##### Parameters:

Name | Type | Description
--- | --- | ---
`&$numMessages` | int |
`&$sizeMessages` | int |
`&$recent` | int |
`&$unseen` | int |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

#### top

string top( int $msgNum , [int $chars = 0] )

Returns the headers and the first characters from message $msgNum, without setting the SEEN flag.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

If the command failed or if it was not supported by the server an empty string is returned.

This method is useful for retrieving the headers of messages from the mailbox as strings, which can be later parsed with ezcMailParser and ezcMailVariableSet. In this way the retrieval of the full messages from the server is avoided when building a list of messages.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example of listing the mail headers of all the messages in the current mailbox:

1. $imap=new ezcMailImapTransport ('imap.example.com');
2. $imap-> authenticate ('username','password');
3. $imap-> selectMailbox ('Inbox');
5. $parser=new ezcMailParser ();
6. $messages=$imap-> listMessages ();
7. foreach($messagesas$messageNr=>$size)
8. {
9. $set=new ezcMailVariableSet ($imap-> top ($messageNr) );
10. $mail=$parser->parseMail($set);
11. $mail=$mail[0];
12. echo"From: {$mail->from}, Subject: {$mail->subject}, Size: {$size}\n";
13. }

For a more advanced example see the "Mail listing example" in the online documentation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$msgNum` | int |
`$chars` | int |

##### Exceptions:

Type | Description
--- | ---
`ezcMailTransportException` | if a mailbox is not selected or if the server sent a negative response

Documentation generated by phpDocumentor 1.4.3