XLII. IMAP, POP3 and NNTP Functions

Introduzione

These functions are not limited to the IMAP protocol, despite their name. The underlying c-client library also supports NNTP, POP3 and local mailbox access methods.

Requisiti

This extension requires the c-client library to be installed. Grab the latest version from ftp://ftp.cac.washington.edu/imap/ and compile it.

It's important that you do not copy the IMAP source files directly into the system include directory as there may be conflicts. Instead, create a new directory inside the system include directory, such as /usr/local/imap-2000b/ (location and name depend on your setup and IMAP version), and inside this new directory create additional directories named lib/ and include/. From the c-client directory from your IMAP source tree, copy all the *.h files into include/ and all the *.c files into lib/. Additionally when you compiled IMAP, a file named c-client.a was created. Also put this in the lib/ directory but rename it as libc-client.a.

Nota: To build the c-client library with SSL or/and Kerberos support read the docs supplied with the package.

Installazione

To get these functions to work, you have to compile PHP with --with-imap[=DIR], where DIR is the c-client install prefix. From our example above, you would use --with-imap=/usr/local/imap-2000b. This location depends on where you created this directory according to the description above. Windows users may include the php_imap.dll DLL in php.ini

Nota: Depending how the c-client was configured, you might also need to add --with-imap-ssl=/path/to/openssl/ and/or --with-kerberos=/path/to/kerberos into the PHP configure line.

Attenzione

Il modulo IMAP non pu� essere utilizzato in congiunzione con i moduli recode o YAZ. Poich� questi moduli condividono i medesimi simboli interni.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione � stata compilata nel PHP o se � stata caricata dinamicamente a runtime.

NIL (integer)
OP_DEBUG (integer)
OP_READONLY (integer): Open mailbox read-only
OP_ANONYMOUS (integer): Don't use or update a .newsrc for news (NNTP only)
OP_SHORTCACHE (integer)
OP_SILENT (integer)
OP_PROTOTYPE (integer)
OP_HALFOPEN (integer): For IMAP and NNTP names, open a connection but don't open a mailbox.
OP_EXPUNGE (integer)
OP_SECURE (integer)
CL_EXPUNGE (integer): silently expunge the mailbox before closing when calling imap_close()
FT_UID (integer): The parameter is a UID
FT_PEEK (integer): Do not set the \Seen flag if not already set
FT_NOT (integer)
FT_INTERNAL (integer): The return string is in internal format, will not canonicalize to CRLF.
FT_PREFETCHTEXT (integer)
ST_UID (integer): The sequence argument contains UIDs instead of sequence numbers
ST_SILENT (integer)
ST_SET (integer)
CP_UID (integer): the sequence numbers contain UIDS
CP_MOVE (integer): Delete the messages from the current mailbox after copying with imap_mail_copy()
SE_UID (integer): Return UIDs instead of sequence numbers
SE_FREE (integer)
SE_NOPREFETCH (integer): Don't prefetch searched messages
SO_FREE (integer)
SO_NOSERVER (integer)
SA_MESSAGES (integer)
SA_RECENT (integer)
SA_UNSEEN (integer)
SA_UIDNEXT (integer)
SA_UIDVALIDITY (integer)
SA_ALL (integer)
LATT_NOINFERIORS (integer): This mailbox has no "children" (there are no mailboxes below this one).
LATT_NOSELECT (integer): This is only a container, not a mailbox - you cannot open it.
LATT_MARKED (integer): This mailbox is marked. Only used by UW-IMAPD.
LATT_UNMARKED (integer): This mailbox is not marked. Only used by UW-IMAPD.
SORTDATE (integer): Sort criteria for imap_sort(): message Date
SORTARRIVAL (integer): Sort criteria for imap_sort(): arrival date
SORTFROM (integer): Sort criteria for imap_sort(): mailbox in first From address
SORTSUBJECT (integer): Sort criteria for imap_sort(): message subject
SORTTO (integer): Sort criteria for imap_sort(): mailbox in first To address
SORTCC (integer): Sort criteria for imap_sort(): mailbox in first cc address
SORTSIZE (integer): Sort criteria for imap_sort(): size of message in octets
TYPETEXT (integer)
TYPEMULTIPART (integer)
TYPEMESSAGE (integer)
TYPEAPPLICATION (integer)
TYPEAUDIO (integer)
TYPEIMAGE (integer)
TYPEVIDEO (integer)
TYPEOTHER (integer)
ENC7BIT (integer)
ENC8BIT (integer)
ENCBINARY (integer)
ENCBASE64 (integer)
ENCQUOTEDPRINTABLE (integer)
ENCOTHER (integer)

