Zeta Components - high quality PHP components

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)

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

• 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())

• 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())

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

• [*] 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())

• 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())

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.

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

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

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

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

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' );

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.

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

• 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

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' );

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.

$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

• UNANSWERED
• UNDELETED
• UNDRAFT
• UNFLAGGED
• OLD
• UNSEEN

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

Inbox cannot be created.

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

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.

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.

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.

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

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

• UNANSWERED
• UNDELETED
• UNDRAFT
• UNFLAGGED
• OLD
• UNSEEN

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

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

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( 1 );
6.  
7.  // $set can be parsed with ezcMailParser

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

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->fetchFromOffset( 1, 10 );
6.  
7.  // $set can be parsed with ezcMailParser

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

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 "/".

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.

The structure of the IMAP tag is Axxxx, where:

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

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.

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.

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();

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.

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.

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

Inbox cannot be renamed.

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

Returns one of the following:

• RESPONSE_OK
• RESPONSE_NO
• RESPONSE_BAD
• RESPONSE_UNTAGGED
• RESPONSE_FEEDBACK

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

• UNANSWERED
• UNDELETED
• UNDRAFT
• UNFLAGGED
• OLD
• UNSEEN

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

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.

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

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

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' );

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)

• 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

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' );

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.

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->sortFromOffset( 1, 10, "Date" );
7.  
8.  // $set can be parsed with ezcMailParser

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
4.  
5.  // Fetch the list of messages sorted by Date
6.  $set = $imap->sortMessages( 1, 10, "Date" );
7.  
8.  // $set can be parsed with ezcMailParser

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

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.

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.