Path

ez components / documentation / api reference / 2009.2.1 / mail


eZ Components 2009.2.1

Mail: ezcMailImapTransport

[ Tutorial ] [ Display example ] [ Mail listing example ] [ Rfcs ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcMailImapTransport

The class ezcMailImapTransport implements functionality for handling IMAP mail servers. [source]
The implementation supports most of the commands specified in: 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: Work with mailboxes: Work with message numbers (on the currently selected mailbox): 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): Miscellaneous commands: 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 );
 6.  
 7.  // Authenticate to the IMAP server
 8.  $imap->authenticate'username''password' );
 9.  
10.  // Select a mailbox (here 'Inbox')
11.  $imap->selectMailbox'Inbox' );
12.  
13.  // issue commands to the IMAP server
14.  // for example get the number of RECENT messages
15.  $recent $imap->countByFlag'RECENT' );
16.  
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
19.  
20.  // disconnect from the IMAP server
21.  $imap->disconnect();
See ezcMailImapTransportOptions for other options you can specify for IMAP.

Properties

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

Member Variables

protected array(string) $basicFlags = array( 'ANSWERED', 'DELETED', 'DRAFT', 'FLAGGED', 'SEEN' )
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 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 array(string) $extendedFlags = array( 'ALL', 'ANSWERED', 'DELETED', 'DRAFT', 'FLAGGED', 'NEW', 'OLD', 'RECENT', 'SEEN', 'UNANSWERED', 'UNDELETED', 'UNDRAFT', 'UNFLAGGED', 'UNRECENT', 'UNSEEN' )
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 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' );
 3.  
 4.  // if you want to use SSL:
 5.  $options new ezcMailImapTransportOptions();
 6.  $options->ssl true;
 7.  
 8.  $imap new ezcMailImapTransport'imap.example.com'null$options );

Parameters

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

Throws

ClassDescription
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)  

Throws

ClassDescription
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' );
 3.  
 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  

Throws

ClassDescription
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.

Throws

ClassDescription
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
 4.  
 5.  $imap->clearFlag'1:4''DRAFT' );

Parameters

Name Type Description
$messages string  
$flag string  

Throws

ClassDescription
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  

Throws

ClassDescription
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  

Throws

ClassDescription
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  

Throws

ClassDescription
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  

Throws

ClassDescription
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  

Throws

ClassDescription
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.

Throws

ClassDescription
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' );
 4.  
 5.  $set $imap->fetchAll();
 6.  
 7.  // parse $set with ezcMailParser
 8.  $parser new ezcMailParser();
 9.  $mails $parser->parseMail$set );
10.  foreach $mails as $mail )
11.  {
12.      // process $mail which is an ezcMail object
13.  }

Parameters

Name Type Description
$deleteFromServer bool  

Throws

ClassDescription
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
 4.  
 5.  // Fetch the messages marked with the RECENT flag
 6.  $set $imap->fetchByFlag'RECENT' );
 7.  
 8.  // $set can be parsed with ezcMailParser

Parameters

Name Type Description
$flag string  

Throws

ClassDescription
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' );
 4.  
 5.  $set $imap->fetchByMessageNr);
 6.  
 7.  // $set can be parsed with ezcMailParser

Parameters

Name Type Description
$number int  
$deleteFromServer bool  

Throws

ClassDescription
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.    array12);
The format of the returned array is:
 1.    arraymessage_number => arrayflags ) )
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
 4.  
 5.  $flags $imap->fetchFlagsarray12) );
The returned array $flags will be something like:
 1.    array=> array'\Seen' ),
 2.           => array'\Seen' ),
 3.           => array'\Seen''NonJunk' )
 4.         );

Parameters

Name Type Description
$messages array  

Throws

ClassDescription
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' );
 4.  
 5.  $set $imap->fetchFromOffset110 );
 6.  
 7.  // $set can be parsed with ezcMailParser

Parameters

Name Type Description
$offset int  
$count int  
$deleteFromServer bool  

Throws

ClassDescription
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.    array12);
The format of the returned array is:
 1.    arraymessage_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
 4.  
 5.  $sizes $imap->fetchSizesarray12) );
The returned array $sizes will be something like:
 1.    array=> 1043,
 2.           => 203901,
 3.           => 14277
 4.         );

Parameters

Name Type Description
$messages array  

Throws

ClassDescription
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' );
 3.  
 4.  $delimiter $imap->getDelimiter();
After running the above code, $delimiter should be something like "/".

Throws

ClassDescription
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' );
 3.  
 4.  $mailboxes $imap->listMailboxes();

Parameters

Name Type Description
$reference string  
$mailbox string  

Throws

ClassDescription
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.    arraymessage_id => size );
Example:
 1.    array=> 1700=> 1450=> 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  

Throws

ClassDescription
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.    arraymessage_num => unique_id );
Example:
 1.    array=> 216=> 217=> 218=> 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  

Throws

ClassDescription
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.

Throws

ClassDescription
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  

Throws

ClassDescription
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  

Throws

ClassDescription
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=> 1=> );
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  

Throws

ClassDescription
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 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
 4.  
 5.  // return an ezcMailImapSet containing all messages flagged as 'SEEN'
 6.  $set $imap->searchMailbox'SEEN' );
 7.  
 8.  // return an ezcMailImapSet containing messages with 'release' in their Subject
 9.  $set $imap->searchMailbox'SUBJECT "release"' );
10.  
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"' );
15.  
16.  // $set can be parsed with ezcMailParser

Parameters

Name Type Description
$criteria string  

Throws

ClassDescription
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' );
 3.  
 4.  $imap->selectMailbox'Reports 2006' );

Parameters

Name Type Description
$mailbox string  
$readOnly bool  

Throws

ClassDescription
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
 4.  
 5.  $imap->setFlag'1:4''DRAFT' );

Parameters

Name Type Description
$messages string  
$flag string  

Throws

ClassDescription
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.    array12);
$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  

Throws

ClassDescription
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
 4.  
 5.  // Fetch a range of messages sorted by Date
 6.  $set $imap->sortFromOffset110"Date" );
 7.  
 8.  // $set can be parsed with ezcMailParser

Parameters

Name Type Description
$offset int  
$count int  
$sortCriteria string  
$reverse bool  

Throws

ClassDescription
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.    array12);
$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
 4.  
 5.  // Fetch the list of messages sorted by Date
 6.  $set $imap->sortMessages110"Date" );
 7.  
 8.  // $set can be parsed with ezcMailParser

Parameters

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

Throws

ClassDescription
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' );
 4.  
 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  

Throws

ClassDescription
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' );
 4.  
 5.  $parser new ezcMailParser();
 6.  $messages $imap->listMessages();
 7.  foreach $messages as $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  

Throws

ClassDescription
ezcMailTransportException if a mailbox is not selected or if the server sent a negative response

Last updated: Tue, 23 Mar 2010