IMAP Functions

To get these functions to work, you have to compile PHP with --with-imap. That requires the c-client library to be installed. Grab it from ftp://ftp.cac.washington.edu/imap/imap-4.2.tar.Z and compile it. Then copy c-client/c-client.a to /usr/local/lib or some other directory on your link path and copy c- client/rfc822.h, mail.h and linkage.h to /usr/local/include or some other directory in your include path.

IMAP Functions

imap_append

Name

imap_append — Append a string message to a specified mailbox

Description

int imap_append(int imap_stream, string mbox, string message, stringflags);

Returns true on sucess, false on error.

imap_append() function appends a string message to the specified mailbox mbox. If the optional flags is specified, writes the flags to that mailbox also.

imap_base64

Name

imap_base64 — Decode BASE64 encoded text

Description

string imap_base64(string text);

imap_base64() function decodes a BASE64 encoded text. The decoded message is returned as a string.

imap_body

Name

imap_body — Read the message body

Description

string imap_body(int imap_stream, int msg_number, int flags);

imap_body() returns the body of the message, numbered msg_number in the current mailbox. The optional flags are a bit mask with one or more of the following:

  • FT_UID - The msgno is a UID

  • FT_PEEK - Do not set the \Seen flag if not already set

  • FT_INTERNAL - The return string is in internal format, will not

    canonicalize to CRLF.

imap_check

Name

imap_check — Check current mailbox

Description

array imap_check(int imap_stream);

Returns information about the current mailbox. Returns FALSE on failure.

The imap_check() function checks the current mailbox status on the server and returns the information in an object with following properties.

Date : date of the message Driver : driver

Mailbox : name of the mailbox Nmsgs : number of messages Recent : number of recent messages

imap_close

Name

imap_close — Close an IMAP stream

Description

int imap_close(int imap_stream, int flags);

Close the imap stream. Takes an optional flag CL_EXPUNGE, which will silently expunge the mailbox before closing.

imap_createmailbox

Name

imap_createmailbox — Create a new mailbox

Description

int imap_createmailbox(int imap_stream, string mbox);

Returns true on success and false on error. imap_createmailbox() creates a new mailbox specified by mbox.

imap_delete

Name

imap_delete — Mark a messge for deletion from current mailbox

Description

int imap_delete(int imap_stream, int msg_number);

Returns true.

imap_delete() function marks message pointed by msg_number for deletion. Actual deletion of the messages is done by imap_expunge .

imap_deletemailbox

Name

imap_deletemailbox — Delete a mailbox

Description

int imap_deletemailbox(int imap_stream, string mbox);

Returns true on success and false on error. imap_deletemailbox() deletes the specified mailbox.

imap_expunge

Name

imap_expunge — Delete all messages marked for deletion

Description

int imap_expunge(int imap_stream);

Returns true.

imap_expunge() deletes all the messages marked for deletion by imap_delete.

imap_fetchbody

Name

imap_fetchbody — Fetch a particular section of the body of the message

Description

string imap_fetchbody(int imap_stream, int msg_number, int part_number, flags

flags);

This function causes a fetch of a particular section of the body of the specified messages as a text string and returns that text string. The section specification is a string of integers delimited by period which index into a body part list as per the IMAP4 specification. Body parts are not decoded by this function.

The options for imap_fetchbody are a bitmask with one or more of the following

  • FT_UID - The msgono is a UID

  • FT_PEEK - Do not set the \Seen flag if not already set

  • FT_UID - The return string is in "internal" format, without any

    attempt to canonicalize CRLF

imap_fetchstructure

Name

imap_fetchstructure — Read the structure of a particular message

Description

array imap_fetchstructure(int imap_stream, int msg_number, int flags);

This function causes a fetch of all the structured information for the given msg_number. The returned value is an object with following elements.

type, encoding, ifsubtype, subtype, ifdescription, description, ifid, id, lines, bytes, ifparameters

It also returns an array of objects called parameters[]. This object has following properties. attribute, value

In case of multipart, it also returns an array of objects of all the properties, called parts[].

imap_header

Name

imap_header — Read the header of the message

Description

object imap_header(int imap_stream, int msg_number, int fromlength, int

subjectlength, int defaulthost);

This function returns an object of various header elements

remail,date,Date,subject,Subject,in_reply_to,message_id,newsgroups, followup_to,references

toaddress (full to: line, up to 1024 characters)

to[] (returns an array of objects from the To line, containing:) personal

adl mailbox host

fromaddress (full from: line, up to 1024 characters)

from[] (returns an array of objects from the From line, containing:) personal

adl mailbox host

ccaddress (full cc: line, up to 1024 characters)

cc[] (returns an array of objects from the Cc line, containing:) personal

adl mailbox host

bccaddress (full bcc line, up to 1024 characters)