Vedere anche

This document can't go into detail on all the topics touched by the provided functions. Further information is provided by the documentation of the c-client library source (docs/internal.txt). and the following RFC documents:

RFC2821: Simple Mail Transfer Protocol (SMTP).
RFC2822: Standard for ARPA internet text messages.
RFC2060: Internet Message Access Protocol (IMAP) Version 4rev1.
RFC1939: Post Office Protocol Version 3 (POP3).
RFC977: Network News Transfer Protocol (NNTP).
RFC2076: Common Internet Message Headers.
RFC2045 , RFC2046 , RFC2047 , RFC2048 & RFC2049: Multipurpose Internet Mail Extensions (MIME).

A detailed overview is also available in the books Programming Internet Email by David Wood and Managing IMAP by Dianna Mullet & Kevin Mullet.

Sommario
imap_8bit -- Convert an 8bit string to a quoted-printable string
imap_alerts -- This function returns all IMAP alert messages (if any) that have occurred during this page request or since the alert stack was reset
imap_append -- Append a string message to a specified mailbox
imap_base64 -- Decode BASE64 encoded text
imap_binary -- Convert an 8bit string to a base64 string
imap_body -- Read the message body
imap_bodystruct -- Read the structure of a specified body section of a specific message
imap_check -- Check current mailbox
imap_clearflag_full -- Clears flags on messages
imap_close -- Close an IMAP stream
imap_createmailbox -- Create a new mailbox
imap_delete -- Mark a message for deletion from current mailbox
imap_deletemailbox -- Delete a mailbox
imap_errors -- This function returns all of the IMAP errors (if any) that have occurred during this page request or since the error stack was reset.
imap_expunge -- Delete all messages marked for deletion
imap_fetch_overview -- Read an overview of the information in the headers of the given message
imap_fetchbody -- Fetch a particular section of the body of the message
imap_fetchheader -- Returns header for a message
imap_fetchstructure -- Read the structure of a particular message
imap_get_quota -- Retrieve the quota level settings, and usage statics per mailbox
imap_get_quotaroot -- Retrieve the quota settings per user
imap_getacl -- Gets the ACL for a given mailbox
imap_getmailboxes -- Read the list of mailboxes, returning detailed information on each one
imap_getsubscribed -- List all the subscribed mailboxes
imap_header -- Alias of imap_headerinfo()
imap_headerinfo -- Read the header of the message
imap_headers -- Returns headers for all messages in a mailbox
imap_last_error -- This function returns the last IMAP error (if any) that occurred during this page request
imap_list -- Read the list of mailboxes
imap_listmailbox -- Alias of imap_list()
imap_listscan -- Read the list of mailboxes, takes a string to search for in the text of the mailbox
imap_listsubscribed -- Alias of imap_lsub()
imap_lsub -- List all the subscribed mailboxes
imap_mail_compose -- Create a MIME message based on given envelope and body sections
imap_mail_copy -- Copy specified messages to a mailbox
imap_mail_move -- Move specified messages to a mailbox
imap_mail -- Send an email message
imap_mailboxmsginfo -- Get information about the current mailbox
imap_mime_header_decode -- Decode MIME header elements
imap_msgno -- This function returns the message sequence number for the given UID
imap_num_msg -- Gives the number of messages in the current mailbox
imap_num_recent -- Gives the number of recent messages in current mailbox
imap_open -- Open an IMAP stream to a mailbox
imap_ping -- Check if the IMAP stream is still active
imap_qprint -- Convert a quoted-printable string to an 8 bit string
imap_renamemailbox -- Rename an old mailbox to new mailbox
imap_reopen -- Reopen IMAP stream to new mailbox
imap_rfc822_parse_adrlist -- Parses an address string
imap_rfc822_parse_headers -- Parse mail headers from a string
imap_rfc822_write_address -- Returns a properly formatted email address given the mailbox, host, and personal info.
imap_scanmailbox -- Alias of imap_listscan()
imap_search -- This function returns an array of messages matching the given search criteria
imap_set_quota -- Sets a quota for a given mailbox
imap_setacl -- Sets the ACL for a giving mailbox
imap_setflag_full -- Sets flags on messages
imap_sort -- Sort an array of message headers
imap_status -- This function returns status information on a mailbox other than the current one
imap_subscribe -- Subscribe to a mailbox
imap_thread -- Return threaded by REFERENCES tree
imap_timeout -- Set or fetch imap timeout
imap_uid -- This function returns the UID for the given message sequence number
imap_undelete -- Unmark the message which is marked deleted
imap_unsubscribe -- Unsubscribe from a mailbox
imap_utf7_decode -- Decodes a modified UTF-7 encoded string.
imap_utf7_encode -- Converts ISO-8859-1 string to modified UTF-7 text.
imap_utf8 -- Converts MIME-encoded text to UTF-8

