PHP IMAP Notes
Previously I wrote about using PHP’s IMAP functions. Now I’d like to provide a more detailed, and less wordy, overview of some of the more common IMAP functions. Enjoy!
imap_open opens a connection to the specified mailbox. It takes up to 5 parameters:
Mailbox:
This is the address and port of the mail server you are connecting to. Typically this parameter will look like one of the following:
- mail.domain.net:143
- localhost
- 127.0.0.1:110
The port number is optional, but it is much more efficient if one is provided. The default IMAP port is 143 and POP3 is 110
Username
Typically the email address you are trying to access mail from, but not necessarily.
Password
The password corresponding to the username
Options
The options, or flags, modify your connection stream. The default is /imap but I’ve found that /imap/novalidate-cert is often necessary. If you are trying to connect using POP3 you’ll have to set this to /pop3.
Retries
The number of connection retries. If your mail server limits the number of connection attempts it is important that this value be set to 0, otherwise you may lock yourself out of your account.
Don’t forget to close the connection stream using imap_close($mailbox) where mailbox is the connection stream you opened with imap_open.
imap_fetch_overview returns an overview of one or more emails. This function Always returns an array, even if only a single message is specified.
imap_stream
A connection stream created with imap_open
message id or sequence
imap_fetch_overview takes either a single message id, or a sequence formatted as x:y (ex. 1:5 will return message 1 through 5 inclusive).
Options
This parameter must be set to FT_UID if the sequence parameter is a sequence of UIDs rather than message ids. Using UIDs is often preferable to message ids because message ids are not guaranteed to remain the same. Some functions however, require that you use message ids.
This function returns a lot of useful information about a particular email. Read the function documentation for a full list. While this function does return to and from headers, it does not return the cc and bcc headers. You will have to use imap_headerinfo to obtain these. Note that imap_headerinfo cannot take a UID as a message parameter, you’ll have to use message ids.
This function returns information about the specified mailbox. Most likely if you are using this function, you are using it to obtain the number of messages in the mailbox.
Setting and Unsetting Message Flags
Each message in a mailbox has a set of flags, probably the most interesting one is the SEEN flag. The seen flag indicates if the email has been opened or read. Usually this flag is set when using the imap_body function to obtain the body of a message. If you want to mark an email as seen you can use imap_setflag_full. To set the email as unread, use imap_clearflag_full to unset the SEEN flag.
Deleting Emails
The imap_delete flags an email for deletion. This function is really a shortcut for calling imap_setflag_full with the deleted flag. Likewise, imap_undelete is a shortcut for calling imap_clearflag_full with the deleted flag. Note that these functions do not actually delete the message. In order to delete the message you must either call imap_expunge or imap_close with the optional flag CL_EXPUNGE.
Searching the mailbox
The imap_search function is great for emails that meet a certain criteria. Personally I use this function mostly to find unopened emails.
[...] For a concise overview of some of the more common functions and a few tips read PHP IMAP Notes. [...]