bcc[] (returns an array of objects from the Bcc line, containing:) personal

adl mailbox host

reply_toaddress (full reply_to: line, up to 1024 characters)

reply_to[] (returns an array of objects from the Reply_to line, containing:) personal

adl mailbox host

senderaddress (full sender: line, up to 1024 characters)

sender[] (returns an array of objects from the sender line, containing:) personal

adl mailbox host

return_path (full return-path: line, up to 1024 characters)

return_path[] (returns an array of objects from the return_path line, containing:) personal

adl mailbox host

udate ( mail message date in unix time)

fetchfrom (from line formatted to fit fromlength characters) fetchsubject (subject line formatted to fit subjectlength characters)

imap_headers

Name

imap_headers — Returns headers for all messages in a mailbox

Description

array imap_headers(int imap_stream);

Returns an array of string formatted with header info. One element per mail message.

imap_listmailbox

Name

imap_listmailbox — Read the list of mailboxes

Description

array imap_listmailbox(int imap_stream, string ref, string pat);

Returns an array containing the names of the mailboxes.

imap_listsubscribed

Name

imap_listsubscribed — List all the subscribed mailboxes

Description

array imap_listsubscribed(int imap_stream, string ref, string pattern);

Returns an array of all the mailboxes that you have subscribed. The ref and pattern arguments specify the base location to search from and the pattern the mailbox name must match.

imap_mail_copy

Name

imap_mail_copy — Copy specified messages to a mailbox

Description

int imap_mail_copy(int imap_stream, string msglist, string mbox, int flags);

Returns true on success and false on error.

Copies mail messages specified by msglist to specified mailbox. msglist is a range not just message numbers.

flags is a bitmask of one or more of

  • CP_UID - the sequence numbers contain UIDS

  • CP_MOVE - Delete the messages from the current mailbox after

    copying

imap_mail_move

Name

imap_mail_move — Move specified messages to a mailbox

Description

int imap_mail_move(int imap_stream, string msglist, string mbox);

Returns true on success and false on error.

Moves mail messages specified by msglist to specified mailbox. msglist is a range not just message numbers.

imap_num_msg

Name

imap_num_msg — Gives the number of messages in the current mailbox

Description

int imap_num_msg(void);

Return the number of messages in the current mailbox.

imap_num_recent

Name

imap_num_recent — Gives the number of recent messages in current mailbox

Description

int imap_num_recent(int imap_stream);

Returns the number of recent messages in the current mailbox.

imap_open

Name

imap_open — Open an IMAP stream to a mailbox

Description

int imap_open(string mailbox, string username, string password, int flags);

Returns an IMAP stream on success and false on error. This function can also be used to open streams to POP3 and NNTP servers. To connect to an IMAP server running on port 143 on the local machine, do the following:

$mbox = imap_open("{localhost:143}INBOX","user_id","password");

To connect to a POP3 server on port 110 on the local server, use:

$mbox = imap_open("{localhost/pop3:110}INBOX","user_id","password");

To connect to an NNTP server on port 119 on the local server, use:

$nntp = imap_open("{localhost/nntp:119}comp.test","","");

To connect to a remote server replace "localhost" with the name or the IP address of the server you want to connect to.

The options are a bit mask with noe or more of the following:

  • OP_READONLY - Open mailbox read-only

  • OP_ANONYMOUS - Dont use or update a .newsrc for news

  • OP_HALFOPEN - For IMAP and NNTP names, open a connection but dont

    open a mailbox

  • CL_EXPUNGE - Expunge mailbox automatically upon mailbox close

imap_ping

Name

imap_ping — Check if the IMAP stream is still active

Description

int imap_ping(int imap_stream);

Returns true if the stream is still alive, false otherwise.

imap_ping() function pings the stream to see it is still active. It may discover new mail; this is the preferred method for a periodic "new mail check" as well as a "keep alive" for servers which have inactivity timeout.

imap_renamemailbox

Name

imap_renamemailbox — Rename an old mailbox to new mailbox

Description

int imap_renamemailbox(int imap_stream, string old_mbox, string new_mbox);

Returns true on success and false on error.

This function renames on old mailbox to new mailbox.

imap_reopen

Name

imap_reopen — Reopen IMAP stream to new mailbox

Description

int imap_reopen(string imap_stream, string mailbox, string [flags]);

Returns true on success and false on error.

This function reopens the specified stream to new mailbox. the options are a bit mask with noe or more of the following:

  • OP_READONLY - Open mailbox read-only

  • OP_ANONYMOUS - Dont use or update a .newsrc for news

  • OP_HALFOPEN - For IMAP and NNTP names, open a connection but dont

    open a mailbox

  • CL_EXPUNGE - Expunge mailbox automatically upon mailbox close