add a note User Contributed Notes
IMAP, POP3 and NNTP Functions

Tomas V.V.Cox
11-May-2004 12:15


For compiling this extension without compiling imap from sources I did (this was mandrake):



Install the following rpms:

imap

imap-devel

openssl

openssl-devel

krb5

krb5-devel

pam

pam-devel



Do the trick:

# mkdir /usr/include/imap/lib

# cp /usr/lib/libc-client-PHP4.a /usr/include/imap/lib/libc-client.a



And the configure line:

./configure <options> --with-imap=/usr/include/imap --with-imap-ssl



(don't forget --enable-pear ;)

sysadmin at grmtech dot com
27-Mar-2004 10:01


The manual mentions:

"From the c-client directory from your IMAP source tree, copy all the *.h files into include/ and all the *.c files into lib/. Additionally when you compiled IMAP, a file named c-client.a was created. Also put this in the lib/ directory but rename it as libc-client.a. 

"



A. Please do not copy rather make symbolic links like this:

ln -s c-client include

ln -s c-client lib



B. You do not need to copy c-client.a to libc-client.a.

The make command used to compile the imap-2002e source code creates the symbolic link from c-client.a to libc-client.a



The imap client version used for the above two points is:

1. imap-2002e



my 2 cents,



sysadmin

http://www.grmtech.com

peder at godvik dot no
09-Mar-2004 02:24


Additionally to Mauricio's procedure; You must check the Makefile to find the correct system type that you are compiling on. Mauricio's example assumes you are using Linux. -Check the README for imap-xxxx for further details.

Fjor
14-Feb-2004 11:50


Additionally to Mauricio's procedure, I had to make a symlink to the c-client library this way:



cd imap-xxxx/c-client

ln -s c-client.a libc-client.a



(Tested with imap-200e)



Fjor (GDL/Mexico)

dev at puertocity dot com
26-Nov-2003 02:38


A tip for imap support installation:



With SSL support:

------------------

tar -zxf imap-xxxxx.tar.Z

cd imap-xxxxx

make slx

ln -sf c-client include

ln -sf c-client lib

cd ..

tar -jxf php-4.3.x.tar.bz2

cd php-4.3.x

./configure --with-imap=../imap-xxxxx --with-imap-ssl=/path-to-openssl



With out SSL support:

---------------------

tar -zxf imap-xxxxx.tar.Z

cd imap-xxxxx

make slx SSLTYPE=none

ln -sf c-client include

ln -sf c-client lib

cd ..

tar -jxf php-4.3.x.tar.bz2

cd php-4.3.x

./configure --with-imap=../imap-xxxxx



Good Luck

Mauricio

millz at incogen dot com
10-Oct-2003 10:19


I experienced a problem when adding IMAP support into PHP.  The php configure script would die when trying to see if "IMAP Works..." and the config.log would complain about libc-client.a references.  

It was similar to the problem reported here: 

http://lists.horde.org/archives/imp/Week-of-Mon-20030915/034692.html  



I resolved it by compiling IMAP like this (replace <ARCH> with the proper OS type for your system, get that from the top of the Makefile):



make <ARCH> SSLTYPE=none



That turned off the SSL support in the IMAP files and seemed to resolve my php compile problem.



BTW, I also followed the directions about making a new /usr/local/imap... directory that are mentioned at the top of the page.

k3nny at squidart dot co dot za
31-Jul-2003 11:02


After having numerous problems compiling PHP with IMAP support, both PHP problems and IMAP problems I found this simple solution to the problem, which I've tried with several versions of IMAP and all worked perfectly!



tar -zxf imap-xxxxx.tar.Z

cd imap-xxxxx

make slx

ln -sf c-client include

ln -sf c-client lib

cd ..

tar -jxf php-4.3.x.tar.bz2

cd php-4.3.x

./configure --with-imap=../imap-xxxxx



It worked everytime for me, hope it does for you!



Kenneth

designer at bs-dee dot org
09-Mar-2003 10:27


The only c-client that has worked 100% with php is



ftp://ftp.cac.washington.edu/imap/old/imap-2001.FINAL.tar.Z



DO NOT DOWNLOAD 2002 B its BUGGY!

keeper at odi dot com dot br
01-Mar-2003 06:37


For those working with mail talke a look ate the pear class

Mime decode:



http://pear.php.net/manual/en/core.mail.mimedecode.php



Dotrinador

naveed at php dot net
12-Jan-2003 01:49


Beware!

If you are trying to make a connection with POP3 mailbox,then some of IMAP functions will not work correctly as you might expecting .This is because the difference of workings in POP3 and IMAP protocols.

These functions work correctly for IMAP mailboxes but some of the fnctions will return nothing, when connected to a POP3 mailbox.(even no error message).

duckel at electroporn dot de
22-May-2002 05:16


please don't copy the .h files in the system include directory! the unix.h file from the washington.edu c-client conflicts with another file called unix.h

make a dir called "imap" in either /usr/include or /usr/local/include or whatever you wish, copy the header files there and the .a file prefix'ish in /usr/lib or /usr/local/lib or whatever you used for the include files.

then tell configure with --with-imap=/usr the "prefix" of your installation. 

then works without problem ;)

try at linuxplanet dot nu
16-Apr-2002 05:30


there are a nice pop3/imap Tutorial @ devhed



http://www.devshed.com/Server_Side/PHP/PHPMail/PHPMail1/page1.html



have fun

netshadow at madpoets dot org
03-Nov-2001 07:42


I just found something a bit bizarre.  I was having problems with the pages taking too long to load (15-20sec) when they opened an imap connection.  I was pulling my hair out trying to figure out what was wrong.





Turns out it was quite simple.  I was letting it default to 143 for the port.  When i specified the port number (i.e. {localhost:143} rather than {localhost} )  It reduced page load time to a few seconds.

raoul at runtheotherway dot com
22-Oct-2001 01:11


I have found the order in which you connect to you POP server with IMAP 2000 and your database with PostgreSQL 7.1.2 can cause problems.





Make sure that you connect first to your POP server then get your db connection. This will prevent you from getting an invalid stream from imap_open().

add a note


	downloads \| documentation \| faq \| getting help \| mailing lists \| reporting bugs \| php.net sites \| links \| my php.net

search for in the