PHP Class ezcMailImapTransport

The implementation supports most of the commands specified in: - {@link http://www.faqs.org/rfcs/rfc1730.html} (IMAP4) - {@link 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 {@link 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 {@link ezcMailImapTransportOptions} to find out how to enable unique IDs referencing): Basic commands: - connect to an IMAP server ({@link __construct()}) - authenticate a user with a username and password ({@link authenticate()}) - select a mailbox ({@link selectMailbox()}) - disconnect from the IMAP server ({@link disconnect()}) Work with mailboxes: - get the list of mailboxes of the user ({@link listMailboxes()}) - create a mailbox ({@link createMailbox()}) - rename a mailbox ({@link renameMailbox()}) - delete a mailbox ({@link deleteMailbox()}) - append a message to a mailbox ({@link append()}) - select a mailbox ({@link selectMailbox()}) - get the status of messages in the current mailbox ({@link status()}) - get the number of messages with a certain flag ({@link countByFlag()}) Work with message numbers (on the currently selected mailbox): - get the message numbers and sizes of all the messages ({@link listMessages()}) - get the message numbers and IDs of all the messages ({@link listUniqueIdentifiers()}) - [*] get the headers of a certain message ({@link top()}) - [*] delete a message ({@link delete()} and {@link expunge()}) - [*] copy messages to another mailbox ({@link copyMessages()}) - [*] get the sizes of the specified messages ({@link fetchSizes()}) Work with flags (on the currently selected mailbox): - [*] get the flags of the specified messages ({@link fetchFlags()}) - [*] set a flag on the specified messages ({@link setFlag()}) - [*] clear a flag from the specified messages ({@link clearFlag()}) Work with {@link ezcMailImapSet} sets (parseable with {@link ezcMailParser}) (on the currently selected mailbox): - [*] create a set from all messages ({@link fetchAll()}) - [*] create a set from a certain message ({@link fetchByMessageNr()}) - [*] create a set from a range of messages ({@link fetchFromOffset()}) - [*] create a set from messages with a certain flag ({@link fetchByFlag()}) - [*] create a set from a sorted range of messages ({@link sortFromOffset()}) - [*] create a set from a sorted list of messages ({@link sortMessages()}) - [*] create a set from a free-form search ({@link searchMailbox()}) Miscellaneous commands: - get the capabilities of the IMAP server ({@link capability()}) - get the hierarchy delimiter (useful for nested mailboxes) ({@link getHierarchyDelimiter()}) - issue a NOOP command to keep the connection alive ({@link noop()}) The usual operation with an IMAP server is illustrated by this example: create a new IMAP transport object by specifying the server name, optional port and optional SSL mode $options = new ezcMailImapTransportOptions(); $options->ssl = true; $imap = new ezcMailImapTransport( 'imap.example.com', null, $options ); Authenticate to the IMAP server $imap->authenticate( 'username', 'password' ); Select a mailbox (here 'Inbox') $imap->selectMailbox( 'Inbox' ); issue commands to the IMAP server for example get the number of RECENT messages $recent = $imap->countByFlag( 'RECENT' ); see the above list of commands or consult the online documentation for the full list of commands you can issue to an IMAP server and examples disconnect from the IMAP server $imap->disconnect(); See {@link ezcMailImapTransportOptions} for other options you can specify for IMAP.
Show file Open project: zetacomponents/mail Class Usage Examples

Protected Properties

Property Type Description
$basicFlags array(string) 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
$connection ezcMailTransportConnection Holds the connection to the IMAP server.
$currentTag string Used to generate a tag for sending commands to the IMAP server.
$extendedFlags array(string) 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
$selectedMailbox string Holds the currently selected mailbox.
$serverType string Used for fixing problems with Google IMAP (see issue #14360). Possible values are {@link self::SERVER_GIMAP} or null for all other servers.
$state Holds the connection state.

Public Methods

Method Description
__construct ( string $server, integer $port = null, ezcMailImapTransportOptions | array(string=>mixed) $options = [] ) Creates a new IMAP transport and connects to the $server at $port.
__destruct ( ) Destructs the IMAP transport.
__get ( string $name ) Returns the value of the property $name.
__isset ( string $name ) : boolean Returns true if the property $name is set, otherwise false.
__set ( string $name, mixed $value ) Sets the value of the property $name to $value.
append ( string $mailbox, string $mail, array(string) $flags = null ) Appends $mail to the $mailbox mailbox.
authenticate ( string $user, string $password ) : boolean Authenticates the user to the IMAP server with $user and $password.
capability ( ) : array(string) Returns an array with the capabilities of the IMAP server.
clearFlag ( string $messages, string $flag ) : boolean Clears $flag from $messages.
copyMessages ( string $messages, string $destination ) : boolean Copies message(s) from the currently selected mailbox to mailbox $destination.
countByFlag ( string $flag ) : integer Wrapper function to fetch count of messages by a certain flag.
createMailbox ( string $mailbox ) : boolean Creates the mailbox $mailbox.
delete ( integer $msgNum ) : boolean Deletes the message with the message number $msgNum from the current mailbox.
deleteMailbox ( string $mailbox ) : boolean Deletes the mailbox $mailbox.
disconnect ( ) Disconnects the transport from the IMAP server.
expunge ( ) Sends an EXPUNGE command to the server.
fetchAll ( boolean $deleteFromServer = false ) : ezcMailParserSet Returns an {@link ezcMailImapSet} with all the messages from the current mailbox.
fetchByFlag ( string $flag ) : ezcMailImapSet Returns an {@link ezcMailImapSet} containing messages with a certain flag from the current mailbox.
fetchByMessageNr ( integer $number, boolean $deleteFromServer = false ) : ezcMailImapSet Returns an {@link ezcMailImapSet} containing only the $number -th message in the current mailbox.
fetchFlags ( array $messages ) : array(mixed) Fetches IMAP flags for messages $messages.
fetchFromOffset ( integer $offset, integer $count, boolean $deleteFromServer = false ) : ezcMailImapSet Returns an {@link ezcMailImapSet} with $count messages starting from $offset from the current mailbox.
fetchSizes ( array $messages ) : array(int) Fetches the sizes in bytes for messages $messages.
getHierarchyDelimiter ( ) : string Returns the hierarchy delimiter of the IMAP server, useful for handling nested IMAP folders.
listMailboxes ( string $reference = '', string $mailbox = '*' ) : array(string) Returns an array with the names of the available mailboxes for the user currently authenticated on the IMAP server.
listMessages ( string $contentType = null ) : array(int) Returns a list of the not deleted messages in the current mailbox.
listUniqueIdentifiers ( integer $msgNum = null ) : array(string) Returns the unique identifiers for the messages from the current mailbox.
noop ( ) Sends a NOOP command to the server, use it to keep the connection alive.
renameMailbox ( string $mailbox, string $newName ) : boolean Renames the mailbox $mailbox to $newName.
searchMailbox ( string $criteria = null ) : ezcMailImapSet Returns an {@link ezcMailImapSet} containing the messages which match the provided $criteria from the current mailbox.
selectMailbox ( string $mailbox, boolean $readOnly = false ) Selects the mailbox $mailbox, which will be the active mailbox for the subsequent commands until it is changed.
setFlag ( string $messages, string $flag ) : boolean Sets $flag on $messages.
sortFromOffset ( integer $offset, integer $count, string $sortCriteria, boolean $reverse = false ) : ezcMailImapSet Returns an {@link ezcMailImapSet} containing $count messages starting from $offset sorted by $sortCriteria from the current mailbox.
sortMessages ( array(int) $messages, string $sortCriteria, boolean $reverse = false ) : ezcMailImapSet Returns an {@link ezcMailImapSet} containing messages $messages sorted by $sortCriteria from the current mailbox.
status ( &$numMessages, &$sizeMessages, &$recent, &$unseen ) : boolean Returns information about the messages in the current mailbox.
top ( integer $msgNum, integer $chars ) : string Returns the headers and the first characters from message $msgNum, without setting the SEEN flag.

Protected Methods

Method Description
getMessageSectionSize ( $response ) : integer Returns the size of a FETCH section in bytes.
getNextTag ( ) : string Generates the next IMAP tag to prepend to client commands.
getResponse ( string $tag, string $response = null ) : string Reads the responses from the server until encountering $tag.
normalizeFlag ( string $flag ) : string Clears $flag of unwanted characters and makes it uppercase.
responseType ( string $line ) : integer Parses $line to return the response code.
searchByFlag ( string $flag ) : array(int) Returns an array of message numbers from the selected mailbox which have a certain flag set.
sort ( array(int) $messages, string $sortCriteria, boolean $reverse = false ) : array(string) Sorts message numbers array $messages by the specified $sortCriteria.

Method Details

__construct() public method

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 {@link ezcMailImapTransportOptions} for options you can specify for IMAP. Example of creating an IMAP transport: replace with your IMAP server address $imap = new ezcMailImapTransport( 'imap.example.com' ); if you want to use SSL: $options = new ezcMailImapTransportOptions(); $options->ssl = true; $imap = new ezcMailImapTransport( 'imap.example.com', null, $options );
public __construct ( string $server, integer $port = null, ezcMailImapTransportOptions | array(string=>mixed) $options = [] )
$server string
$port integer
$options ezcMailImapTransportOptions | array(string=>mixed)

__destruct() public method

If there is an open connection to the IMAP server it is closed.
public __destruct ( )

__get() public method

Returns the value of the property $name.
public __get ( string $name )
$name string

__isset() public method

Returns true if the property $name is set, otherwise false.
public __isset ( string $name ) : boolean
$name string
return boolean

__set() public method

Sets the value of the property $name to $value.
public __set ( string $name, mixed $value )
$name string
$value mixed

append() public method

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.
public append ( string $mailbox, string $mail, array(string) $flags = null )
$mailbox string
$mail string
$flags array(string)

authenticate() public method

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: replace with your IMAP server address $imap = new ezcMailImapTransport( 'imap.example.com' ); replace the values with your username and password for the IMAP server $imap->authenticate( 'username', 'password' );
public authenticate ( string $user, string $password ) : boolean
$user string
$password string
return boolean

capability() public method

The returned array will be something like this: array( 'IMAP4rev1', 'SASL-IR SORT', 'THREAD=REFERENCES', 'MULTIAPPEND', 'UNSELECT', 'LITERAL+', 'IDLE', 'CHILDREN', 'NAMESPACE', 'LOGIN-REFERRALS' ); Before calling this method, a connection to the IMAP server must be established.
public capability ( ) : array(string)
return array(string)

clearFlag() public method

This method supports unique IDs instead of message numbers. See {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox $imap->clearFlag( '1:4', 'DRAFT' );
public clearFlag ( string $messages, string $flag ) : boolean
$messages string
$flag string
return boolean

copyMessages() public method

This method supports unique IDs instead of message numbers. See {@link 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.
public copyMessages ( string $messages, string $destination ) : boolean
$messages string
$destination string
return boolean

countByFlag() public method

$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.
public countByFlag ( string $flag ) : integer
$flag string
return integer

createMailbox() public method

Inbox cannot be created. Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.
public createMailbox ( string $mailbox ) : boolean
$mailbox string
return boolean

delete() public method

This method supports unique IDs instead of message numbers. See {@link ezcMailImapTransportOptions} for how to enable unique IDs referencing. The message number $msgNum must be a valid identifier fetched with e.g. {@link listMessages()}. The message is not physically deleted, but has its DELETED flag set, and can be later undeleted by clearing its DELETED flag with {@link 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.
public delete ( integer $msgNum ) : boolean
$msgNum integer
return boolean

deleteMailbox() public method

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.
public deleteMailbox ( string $mailbox ) : boolean
$mailbox string
return boolean

disconnect() public method

Disconnects the transport from the IMAP server.
public disconnect ( )

expunge() public method

This method permanently deletes the messages marked for deletion by the method {@link 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.
public expunge ( )

fetchAll() public method

This method supports unique IDs instead of message numbers. See {@link 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 {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'Inbox' ); $set = $imap->fetchAll(); parse $set with ezcMailParser $parser = new ezcMailParser(); $mails = $parser->parseMail( $set ); foreach ( $mails as $mail ) { process $mail which is an ezcMail object }
public fetchAll ( boolean $deleteFromServer = false ) : ezcMailParserSet
$deleteFromServer boolean
return ezcMailParserSet

fetchByFlag() public method

This method supports unique IDs instead of message numbers. See {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox Fetch the messages marked with the RECENT flag $set = $imap->fetchByFlag( 'RECENT' ); $set can be parsed with ezcMailParser
public fetchByFlag ( string $flag ) : ezcMailImapSet
$flag string
return ezcMailImapSet

fetchByMessageNr() public method

This method supports unique IDs instead of message numbers. See {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'Inbox' ); $set = $imap->fetchByMessageNr( 1 ); $set can be parsed with ezcMailParser
public fetchByMessageNr ( integer $number, boolean $deleteFromServer = false ) : ezcMailImapSet
$number integer
$deleteFromServer boolean
return ezcMailImapSet

fetchFlags() public method

This method supports unique IDs instead of message numbers. See {@link ezcMailImapTransportOptions} for how to enable unique IDs referencing. $messages is an array of message numbers, for example: array( 1, 2, 4 ); The format of the returned array is: 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox $flags = $imap->fetchFlags( array( 1, 2, 4 ) ); The returned array $flags will be something like: array( 1 => array( '\Seen' ), 2 => array( '\Seen' ), 4 => array( '\Seen', 'NonJunk' ) );
public fetchFlags ( array $messages ) : array(mixed)
$messages array
return array(mixed)

fetchFromOffset() public method

This method supports unique IDs instead of message numbers. See {@link ezcMailImapTransportOptions} for how to enable unique IDs referencing. Fetches $count messages starting from the $offset and returns them as a {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'Inbox' ); $set = $imap->fetchFromOffset( 1, 10 ); $set can be parsed with ezcMailParser
public fetchFromOffset ( integer $offset, integer $count, boolean $deleteFromServer = false ) : ezcMailImapSet
$offset integer
$count integer
$deleteFromServer boolean
return ezcMailImapSet

fetchSizes() public method

This method supports unique IDs instead of message numbers. See {@link ezcMailImapTransportOptions} for how to enable unique IDs referencing. $messages is an array of message numbers, for example: array( 1, 2, 4 ); The format of the returned array is: 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox $sizes = $imap->fetchSizes( array( 1, 2, 4 ) ); The returned array $sizes will be something like: array( 1 => 1043, 2 => 203901, 4 => 14277 );
public fetchSizes ( array $messages ) : array(int)
$messages array
return array(int)

getHierarchyDelimiter() public method

For more information about the hierarchy delimiter, consult the IMAP RFCs {@link http://www.faqs.org/rfcs/rfc1730.html} or {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $delimiter = $imap->getDelimiter(); After running the above code, $delimiter should be something like "/".
public getHierarchyDelimiter ( ) : string
return string

getMessageSectionSize() protected method

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.
protected getMessageSectionSize ( $response ) : integer
return integer

getNextTag() protected method

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.
protected getNextTag ( ) : string
return string

getResponse() protected method

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.
protected getResponse ( string $tag, string $response = null ) : string
$tag string
$response string
return string

listMailboxes() public method

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 ({@link http://www.faqs.org/rfcs/rfc1730.html} or {@link 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 {@link selectMailbox()} method). Example of listing mailboxes: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $mailboxes = $imap->listMailboxes();
public listMailboxes ( string $reference = '', string $mailbox = '*' ) : array(string)
$reference string
$mailbox string
return array(string)

listMessages() public method

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 array( message_id => size ); Example: 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.
public listMessages ( string $contentType = null ) : array(int)
$contentType string
return array(int)

listUniqueIdentifiers() public method

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: array( message_num => unique_id ); Example: 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.
public listUniqueIdentifiers ( integer $msgNum = null ) : array(string)
$msgNum integer
return array(string)

noop() public method

Before calling this method, a connection to the IMAP server must be established.
public noop ( )

normalizeFlag() protected method

Clears $flag of unwanted characters and makes it uppercase.
protected normalizeFlag ( string $flag ) : string
$flag string
return string

renameMailbox() public method

Inbox cannot be renamed. Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.
public renameMailbox ( string $mailbox, string $newName ) : boolean
$mailbox string
$newName string
return boolean

responseType() protected method

Returns one of the following: - {@link RESPONSE_OK} - {@link RESPONSE_NO} - {@link RESPONSE_BAD} - {@link RESPONSE_UNTAGGED} - {@link RESPONSE_FEEDBACK}
protected responseType ( string $line ) : integer
$line string
return integer

searchByFlag() protected method

This method supports unique IDs instead of message numbers. See {@link 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: 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.
protected searchByFlag ( string $flag ) : array(int)
$flag string
return array(int)

searchMailbox() public method

This method supports unique IDs instead of message numbers. See {@link ezcMailImapTransportOptions} for how to enable unique IDs referencing. See {@link http://www.faqs.org/rfcs/rfc1730.html} - 6.4.4. (or {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox return an ezcMailImapSet containing all messages flagged as 'SEEN' $set = $imap->searchMailbox( 'SEEN' ); return an ezcMailImapSet containing messages with 'release' in their Subject $set = $imap->searchMailbox( 'SUBJECT "release"' ); criterias can be combined: return an ezcMailImapSet containing messages flagged as 'SEEN' and with 'release' in their Subject $set = $imap->searchMailbox( 'SEEN SUBJECT "release"' ); $set can be parsed with ezcMailParser
public searchMailbox ( string $criteria = null ) : ezcMailImapSet
$criteria string
return ezcMailImapSet

selectMailbox() public method

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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'Reports 2006' );
public selectMailbox ( string $mailbox, boolean $readOnly = false )
$mailbox string
$readOnly boolean

setFlag() public method

This method supports unique IDs instead of message numbers. See {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox $imap->setFlag( '1:4', 'DRAFT' );
public setFlag ( string $messages, string $flag ) : boolean
$messages string
$flag string
return boolean

sort() protected method

This method supports unique IDs instead of message numbers. See {@link ezcMailImapTransportOptions} for how to enable unique IDs referencing. $messages is an array of message numbers, for example: 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.
protected sort ( array(int) $messages, string $sortCriteria, boolean $reverse = false ) : array(string)
$messages array(int)
$sortCriteria string
$reverse boolean
return array(string)

sortFromOffset() public method

This method supports unique IDs instead of message numbers. See {@link 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 {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox Fetch a range of messages sorted by Date $set = $imap->sortFromOffset( 1, 10, "Date" ); $set can be parsed with ezcMailParser
public sortFromOffset ( integer $offset, integer $count, string $sortCriteria, boolean $reverse = false ) : ezcMailImapSet
$offset integer
$count integer
$sortCriteria string
$reverse boolean
return ezcMailImapSet

sortMessages() public method

This method supports unique IDs instead of message numbers. See {@link ezcMailImapTransportOptions} for how to enable unique IDs referencing. $messages is an array of message numbers, for example: 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox Fetch the list of messages sorted by Date $set = $imap->sortMessages( 1, 10, "Date" ); $set can be parsed with ezcMailParser
public sortMessages ( array(int) $messages, string $sortCriteria, boolean $reverse = false ) : ezcMailImapSet
$messages array(int)
$sortCriteria string
$reverse boolean
return ezcMailImapSet

status() public method

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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'Inbox' ); $imap->status( $numMessages, $sizeMessages, $recent, $unseen ); After running the above code, $numMessages, $sizeMessages, $recent and $unseen will be populated with values.
public status ( &$numMessages, &$sizeMessages, &$recent, &$unseen ) : boolean
return boolean

top() public method

This method supports unique IDs instead of message numbers. See {@link 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 {@link ezcMailParser} and {@link 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: $imap = new ezcMailImapTransport( 'imap.example.com' ); $imap->authenticate( 'username', 'password' ); $imap->selectMailbox( 'Inbox' ); $parser = new ezcMailParser(); $messages = $imap->listMessages(); foreach ( $messages as $messageNr => $size ) { $set = new ezcMailVariableSet( $imap->top( $messageNr ) ); $mail = $parser->parseMail( $set ); $mail = $mail[0]; echo "From: {$mail->from}, Subject: {$mail->subject}, Size: {$size}\n"; } For a more advanced example see the "Mail listing example" in the online documentation.
public top ( integer $msgNum, integer $chars ) : string
$msgNum integer
$chars integer
return string

Property Details

$basicFlags protected static property

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) $basicFlags
return array(string)

$connection protected property

Holds the connection to the IMAP server.
protected ezcMailTransportConnection $connection
return ezcMailTransportConnection

$currentTag protected property

Used to generate a tag for sending commands to the IMAP server.
protected string $currentTag
return string

$extendedFlags protected static property

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 static array(string) $extendedFlags
return array(string)

$selectedMailbox protected property

Holds the currently selected mailbox.
protected string $selectedMailbox
return string

$serverType protected property

Used for fixing problems with Google IMAP (see issue #14360). Possible values are {@link self::SERVER_GIMAP} or null for all other servers.
protected string $serverType
return string

$state protected property

Holds the connection state.
protected $state