imap_subscribe

Name

imap_subscribe — Subscribe to a mailbox

Description

int imap_subscribe(int imap_stream, string mbox);

Returns true on success and false on error. Subscribe to a new mailbox.

imap_undelete

Name

imap_undelete — Unmark the message which is marked deleted

Description

int imap_undelete(int imap_stream, int msg_number);

Returns true on success and false on error.

This function removes the deletion flag for a specified message, which is set by imap_delete.

imap_unsubscribe

Name

imap_unsubscribe — Unsubscribe from a mailbox

Description

int imap_unsubscribe(int imap_stream, string mbox);

Returns true on success and false on error. Unsubscribe from a specified mailbox.

imap_qprint

Name

imap_qprint — Convert a quoted-printable string to an 8 bit string

Description

string imap_qprint(string string);

Returns an 8 bit (binary) string

Convert a quoted-printable string to an 8 bit string

imap_8bit

Name

imap_8bit — Convert an 8bit string to a quoted-printable string.

Description

string imap_8bit(string string);

Returns a quoted-printable string

Convert an 8bit string to a quoted-printable string.

imap_binary

Name

imap_binary — Convert an 8bit string to a base64 string.

Description

string imap_binary(string string);

Returns a base64 string

Convert an 8bit string to a base64 string.

imap_scanmailbox

Name

imap_scanmailbox — Read the list of mailboxes, takes a string to search for in the text of the mailbox

Description

array imap_scanmailbox(int imap_stream, string string);

Returns an array containing the names of the mailboxes that have that string in the text of the mailbox.

imap_mailboxmsginfo

Name

imap_mailboxmsginfo — Mailboxmsginfo current mailbox

Description

array imap_mailboxmsginfo(int imap_stream);

Returns information about the current mailbox. Returns FALSE on failure.

The imap_mailboxmsginfo() function checks the current mailbox status on the server and returns the information in an object with following properties.

Date : date of the message Driver : driver

Mailbox : name of the mailbox Nmsgs : number of messages Recent : number of recent messages

Unread : number of unread messages Size : mailbox size

imap_rfc822_write_address

Name

imap_rfc822_write_address — Returns a properly formatted email address given the mailbox, host, and personal info.

Description

string imap_rfc822_write_address(string mailbox, string host, string

personal);

Returns a properly formatted email address given the mailbox, host, and personal info.

imap_rfc822_parse_adrlist

Name

imap_rfc822_parse_adrlist — Parses an address string

Description

string imap_rfc822_parse_adrlist(string address, string default_host);

This function parses the address tring and for each address, returns an array of objects. The 4 objects are: mailbox - the mailbox name (username) host - the host name personal - the personal name adl - at domain source route

imap_setflag_full

Name

imap_setflag_full — Sets flags on messages

Description

string imap_setflag_full(int stream, string sequence, string flag, string

options);

This function causes a store to add the specified flag to the flags set for the messages in the specified sequence.

The options are a bit mask with one or more of the following: ST_UID The sequence argument contains UIDs instead of sequence numbers

imap_clearflag_full

Name

imap_clearflag_full — Clears flags on messages

Description

string imap_clearflag_full(int stream, string sequence, string flag, string

options);

This function causes a store to delete the specified flag to the flags set for the messages in the specified sequence.

The options are a bit mask with one or more of the following: ST_UID The sequence argument contains UIDs instead of sequence numbers

imap_sort

Name

imap_sort —

Description

string imap_sort(int stream, int criteria, int reverse, int options);

Returns an array of message numbers sorted by the given parameters Rev is 1 for reverse-sorting.

Criteria can be one (and only one) of the following: SORTDATE message Date SORTARRIVAL arrival date SORTFROM mailbox in first From address SORTSUBJECT message Subject SORTTO mailbox in first To address SORTCC mailbox in first cc address SORTSIZE size of message in octets

The flags are a bitmask of one or more of the following: SE_UID Return UIDs instead of sequence numbers SE_NOPREFETCH Don't prefetch searched messages.

imap_fetchheader

Name

imap_fetchheader — Returns header for a message

Description

stringimap_fetchheader(int imap_stream, int msgno, int flags);

This function causes a fetch of the complete, unfiltered RFC 822 format header of the specified message as a text string and returns that text string.

The options are: FT_UID The msgno argument is a UID FT_INTERNAL The return string is in "internal" format, without any attempt to canonicalize to CRLF newlines FT_PREFETCHTEXT The RFC822.TEXT should be pre-fetched at the same time. This avoids an extra RTT on an IMAP connection if a full message text is desired (e.g. in a "save to local file" operation)

imap_uid

Name

imap_uid — This function returns the UID for the given message sequence number.

Description

string imap_uid(string mailbox, int msgno);

This function returns the UID for the given message sequence number