Ref/imap-Phpdoc专题

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.

imap_8bit

Convert an 8bit string to a quoted-printable string

说明

string imap_8bit ( string $string )

Convert an 8bit string to a quoted-printable string (according to » RFC2045, section 6.7).

参数

string
The 8bit string to convert

返回值

Returns a quoted-printable string.

参见

imap_qprint

imap_alerts

Returns all IMAP alert messages that have occurred

说明

array imap_alerts ( void )

Returns all of the IMAP alert messages generated since the last imap_alerts call, or the beginning of the page.

When imap_alerts is called, the alert stack is subsequently cleared. The IMAP specification requires that these messages be passed to the user.

返回值

Returns an array of all of the IMAP alert messages generated or false if no alert messages are available.

参见

imap_errors

imap_append

Append a string message to a specified mailbox

说明

bool imap_append ( resource $imap_stream , string $mailbox , string $message [, string $options = null [, string $internal_date = null ]] )

Appends a string message to the specified mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

message
The message to be append, as a string

When talking to the Cyrus IMAP server, you must use "\r\n" as your end-of-line terminator instead of "\n" or the operation will fail

options
If provided, the options will also be written to the mailbox

internal_date
If this parameter is set, it will set the INTERNALDATE on the appended message. The parameter should be a date string that conforms to the rfc2060 specifications for a date_time value.

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 imap_append example

<?php
$stream = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

$check = imap_check($stream);
echo "Msg Count before append: ". $check->Nmsgs . "\n";

imap_append($stream, "{imap.example.org}INBOX.Drafts"
                   , "From: [email protected]\r\n"
                   . "To: [email protected]\r\n"
                   . "Subject: test\r\n"
                   . "\r\n"
                   . "this is a test message, please ignore\r\n"
                   );

$check = imap_check($stream);
echo "Msg Count after append : ". $check->Nmsgs . "\n";

imap_close($stream);
?>

imap_base64

Decode BASE64 encoded text

说明

string imap_base64 ( string $text )

Decodes the given BASE-64 encoded text.

参数

text
The encoded text

返回值

Returns the decoded message as a string.

参见

imap_binary
base64_encode
base64_decode
» RFC2045, Section 6.8

imap_binary

Convert an 8bit string to a base64 string

说明

string imap_binary ( string $string )

Convert an 8bit string to a base64 string according to » RFC2045, Section 6.8.

参数

string
The 8bit string

返回值

Returns a base64 encoded string.

参见

imap_base64

imap_body

Read the message body

说明

string imap_body ( resource $imap_stream , int $msg_number [, int $options = 0 ] )

imap_body returns the body of the message, numbered msg_number in the current mailbox.

imap_body will only return a verbatim copy of the message body. To extract single parts of a multipart MIME-encoded message you have to use imap_fetchstructure to analyze its structure and imap_fetchbody to extract a copy of a single body component.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

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

FT_UID - The msg_number 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.

返回值

Returns the body of the specified message, as a string.

imap_bodystruct

Read the structure of a specified body section of a specific message

说明

object imap_bodystruct ( resource $imap_stream , int $msg_number , string $section )

Read the structure of a specified body section of a specific message.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

section
The body section to read

返回值

Returns the information in an object, for a detailed description of the object structure and properties see imap_fetchstructure.

参见

imap_fetchstructure

imap_check

Check current mailbox

说明

object imap_check ( resource $imap_stream )

Checks information about the current mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

返回值

Returns the information in an object with following properties:

Date - current system time formatted according to » RFC2822
Driver - protocol used to access this mailbox: POP3, IMAP, NNTP
Mailbox - the mailbox name
Nmsgs - number of messages in the mailbox
Recent - number of recent messages in the mailbox

Returns false on failure.

范例

示例 #1 imap_check example

<?php

$imap_obj = imap_check($imap_stream);
var_dump($imap_obj);

?>

以上例程的输出类似于：

object(stdClass)(5) {
  ["Date"]=>
  string(37) "Wed, 10 Dec 2003 17:56:54 +0100 (CET)"
  ["Driver"]=>
  string(4) "imap"
  ["Mailbox"]=>
  string(54)
  "{www.example.com:143/imap/user="[email protected]"}INBOX"
  ["Nmsgs"]=>
  int(1)
  ["Recent"]=>
  int(0)
}

imap_clearflag_full

Clears flags on messages

说明

bool imap_clearflag_full ( resource $imap_stream , string $sequence , string $flag [, int $options = 0 ] )

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

参数

imap_stream
由 imap_open 返回的 IMAP 流。

sequence
A sequence of message numbers. You can enumerate desired messages with the X,Y syntax, or retrieve all messages within an interval with the X:Y syntax

flag
The flags which you can unset are "\\Seen", "\\Answered", "\\Flagged", "\\Deleted", and "\\Draft" (as defined by » RFC2060)

options
options are a bit mask and may contain the single option:

ST_UID - The sequence argument contains UIDs instead of sequence numbers

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_setflag_full

imap_close

Close an IMAP stream

说明

bool imap_close ( resource $imap_stream [, int $flag = 0 ] )

Closes the imap stream.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

flag
If set to CL_EXPUNGE, the function will silently expunge the mailbox before closing, removing all messages marked for deletion. You can achieve the same thing by using imap_expunge

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_open

imap_create

别名 imap_createmailbox

说明

此函数是该函数的别名： imap_createmailbox.

imap_createmailbox

Create a new mailbox

说明

bool imap_createmailbox ( resource $imap_stream , string $mailbox )

Creates a new mailbox specified by mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information. Names containing international characters should be encoded by imap_utf7_encode

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 imap_createmailbox example

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
     or die("can't connect: " . imap_last_error());

$name1 = "phpnewbox";
$name2 = imap_utf7_encode("phpnewböx"); // phpnewb&w7Y-x

$newname = $name1;

echo "Newname will be '$name1'<br />\n";

// we will now create a new mailbox "phptestbox" in your inbox folder,
// check its status after creation and finally remove it to restore
// your inbox to its initial state

if (@imap_createmailbox($mbox, imap_utf7_encode("{imap.example.org}INBOX.$newname"))) {
    $status = @imap_status($mbox, "{imap.example.org}INBOX.$newname", SA_ALL);
    if ($status) {
        echo "your new mailbox '$name1' has the following status:<br />\n";
        echo "Messages:   " . $status->messages    . "<br />\n";
        echo "Recent:     " . $status->recent      . "<br />\n";
        echo "Unseen:     " . $status->unseen      . "<br />\n";
        echo "UIDnext:    " . $status->uidnext     . "<br />\n";
        echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";

        if (imap_renamemailbox($mbox, "{imap.example.org}INBOX.$newname", "{imap.example.org}INBOX.$name2")) {
            echo "renamed new mailbox from '$name1' to '$name2'<br />\n";
            $newname = $name2;
        } else {
            echo "imap_renamemailbox on new mailbox failed: " . imap_last_error() . "<br />\n";
        }
    } else {
        echo "imap_status on new mailbox failed: " . imap_last_error() . "<br />\n";
    }

    if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
        echo "new mailbox removed to restore initial state<br />\n";
    } else {
        echo "imap_deletemailbox on new mailbox failed: " . implode("<br />\n", imap_errors()) . "<br />\n";
    }

} else {
    echo "could not create new mailbox: " . implode("<br />\n", imap_errors()) . "<br />\n";
}

imap_close($mbox);
?>

参见

imap_renamemailbox
imap_deletemailbox

imap_delete

Mark a message for deletion from current mailbox

说明

bool imap_delete ( resource $imap_stream , int $msg_number [, int $options = 0 ] )

Marks messages listed in msg_number for deletion. Messages marked for deletion will stay in the mailbox until either imap_expunge is called or imap_close is called with the optional parameter CL_EXPUNGE.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

options
You can set the FT_UID which tells the function to treat the msg_number argument as a UID.

返回值

Returns true.

范例

示例 #1 imap_delete example

<?php

$mbox = imap_open("{imap.example.org}INBOX", "username", "password")
    or die("Can't connect: " . imap_last_error());

$check = imap_mailboxmsginfo($mbox);
echo "Messages before delete: " . $check->Nmsgs . "<br />\n";

imap_delete($mbox, 1);

$check = imap_mailboxmsginfo($mbox);
echo "Messages after  delete: " . $check->Nmsgs . "<br />\n";

imap_expunge($mbox);

$check = imap_mailboxmsginfo($mbox);
echo "Messages after expunge: " . $check->Nmsgs . "<br />\n";

imap_close($mbox);
?>

注释

Note:

IMAP mailboxes may not have their message flags saved between connections, so imap_expunge should be called during the same connection in order to guarantee that messages marked for deletion will actually be purged.

参见

imap_undelete
imap_expunge
imap_close

imap_deletemailbox

Delete a mailbox

说明

bool imap_deletemailbox ( resource $imap_stream , string $mailbox )

Deletes the specified mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_createmailbox
imap_renamemailbox
imap_open for the format of mbox

imap_errors

Returns all of the IMAP errors that have occurred

说明

array imap_errors ( void )

Gets all of the IMAP errors (if any) that have occurred during this page request or since the error stack was reset.

When imap_errors is called, the error stack is subsequently cleared.

返回值

This function returns an array of all of the IMAP error messages generated since the last imap_errors call, or the beginning of the page. Returns false if no error messages are available.

参见

imap_last_error
imap_alerts

imap_expunge

Delete all messages marked for deletion

说明

bool imap_expunge ( resource $imap_stream )

Deletes all the messages marked for deletion by imap_delete, imap_mail_move, or imap_setflag_full.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

返回值

Returns true.

imap_fetch_overview

Read an overview of the information in the headers of the given message

说明

array imap_fetch_overview ( resource $imap_stream , string $sequence [, int $options = 0 ] )

This function fetches mail headers for the given sequence and returns an overview of their contents.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

sequence
A message sequence description. You can enumerate desired messages with the X,Y syntax, or retrieve all messages within an interval with the X:Y syntax

options
sequence will contain a sequence of message indices or UIDs, if this parameter is set to FT_UID.

返回值

Returns an array of objects describing one message header each. The object will only define a property if it exists. The possible properties are:

subject - the messages subject
from - who sent it
to - recipient
date - when was it sent
message_id - Message-ID
references - is a reference to this message id
in_reply_to - is a reply to this message id
size - size in bytes
uid - UID the message has in the mailbox
msgno - message sequence number in the mailbox
recent - this message is flagged as recent
flagged - this message is flagged
answered - this message is flagged as answered
deleted - this message is flagged for deletion
seen - this message is flagged as already read
draft - this message is flagged as being a draft
udate - the UNIX timestamp of the arrival date

范例

示例 #1 imap_fetch_overview example

<?php
$mbox = imap_open("{imap.example.org:143}INBOX", "username", "password")
     or die("can't connect: " . imap_last_error());

$MC = imap_check($mbox);

// Fetch an overview for all messages in INBOX
$result = imap_fetch_overview($mbox,"1:{$MC->Nmsgs}",0);
foreach ($result as $overview) {
    echo "#{$overview->msgno} ({$overview->date}) - From: {$overview->from}
    {$overview->subject}\n";
}
imap_close($mbox);
?>

参见

imap_fetchheader

imap_fetchbody

Fetch a particular section of the body of the message

说明

string imap_fetchbody ( resource $imap_stream , int $msg_number , string $section [, int $options = 0 ] )

Fetch of a particular section of the body of the specified messages. Body parts are not decoded by this function.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

section
The part number. It is a string of integers delimited by period which index into a body part list as per the IMAP4 specification

options
A bitmask with one or more of the following:

FT_UID - The msg_number 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.

返回值

Returns a particular section of the body of the specified messages as a text string.

参见

imap_savebody
imap_fetchstructure

imap_fetchheader

Returns header for a message

说明

string imap_fetchheader ( resource $imap_stream , int $msg_number [, int $options = 0 ] )

This function causes a fetch of the complete, unfiltered » RFC2822 format header of the specified message.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

options
The possible 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)

返回值

Returns the header of the specified message as a text string.

参见

imap_fetch_overview

imap_fetchmime

Fetch MIME headers for a particular section of the message

说明

string imap_fetchmime ( resource $imap_stream , int $msg_number , string $section [, int $options = 0 ] )

Fetch the MIME headers of a particular section of the body of the specified messages.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

section
The part number. It is a string of integers delimited by period which index into a body part list as per the IMAP4 specification

options
A bitmask with one or more of the following:

FT_UID - The msg_number 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.

返回值

Returns the MIME headers of a particular section of the body of the specified messages as a text string.

参见

imap_fetchbody
imap_fetchstructure
imap_fetchheader

imap_fetchstructure

Read the structure of a particular message

说明

objectfalse imap_fetchstructure ( resource $imap_stream , int $msg_number [, int $options = 0 ] )

Fetches all the structured information for a given message.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

options
This optional parameter only has a single option, FT_UID, which tells the function to treat the msg_number argument as a UID.

返回值

Returns an object with properties listed in the table below, 或者在失败时返回 false.


type	Primary body type
encoding	Body transfer encoding
ifsubtype	`true` if there is a subtype string
subtype	MIME subtype
ifdescription	`true` if there is a description string
description	Content description string
ifid	`true` if there is an identification string
id	Identification string
lines	Number of lines
bytes	Number of bytes
ifdisposition	`true` if there is a disposition string
disposition	Disposition string
ifdparameters	`true` if the `dparameters` array exists
dparameters	An array of objects where each object has an "attribute" and a "value" property corresponding to the parameters on the Content-disposition MIME header.
ifparameters	`true` if the parameters array exists
parameters	An array of objects where each object has an "attribute" and a "value" property.
parts	An array of objects identical in structure to the top-level object, each of which corresponds to a MIME body part.

Value	Type	Constant
0	text	TYPETEXT
1	multipart	TYPEMULTIPART
2	message	TYPEMESSAGE
3	application	TYPEAPPLICATION
4	audio	TYPEAUDIO
5	image	TYPEIMAGE
6	video	TYPEVIDEO
7	model	TYPEMODEL
8	other	TYPEOTHER

Value	Type	Constant
0	7bit	ENC7BIT
1	8bit	ENC8BIT
2	Binary	ENCBINARY
3	Base64	ENCBASE64
4	Quoted-Printable	ENCQUOTEDPRINTABLE
5	other	ENCOTHER

参见

imap_fetchbody
imap_bodystruct

imap_fetchtext

别名 imap_body

说明

此函数是该函数的别名： imap_body.

imap_gc

Clears IMAP cache

说明

bool imap_gc ( resource $imap_stream , int $caches )

Purges the cache of entries of a specific type.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

caches
Specifies the cache to purge. It may one or a combination of the following constants: IMAP_GC_ELT (message cache elements), IMAP_GC_ENV (envelope and bodies), IMAP_GC_TEXTS (texts).

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 imap_gc example

<?php

$mbox = imap_open("{imap.example.org:143}", "username", "password");

imap_gc($mbox, IMAP_GC_ELT);

?>

imap_get_quota

Retrieve the quota level settings, and usage statics per mailbox

说明

array imap_get_quota ( resource $imap_stream , string $quota_root )

Retrieve the quota level settings, and usage statics per mailbox.

For a non-admin user version of this function, please see the imap_get_quotaroot function of PHP.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

quota_root
quota_root should normally be in the form of user.name where name is the mailbox you wish to retrieve information about.

返回值

Returns an array with integer values limit and usage for the given mailbox. The value of limit represents the total amount of space allowed for this mailbox. The usage value represents the mailboxes current level of capacity. Will return false in the case of failure.

As of PHP 4.3, the function more properly reflects the functionality as dictated by the » RFC2087. The array return value has changed to support an unlimited number of returned resources (i.e. messages, or sub-folders) with each named resource receiving an individual array key. Each key value then contains an another array with the usage and limit values within it.

For backwards compatibility reasons, the original access methods are still available for use, although it is suggested to update.

范例

示例 #1 imap_get_quota example

<?php
$mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
      or die("can't connect: " . imap_last_error());

$quota_value = imap_get_quota($mbox, "user.kalowsky");
if (is_array($quota_value)) {
    echo "Usage level is: " . $quota_value['usage'];
    echo "Limit level is: " . $quota_value['limit'];
}

imap_close($mbox);
?>

示例 #2 imap_get_quota 4.3 or greater example

<?php
$mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
      or die("can't connect: " . imap_last_error());

$quota_values = imap_get_quota($mbox, "user.kalowsky");
if (is_array($quota_values)) {
   $storage = $quota_values['STORAGE'];
   echo "STORAGE usage level is: " .  $storage['usage'];
   echo "STORAGE limit level is: " .  $storage['limit'];

   $message = $quota_values['MESSAGE'];
   echo "MESSAGE usage level is: " .  $message['usage'];
   echo "MESSAGE limit is: " .  $message['limit'];

   /* ...  */
}

imap_close($mbox);
?>

注释

This function is currently only available to users of the c-client2000 or greater library.

The given imap_stream must be opened as the mail administrator, otherwise this function will fail.

参见

imap_open
imap_set_quota
imap_get_quotaroot

imap_get_quotaroot

Retrieve the quota settings per user

说明

array imap_get_quotaroot ( resource $imap_stream , string $quota_root )

Retrieve the quota settings per user. The limit value represents the total amount of space allowed for this user's total mailbox usage. The usage value represents the user's current total mailbox capacity.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

quota_root
quota_root should normally be in the form of which mailbox (i.e. INBOX).

返回值

Returns an array of integer values pertaining to the specified user mailbox. All values contain a key based upon the resource name, and a corresponding array with the usage and limit values within.

This function will return false in the case of call failure, and an array of information about the connection upon an un-parsable response from the server.

范例

示例 #1 imap_get_quotaroot example

<?php
$mbox = imap_open("{imap.example.org}", "kalowsky", "password", OP_HALFOPEN)
      or die("can't connect: " . imap_last_error());

$quota = imap_get_quotaroot($mbox, "INBOX");
if (is_array($quota)) {
   $storage = $quota['STORAGE'];
   echo "STORAGE usage level is: " .  $storage['usage'];
   echo "STORAGE limit level is: " .  $storage['limit'];

   $message = $quota['MESSAGE'];
   echo "MESSAGE usage level is: " .  $message['usage'];
   echo "MESSAGE limit level is: " .  $message['limit'];

   /* ...  */

}

imap_close($mbox);
?>

注释

This function is currently only available to users of the c-client2000 or greater library.

The imap_stream should be opened as the user whose mailbox you wish to check.

参见

imap_open
imap_set_quota
imap_get_quota

imap_getacl

Gets the ACL for a given mailbox

说明

array imap_getacl ( resource $imap_stream , string $mailbox )

Gets the ACL for a given mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

返回值

Returns an associative array of "folder" => "acl" pairs.

范例

示例 #1 imap_getacl example

<?php

print_r(imap_getacl($conn_id, 'user.joecool'));

?>

以上例程的输出类似于：

Array
(
    [asubfolder] => lrswipcda
    [anothersubfolder] => lrswipcda
)

注释

This function is currently only available to users of the c-client2000 or greater library.

参见

imap_setacl

imap_getmailboxes

Read the list of mailboxes, returning detailed information on each one

说明

array imap_getmailboxes ( resource $imap_stream , string $ref , string $pattern )

Gets information on the mailboxes.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

ref
ref should normally be just the server specification as described in imap_open

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

pattern
指定在邮箱层级的何处开始查找。

在组成 pattern 的字符中可使用两个特殊字符： '*' 和 '%'。 '*' 是指返回所有邮箱目录. 如果将 '*' 作为 pattern 参数时, 则会返回整个邮箱层级结构。 '%' 是指只返回当前级次。 '%' 作为 pattern 参数则只会返回顶层邮箱； '~/mail/%' 用于 UW_IMAPD 则会返回名为 ~/mail 的目录, 但不包含其子目录。

返回值

Returns an array of objects containing mailbox information. Each object has the attributes name, specifying the full name of the mailbox; delimiter, which is the hierarchy delimiter for the part of the hierarchy this mailbox is in; and attributes. Attributes is a bitmask that can be tested against:

LATT_NOINFERIORS - This mailbox not contains, and may not contain any "children" (there are no mailboxes below this one). Calling imap_createmailbox will not work on this mailbox.
LATT_NOSELECT - This is only a container, not a mailbox - you cannot open it.
LATT_MARKED - This mailbox is marked. This means that it may contain new messages since the last time it was checked. Not provided by all IMAP servers.
LATT_UNMARKED - This mailbox is not marked, does not contain new messages. If either MARKED or UNMARKED is provided, you can assume the IMAP server supports this feature for this mailbox.
LATT_REFERRAL - This container has a referral to a remote mailbox.
LATT_HASCHILDREN - This mailbox has selectable inferiors.
LATT_HASNOCHILDREN - This mailbox has no selectable inferiors.

范例

示例 #1 imap_getmailboxes example

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
      or die("can't connect: " . imap_last_error());

$list = imap_getmailboxes($mbox, "{imap.example.org}", "*");
if (is_array($list)) {
    foreach ($list as $key => $val) {
        echo "($key) ";
        echo imap_utf7_decode($val->name) . ",";
        echo "'" . $val->delimiter . "',";
        echo $val->attributes . "<br />\n";
    }
} else {
    echo "imap_getmailboxes failed: " . imap_last_error() . "\n";
}

imap_close($mbox);
?>

参见

imap_getsubscribed

imap_getsubscribed

List all the subscribed mailboxes

说明

array imap_getsubscribed ( resource $imap_stream , string $ref , string $pattern )

Gets information about the subscribed mailboxes.

Identical to imap_getmailboxes, except that it only returns mailboxes that the user is subscribed to.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

ref
ref should normally be just the server specification as described in imap_open

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

pattern
指定在邮箱层级的何处开始查找。

返回值

LATT_NOINFERIORS - This mailbox has no "children" (there are no mailboxes below this one).
LATT_NOSELECT - This is only a container, not a mailbox - you cannot open it.
LATT_MARKED - This mailbox is marked. Only used by UW-IMAPD.
LATT_UNMARKED - This mailbox is not marked. Only used by UW-IMAPD.
LATT_REFERRAL - This container has a referral to a remote mailbox.
LATT_HASCHILDREN - This mailbox has selectable inferiors.
LATT_HASNOCHILDREN - This mailbox has no selectable inferiors.

imap_header

别名 imap_headerinfo

说明

此函数是该函数的别名： imap_headerinfo.

imap_headerinfo

Read the header of the message

说明

object imap_headerinfo ( resource $imap_stream , int $msg_number [, int $fromlength = 0 [, int $subjectlength = 0 [, string $defaulthost = null ]]] )

Gets information about the given message number by reading its headers.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

fromlength
Number of characters for the fetchfrom property. Must be greater than or equal to zero.

subjectlength
Number of characters for the fetchsubject property Must be greater than or equal to zero.

defaulthost

返回值

Returns false on error or, if successful, the information in an object with following properties:

toaddress - full to: line, up to 1024 characters
to - an array of objects from the To: line, with the following properties: personal, adl, mailbox, and host
fromaddress - full from: line, up to 1024 characters
from - an array of objects from the From: line, with the following properties: personal, adl, mailbox, and host
ccaddress - full cc: line, up to 1024 characters
cc - an array of objects from the Cc: line, with the following properties: personal, adl, mailbox, and host
bccaddress - full bcc: line, up to 1024 characters
bcc - an array of objects from the Bcc: line, with the following properties: personal, adl, mailbox, and host
reply_toaddress - full Reply-To: line, up to 1024 characters
reply_to - an array of objects from the Reply-To: line, with the following properties: personal, adl, mailbox, and host
senderaddress - full sender: line, up to 1024 characters
sender - an array of objects from the Sender: line, with the following properties: personal, adl, mailbox, and host
return_pathaddress - full Return-Path: line, up to 1024 characters
return_path - an array of objects from the Return-Path: line, with the following properties: personal, adl, mailbox, and host
remail -
date - The message date as found in its headers
Date - Same as date
subject - The message subject
Subject - Same as subject
in_reply_to -
message_id -
newsgroups -
followup_to -
references -
Recent - R if recent and seen, N if recent and not seen, ' ' if not recent.
Unseen - U if not seen AND not recent, ' ' if seen OR not seen and recent
Flagged - F if flagged, ' ' if not flagged
Answered - A if answered, ' ' if unanswered
Deleted - D if deleted, ' ' if not deleted
Draft - X if draft, ' ' if not draft
Msgno - The message number
MailDate -
Size - The message size
udate - mail message date in Unix time
fetchfrom - from line formatted to fit fromlength characters
fetchsubject - subject line formatted to fit subjectlength characters

参见

imap_fetch_overview

imap_headers

Returns headers for all messages in a mailbox

说明

array imap_headers ( resource $imap_stream )

Returns headers for all messages in a mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

返回值

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

imap_last_error

Gets the last IMAP error that occurred during this page request

说明

string imap_last_error ( void )

Gets the full text of the last IMAP error message that occurred on the current page. The error stack is untouched; calling imap_last_error subsequently, with no intervening errors, will return the same error.

返回值

Returns the full text of the last IMAP error message that occurred on the current page. Returns false if no error messages are available.

参见

imap_errors

imap_list

Read the list of mailboxes

说明

array imap_list ( resource $imap_stream , string $ref , string $pattern )

Read the list of mailboxes.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

ref
ref should normally be just the server specification as described in imap_open.

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

pattern
指定在邮箱层级的何处开始查找。

返回值

Returns an array containing the names of the mailboxes or false in case of failure.

范例

示例 #1 imap_list example

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
      or die("can't connect: " . imap_last_error());

$list = imap_list($mbox, "{imap.example.org}", "*");
if (is_array($list)) {
    foreach ($list as $val) {
        echo imap_utf7_decode($val) . "\n";
    }
} else {
    echo "imap_list failed: " . imap_last_error() . "\n";
}

imap_close($mbox);
?>

参见

imap_getmailboxes
imap_lsub

imap_listmailbox

别名 imap_list

说明

此函数是该函数的别名： imap_list.

imap_listscan

Returns the list of mailboxes that matches the given text

说明

array imap_listscan ( resource $imap_stream , string $ref , string $pattern , string $content )

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

This function is similar to imap_listmailbox, but it will additionally check for the presence of the string content inside the mailbox data.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

ref
ref should normally be just the server specification as described in imap_open

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

pattern
指定在邮箱层级的何处开始查找。

content
The searched string

返回值

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

参见

imap_listmailbox
imap_search

imap_listsubscribed

别名 imap_lsub

说明

此函数是该函数的别名： imap_lsub.

imap_lsub

List all the subscribed mailboxes

说明

array imap_lsub ( resource $imap_stream , string $ref , string $pattern )

Gets an array of all the mailboxes that you have subscribed.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

ref
ref should normally be just the server specification as described in imap_open

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

pattern
指定在邮箱层级的何处开始查找。

返回值

Returns an array of all the subscribed mailboxes.

参见

imap_list
imap_getmailboxes

imap_mail_compose

Create a MIME message based on given envelope and body sections

说明

stringfalse imap_mail_compose ( array $envelope , array $body )

Create a MIME message based on the given envelope and body sections.

参数

envelope
An associative array of header fields. Valid keys are: "remail", "return_path", "date", "from", "reply_to", "in_reply_to", "subject", "to", "cc", "bcc" and "message_id", which set the respective message headers to the given string. To set additional headers, the key "custom_headers" is supported, which expects an array of those headers, e.g. ["User-Agent: My Mail Client"].

body
An indexed array of bodies. The first body is the main body of the message; only if it has a type of TYPEMULTIPART, further bodies are processed; these bodies constitute the bodies of the parts.

Key	Type	Description
type	int	The MIME type. One of `TYPETEXT` (default), `TYPEMULTIPART`, `TYPEMESSAGE`, `TYPEAPPLICATION`, `TYPEAUDIO`, `TYPEIMAGE`, `TYPEMODEL` or `TYPEOTHER`.
encoding	int	The Content-Transfer-Encoding. One of `ENC7BIT` (default), `ENC8BIT`, `ENCBINARY`, `ENCBASE64`, `ENCQUOTEDPRINTABLE` or `ENCOTHER`.
charset	string	The charset parameter of the MIME type.
type.parameters	array	An associative array of Content-Type parameter names and their values.
subtype	string	The MIME subtype, e.g. 'jpeg' for `TYPEIMAGE`.
id	string	The Content-ID.
description	string	The Content-Description.
disposition.type	string	The Content-Disposition, e.g. 'attachment'.
disposition	array	An associative array of Content-Disposition parameter names and values.
contents.data	string	The payload.
lines	int	The size of the payload in lines.
bytes	int	The size of the payload in bytes.
md5	string	The MD5 checksum of the payload.

返回值

Returns the MIME message as string, 或者在失败时返回 false.

范例

示例 #1 imap_mail_compose example

<?php

$envelope["from"]= "[email protected]";
$envelope["to"]  = "[email protected]";
$envelope["cc"]  = "[email protected]";

$part1["type"] = TYPEMULTIPART;
$part1["subtype"] = "mixed";

$filename = "/tmp/imap.c.gz";
$fp = fopen($filename, "r");
$contents = fread($fp, filesize($filename));
fclose($fp);

$part2["type"] = TYPEAPPLICATION;
$part2["encoding"] = ENCBINARY;
$part2["subtype"] = "octet-stream";
$part2["description"] = basename($filename);
$part2["contents.data"] = $contents;

$part3["type"] = TYPETEXT;
$part3["subtype"] = "plain";
$part3["description"] = "description3";
$part3["contents.data"] = "contents.data3\n\n\n\t";

$body[1] = $part1;
$body[2] = $part2;
$body[3] = $part3;

echo nl2br(imap_mail_compose($envelope, $body));

?>

imap_mail_copy

Copy specified messages to a mailbox

说明

bool imap_mail_copy ( resource $imap_stream , string $msglist , string $mailbox [, int $options = 0 ] )

Copies mail messages specified by msglist to specified mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msglist
msglist is a range not just message numbers (as described in » RFC2060).

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

options
options 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

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_mail_move

imap_mail_move

Move specified messages to a mailbox

说明

bool imap_mail_move ( resource $imap_stream , string $msglist , string $mailbox [, int $options = 0 ] )

Moves mail messages specified by msglist to the specified mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msglist
msglist is a range not just message numbers (as described in » RFC2060).

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

options
options is a bitmask and may contain the single option:

CP_UID - the sequence numbers contain UIDS

返回值

成功时返回 true，或者在失败时返回 false。

注释

Note:

imap_mail_move will flag the original mail with a delete flag, to successfully delete it a call to the imap_expunge function must be made.

参见

imap_mail_copy

imap_mail

Send an email message

说明

bool imap_mail ( string $to , string $subject , string $message [, string $additional_headers = null [, string $cc = null [, string $bcc = null [, string $rpath = null ]]]] )

This function allows sending of emails with correct handling of Cc and Bcc receivers.

The parameters to, cc and bcc are all strings and are all parsed as » RFC822 address lists.

参数

to
The receiver

subject
The mail subject

message
The mail body, see imap_mail_compose

additional_headers
As string with additional headers to be set on the mail

cc

bcc
The receivers specified in bcc will get the mail, but are excluded from the headers.

rpath
Use this parameter to specify return path upon mail delivery failure. This is useful when using PHP as a mail client for multiple users.

返回值

成功时返回 true，或者在失败时返回 false。

参见

mail
imap_mail_compose

imap_mailboxmsginfo

Get information about the current mailbox

说明

object imap_mailboxmsginfo ( resource $imap_stream )

Checks the current mailbox status on the server. It is similar to imap_status, but will additionally sum up the size of all messages in the mailbox, which will take some additional time to execute.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

返回值

Returns the information in an object with following properties:


Date	date of last change (current datetime)
Driver	driver
Mailbox	name of the mailbox
Nmsgs	number of messages
Recent	number of recent messages
Unread	number of unread messages
Deleted	number of deleted messages
Size	mailbox size

Returns false on failure.

范例

示例 #1 imap_mailboxmsginfo example

<?php

$mbox = imap_open("{imap.example.org}INBOX", "username", "password")
      or die("can't connect: " . imap_last_error());

$check = imap_mailboxmsginfo($mbox);

if ($check) {
    echo "Date: "     . $check->Date    . "<br />\n" ;
    echo "Driver: "   . $check->Driver  . "<br />\n" ;
    echo "Mailbox: "  . $check->Mailbox . "<br />\n" ;
    echo "Messages: " . $check->Nmsgs   . "<br />\n" ;
    echo "Recent: "   . $check->Recent  . "<br />\n" ;
    echo "Unread: "   . $check->Unread  . "<br />\n" ;
    echo "Deleted: "  . $check->Deleted . "<br />\n" ;
    echo "Size: "     . $check->Size    . "<br />\n" ;
} else {
    echo "imap_mailboxmsginfo() failed: " . imap_last_error() . "<br />\n";
}

imap_close($mbox);

?>

imap_mime_header_decode

Decode MIME header elements

说明

array imap_mime_header_decode ( string $text )

Decodes MIME message header extensions that are non ASCII text (see » RFC2047).

参数

text
The MIME text

返回值

The decoded elements are returned in an array of objects, where each object has two properties, charset and text.

If the element hasn't been encoded, and in other words is in plain US-ASCII, the charset property of that element is set to default.

范例

示例 #1 imap_mime_header_decode example

<?php
$text = "=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <[email protected]>";

$elements = imap_mime_header_decode($text);
for ($i=0; $i<count($elements); $i++) {
    echo "Charset: {$elements[$i]->charset}\n";
    echo "Text: {$elements[$i]->text}\n\n";
}
?>

以上例程会输出：

Charset: ISO-8859-1
Text: Keld Jørn Simonsen

Charset: default
Text:  <[email protected]>

In the above example we would have two elements, whereas the first element had previously been encoded with ISO-8859-1, and the second element would be plain US-ASCII.

参见

imap_utf8

imap_msgno

Gets the message sequence number for the given UID

说明

int imap_msgno ( resource $imap_stream , int $uid )

Returns the message sequence number for the given uid.

This function is the inverse of imap_uid.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

uid
The message UID

返回值

Returns the message sequence number for the given uid.

参见

imap_uid

imap_mutf7_to_utf8

Decode a modified UTF-7 string to UTF-8

说明

stringfalse imap_mutf7_to_utf8 ( string $in )

Decode a modified UTF-7 (as specified in RFC 2060, section 5.1.3) string to UTF-8.

Note:

This function is only available, if libcclient exports utf8_to_mutf7().

参数

in
A string encoded in modified UTF-7.

返回值

Returns in converted to UTF-8, 或者在失败时返回 false.

参见

imap_utf8_to_mutf7

imap_num_msg

Gets the number of messages in the current mailbox

说明

int imap_num_msg ( resource $imap_stream )

Gets the number of messages in the current mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

返回值

Return the number of messages in the current mailbox, as an integer, or false on error.

参见

imap_num_recent
imap_status

imap_num_recent

Gets the number of recent messages in current mailbox

说明

int imap_num_recent ( resource $imap_stream )

Gets the number of recent messages in the current mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

返回值

Returns the number of recent messages in the current mailbox, as an integer.

参见

imap_num_msg
imap_status

imap_open

Open an IMAP stream to a mailbox

说明

resource imap_open ( string $mailbox , string $username , string $password [, int $options = 0 [, int $n_retries = 0 [, array $params = array() ]]] )

Opens an IMAP stream to a mailbox.

This function can also be used to open streams to POP3 and NNTP servers, but some functions and features are only available on IMAP servers.

参数

mailbox
A mailbox name consists of a server and a mailbox path on this server. The special name INBOX stands for the current users personal mailbox. Mailbox names that contain international characters besides those in the printable ASCII space have to be encoded with imap_utf7_encode.

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

The server part, which is enclosed in '{' and '}', consists of the servers name or ip address, an optional port (prefixed by ':'), and an optional protocol specification (prefixed by '/').

The server part is mandatory in all mailbox parameters.

All names which start with { are remote names, and are in the form "{" remote_system_name [":" port] [flags] "}" [mailbox_name] where:

remote_system_name - Internet domain name or bracketed IP address of server.
port - optional TCP port number, default is the default port for that service
flags - optional flags, see following table.
mailbox_name - remote mailbox name, default is INBOX

Flag	Description
/service=service	mailbox access service, default is "imap"
/user=user	remote user name for login on the server
/authuser=user	remote authentication user; if specified this is the user name whose password is used (e.g. administrator)
/anonymous	remote access as anonymous user
/debug	record protocol telemetry in application's debug log
/secure	do not transmit a plaintext password over the network
/imap, /imap2, /imap2bis, /imap4, /imap4rev1	equivalent to /service=imap
/pop3	equivalent to /service=pop3
/nntp	equivalent to /service=nntp
/norsh	do not use rsh or ssh to establish a preauthenticated IMAP session
/ssl	use the Secure Socket Layer to encrypt the session
/validate-cert	validate certificates from TLS/SSL server (this is the default behavior)
/novalidate-cert	do not validate certificates from TLS/SSL server, needed if server uses self-signed certificates
/tls	force use of start-TLS to encrypt the session, and reject connection to servers that do not support it
/notls	do not do start-TLS to encrypt the session, even with servers that support it
/readonly	request read-only mailbox open (IMAP only; ignored on NNTP, and an error with SMTP and POP3)

username
The user name

password
The password associated with the username

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

OP_READONLY - Open mailbox read-only
OP_ANONYMOUS - Don't use or update a .newsrc for news (NNTP only)
OP_HALFOPEN - For IMAP and NNTP names, open a connection but don't open a mailbox.
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close (see also imap_delete and imap_expunge)
OP_DEBUG - Debug protocol negotiations
OP_SHORTCACHE - Short (elt-only) caching
OP_SILENT - Don't pass up events (internal use)
OP_PROTOTYPE - Return driver prototype
OP_SECURE - Don't do non-secure authentication

n_retries
Number of maximum connect attempts

params
Connection parameters, the following (string) keys maybe used to set one or more connection parameters:

DISABLE_AUTHENTICATOR - Disable authentication properties

返回值

Returns an IMAP stream on success or false on error.

范例

示例 #1 Different use of imap_open

<?php
// 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:110/pop3}INBOX", "user_id", "password");

// To connect to an SSL IMAP or POP3 server, add /ssl after the protocol
// specification:
$mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

// To connect to an SSL IMAP or POP3 server with a self-signed certificate,
// add /ssl/novalidate-cert after the protocol specification:
$mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

// To connect to an NNTP server on port 119 on the local server, use:
$nntp = imap_open ("{localhost:119/nntp}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.
?>

示例 #2 imap_open example

<?php
$mbox = imap_open("{imap.example.org:143}", "username", "password");

echo "<h1>Mailboxes</h1>\n";
$folders = imap_listmailbox($mbox, "{imap.example.org:143}", "*");

if ($folders == false) {
    echo "Call failed<br />\n";
} else {
    foreach ($folders as $val) {
        echo $val . "<br />\n";
    }
}

echo "<h1>Headers in INBOX</h1>\n";
$headers = imap_headers($mbox);

if ($headers == false) {
    echo "Call failed<br />\n";
} else {
    foreach ($headers as $val) {
        echo $val . "<br />\n";
    }
}

imap_close($mbox);
?>

参见

imap_close

imap_ping

Check if the IMAP stream is still active

说明

bool imap_ping ( resource $imap_stream )

imap_ping pings the stream to see if it's 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_stream
由 imap_open 返回的 IMAP 流。

返回值

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

范例

示例 #1 imap_ping Example

<?php

$imap = imap_open("{imap.example.org}", "mailadmin", "password");

// after some sleeping
if (!imap_ping($imap)) {
    // do some stuff to reconnect
}

?>

imap_qprint

Convert a quoted-printable string to an 8 bit string

说明

string imap_qprint ( string $string )

Convert a quoted-printable string to an 8 bit string according to » RFC2045, section 6.7.

参数

string
A quoted-printable string

返回值

Returns an 8 bits string.

参见

imap_8bit

imap_rename

别名 imap_renamemailbox

说明

此函数是该函数的别名： imap_renamemailbox.

imap_renamemailbox

Rename an old mailbox to new mailbox

说明

bool imap_renamemailbox ( resource $imap_stream , string $old_mbox , string $new_mbox )

This function renames on old mailbox to new mailbox (see imap_open for the format of mbox names).

参数

imap_stream
由 imap_open 返回的 IMAP 流。

old_mbox
The old mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

new_mbox
The new mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_createmailbox
imap_deletemailbox

imap_reopen

Reopen IMAP stream to new mailbox

说明

bool imap_reopen ( resource $imap_stream , string $mailbox [, int $options = 0 [, int $n_retries = 0 ]] )

Reopens the specified stream to a new mailbox on an IMAP or NNTP server.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

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

OP_READONLY - Open mailbox read-only
OP_ANONYMOUS - Don't use or update a .newsrc for news (NNTP only)
OP_HALFOPEN - For IMAP and NNTP names, open a connection but don't open a mailbox.
OP_EXPUNGE - Silently expunge recycle stream
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close (see also imap_delete and imap_expunge)

n_retries
Number of maximum connect attempts

返回值

Returns true if the stream is reopened, false otherwise.

范例

示例 #1 imap_reopen example

<?php
$mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
// ...
imap_reopen($mbox, "{imap.example.org:143}INBOX.Sent") or die(implode(", ", imap_errors()));
// ..
?>

imap_rfc822_parse_adrlist

Parses an address string

说明

array imap_rfc822_parse_adrlist ( string $address , string $default_host )

Parses the address string as defined in » RFC2822 and for each address.

参数

address
A string containing addresses

default_host
The default host name

返回值

Returns an array of objects. The objects properties are:

mailbox - the mailbox name (username)
host - the host name
personal - the personal name
adl - at domain source route

范例

示例 #1 imap_rfc822_parse_adrlist example

<?php

$address_string = "Joe Doe <[email protected]>, [email protected], root";
$address_array  = imap_rfc822_parse_adrlist($address_string, "example.com");
if (!is_array($address_array) || count($address_array) < 1) {
    die("something is wrong\n");
}

foreach ($address_array as $id => $val) {
    echo "# $id\n";
    echo "  mailbox : " . $val->mailbox . "\n";
    echo "  host    : " . $val->host . "\n";
    echo "  personal: " . $val->personal . "\n";
    echo "  adl     : " . $val->adl . "\n";
}
?>

以上例程会输出：

# 0
  mailbox : doe
  host    : example.com
  personal: Joe Doe
  adl     : 
# 1
  mailbox : postmaster
  host    : example.com
  personal: 
  adl     : 
# 2
  mailbox : root
  host    : example.com
  personal: 
  adl     :

参见

imap_rfc822_parse_headers

imap_rfc822_parse_headers

Parse mail headers from a string

说明

object imap_rfc822_parse_headers ( string $headers [, string $defaulthost = "UNKNOWN" ] )

Gets an object of various header elements, similar to imap_header.

参数

headers
The parsed headers data

defaulthost
The default host name

返回值

Returns an object similar to the one returned by imap_header, except for the flags and other properties that come from the IMAP server.

参见

imap_rfc822_parse_adrlist

imap_rfc822_write_address

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

说明

string imap_rfc822_write_address ( string $mailbox , string $host , string $personal )

Returns a properly formatted email address as defined in » RFC2822 given the needed information.

参数

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

host
The email host part

personal
The name of the account owner

返回值

Returns a string properly formatted email address as defined in » RFC2822.

范例

示例 #1 imap_rfc822_write_address example

<?php
echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
?>

以上例程会输出：

Hartmut Holzgraefe <[email protected]>

imap_savebody

Save a specific body section to a file

说明

bool imap_savebody ( resource $imap_stream , mixed $file , int $msg_number [, string $part_number = "" [, int $options = 0 ]] )

Saves a part or the whole body of the specified message.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

file
The path to the saved file as a string, or a valid file descriptor returned by fopen.

msg_number
The message number

part_number
The part number. It is a string of integers delimited by period which index into a body part list as per the IMAP4 specification

options
A bitmask with one or more of the following:

FT_UID - The msg_number 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.

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_fetchbody

imap_scan

别名 imap_listscan

说明

此函数是该函数的别名： imap_listscan.

imap_scanmailbox

别名 imap_listscan

说明

此函数是该函数的别名： imap_listscan.

imap_search

This function returns an array of messages matching the given search criteria

说明

array imap_search ( resource $imap_stream , string $criteria [, int $options = SE_FREE [, string $charset = null ]] )

This function performs a search on the mailbox currently opened in the given IMAP stream.

For example, to match all unanswered messages sent by Mom, you'd use: "UNANSWERED FROM mom". Searches appear to be case insensitive. This list of criteria is from a reading of the UW c-client source code and may be incomplete or inaccurate (see also » RFC1176, section "tag SEARCH search_criteria").

参数

imap_stream
由 imap_open 返回的 IMAP 流。

criteria
A string, delimited by spaces, in which the following keywords are allowed. Any multi-word arguments (e.g. FROM "joey smith") must be quoted. Results will match all criteria entries.

ALL - return all messages matching the rest of the criteria
ANSWERED - match messages with the \\ANSWERED flag set
BCC "string" - match messages with "string" in the Bcc: field
BEFORE "date" - match messages with Date: before "date"
BODY "string" - match messages with "string" in the body of the message
CC "string" - match messages with "string" in the Cc: field
DELETED - match deleted messages
FLAGGED - match messages with the \\FLAGGED (sometimes referred to as Important or Urgent) flag set
FROM "string" - match messages with "string" in the From: field
KEYWORD "string" - match messages with "string" as a keyword
NEW - match new messages
OLD - match old messages
ON "date" - match messages with Date: matching "date"
RECENT - match messages with the \\RECENT flag set
SEEN - match messages that have been read (the \\SEEN flag is set)
SINCE "date" - match messages with Date: after "date"
SUBJECT "string" - match messages with "string" in the Subject:
TEXT "string" - match messages with text "string"
TO "string" - match messages with "string" in the To:
UNANSWERED - match messages that have not been answered
UNDELETED - match messages that are not deleted
UNFLAGGED - match messages that are not flagged
UNKEYWORD "string" - match messages that do not have the keyword "string"
UNSEEN - match messages which have not been read yet

options
Valid values for options are SE_UID, which causes the returned array to contain UIDs instead of messages sequence numbers.

charset
MIME character set to use when searching strings.

返回值

Returns an array of message numbers or UIDs.

Return false if it does not understand the search criteria or no messages have been found.

范例

示例 #1 imap_search example

<?php
$conn   = imap_open('{imap.example.com:993/imap/ssl}INBOX', '[email protected]', 'pass123', OP_READONLY);

$some   = imap_search($conn, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
$msgnos = imap_search($conn, 'ALL');
$uids   = imap_search($conn, 'ALL', SE_UID);

print_r($some);
print_r($msgnos);
print_r($uids);
?>

以上例程的输出类似于：

Array
(
    [0] => 4
    [1] => 6
    [2] => 11
)
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
    [5] => 6
)
Array
(
    [0] => 1
    [1] => 4
    [2] => 6
    [3] => 8
    [4] => 11
    [5] => 12
)

参见

imap_listscan

imap_set_quota

Sets a quota for a given mailbox

说明

bool imap_set_quota ( resource $imap_stream , string $quota_root , int $quota_limit )

Sets an upper limit quota on a per mailbox basis.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

quota_root
The mailbox to have a quota set. This should follow the IMAP standard format for a mailbox: user.name.

quota_limit
The maximum size (in KB) for the quota_root

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 imap_set_quota example

<?php
$mbox = imap_open("{imap.example.org:143}", "mailadmin", "password");

if (!imap_set_quota($mbox, "user.kalowsky", 3000)) {
    echo "Error in setting quota\n";
    return;
}

imap_close($mbox);
?>

注释

This function is currently only available to users of the c-client2000 or greater library.

The given imap_stream must be opened as the mail administrator, other wise this function will fail.

参见

imap_open
imap_get_quota

imap_setacl

Sets the ACL for a given mailbox

说明

bool imap_setacl ( resource $imap_stream , string $mailbox , string $id , string $rights )

Sets the ACL for a giving mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

id
The user to give the rights to.

rights
The rights to give to the user. Passing an empty string will delete acl.

返回值

成功时返回 true，或者在失败时返回 false。

注释

This function is currently only available to users of the c-client2000 or greater library.

参见

imap_getacl

imap_setflag_full

Sets flags on messages

说明

bool imap_setflag_full ( resource $imap_stream , string $sequence , string $flag [, int $options = NIL ] )

Causes a store to add the specified flag to the flags set for the messages in the specified sequence.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

sequence
A sequence of message numbers. You can enumerate desired messages with the X,Y syntax, or retrieve all messages within an interval with the X:Y syntax

flag
The flags which you can set are \Seen, \Answered, \Flagged, \Deleted, and \Draft as defined by » RFC2060.

options
A bit mask that may contain the single option:

ST_UID - The sequence argument contains UIDs instead of sequence numbers

返回值

成功时返回 true，或者在失败时返回 false。

范例

示例 #1 imap_setflag_full example

<?php
$mbox = imap_open("{imap.example.org:143}", "username", "password")
     or die("can't connect: " . imap_last_error());

$status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged");

echo gettype($status) . "\n";
echo $status . "\n";

imap_close($mbox);
?>

参见

imap_clearflag_full

imap_sort

Gets and sort messages

说明

arrayfalse imap_sort ( resource $imap_stream , int $criteria , int $reverse [, int $options = 0 [, string $search_criteria = null [, string $charset = null ]]] )

Gets and sorts message numbers by the given parameters.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

criteria
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

reverse
Set this to 1 for reverse sorting

options
The options 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

search_criteria
IMAP2-format search criteria string. For details see imap_search.

charset
MIME character set to use when sorting strings.

返回值

Returns an array of message numbers sorted by the given parameters, 或者在失败时返回 false.

imap_status

Returns status information on a mailbox

说明

object imap_status ( resource $imap_stream , string $mailbox , int $options )

Gets status information about the given mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

options
Valid flags are:

SA_MESSAGES - set $status->messages to the number of messages in the mailbox
SA_RECENT - set $status->recent to the number of recent messages in the mailbox
SA_UNSEEN - set $status->unseen to the number of unseen (new) messages in the mailbox
SA_UIDNEXT - set $status->uidnext to the next uid to be used in the mailbox
SA_UIDVALIDITY - set $status->uidvalidity to a constant that changes when uids for the mailbox may no longer be valid
SA_ALL - set all of the above

返回值

This function returns an object containing status information. The object has the following properties: messages, recent, unseen, uidnext, and uidvalidity.

flags is also set, which contains a bitmask which can be checked against any of the above constants.

范例

示例 #1 imap_status example

<?php
$mbox = imap_open("{imap.example.com}", "username", "password", OP_HALFOPEN)
      or die("can't connect: " . imap_last_error());

$status = imap_status($mbox, "{imap.example.org}INBOX", SA_ALL);
if ($status) {
  echo "Messages:   " . $status->messages    . "<br />\n";
  echo "Recent:     " . $status->recent      . "<br />\n";
  echo "Unseen:     " . $status->unseen      . "<br />\n";
  echo "UIDnext:    " . $status->uidnext     . "<br />\n";
  echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";
} else {
  echo "imap_status failed: " . imap_last_error() . "\n";
}

imap_close($mbox);
?>

imap_subscribe

Subscribe to a mailbox

说明

bool imap_subscribe ( resource $imap_stream , string $mailbox )

Subscribe to a new mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_unsubscribe

imap_thread

Returns a tree of threaded message

说明

array imap_thread ( resource $imap_stream [, int $options = SE_FREE ] )

Gets a tree of a threaded message.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

options

返回值

imap_thread returns an associative array containing a tree of messages threaded by REFERENCES, or false on error.

Every message in the current mailbox will be represented by three entries in the resulting array:

$thread["XX.num"] - current message number
$thread["XX.next"]
$thread["XX.branch"]

范例

示例 #1 imap_thread Example

<?php

// Here we're outputting the threads of a newsgroup, in HTML

$nntp = imap_open('{news.example.com:119/nntp}some.newsgroup', '', '');
$threads = imap_thread($nntp);

foreach ($threads as $key => $val) {
  $tree = explode('.', $key);
  if ($tree[1] == 'num') {
    $header = imap_headerinfo($nntp, $val);
    echo "<ul>\n\t<li>" . $header->fromaddress . "\n";
  } elseif ($tree[1] == 'branch') {
    echo "\t</li>\n</ul>\n";
  }
}

imap_close($nntp);

?>

imap_timeout

Set or fetch imap timeout

说明

mixed imap_timeout ( int $timeout_type [, int $timeout = -1 ] )

Sets or fetches the imap timeout.

参数

timeout_type
One of the following: IMAP_OPENTIMEOUT, IMAP_READTIMEOUT, IMAP_WRITETIMEOUT, or IMAP_CLOSETIMEOUT.

timeout
The timeout, in seconds.

返回值

If the timeout parameter is set, this function returns true on success and false on failure.

If timeout is not provided or evaluates to -1, the current timeout value of timeout_type is returned as an integer.

范例

示例 #1 imap_timeout example

<?php

echo "The current read timeout is " . imap_timeout(IMAP_READTIMEOUT) . "\n";

?>

imap_uid

This function returns the UID for the given message sequence number

说明

int imap_uid ( resource $imap_stream , int $msg_number )

This function returns the UID for the given message sequence number. An UID is a unique identifier that will not change over time while a message sequence number may change whenever the content of the mailbox changes.

This function is the inverse of imap_msgno.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number.

返回值

The UID of the given message.

注释

Note:

This function is not supported by POP3 mailboxes.

参见

imap_msgno

imap_undelete

Unmark the message which is marked deleted

说明

bool imap_undelete ( resource $imap_stream , int $msg_number [, int $flags = 0 ] )

Removes the deletion flag for a specified message, which is set by imap_delete or imap_mail_move.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

msg_number
The message number

flags

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_delete
imap_mail_move

imap_unsubscribe

Unsubscribe from a mailbox

说明

bool imap_unsubscribe ( resource $imap_stream , string $mailbox )

Unsubscribe from the specified mailbox.

参数

imap_stream
由 imap_open 返回的 IMAP 流。

mailbox
The mailbox name, see imap_open for more information

Warning Passing untrusted data to this parameter is insecure, unless imap.enable_insecure_rsh is disabled.

返回值

成功时返回 true，或者在失败时返回 false。

参见

imap_subscribe

imap_utf7_decode

Decodes a modified UTF-7 encoded string

说明

string imap_utf7_decode ( string $text )

Decodes modified UTF-7 text into ISO-8859-1 string.

This function is needed to decode mailbox names that contain certain characters which are not in range of printable ASCII characters.

参数

text
A modified UTF-7 encoding string, as defined in » RFC 2060, section 5.1.3 (original UTF-7 was defined in » RFC1642).

返回值

Returns a string that is encoded in ISO-8859-1 and consists of the same sequence of characters in text, or false if text contains invalid modified UTF-7 sequence or text contains a character that is not part of ISO-8859-1 character set.

参见

imap_utf7_encode

imap_utf7_encode

Converts ISO-8859-1 string to modified UTF-7 text

说明

string imap_utf7_encode ( string $data )

Converts data to modified UTF-7 text.

This is needed to encode mailbox names that contain certain characters which are not in range of printable ASCII characters.

参数

data
An ISO-8859-1 string.

返回值

Returns data encoded with the modified UTF-7 encoding as defined in » RFC 2060, section 5.1.3 (original UTF-7 was defined in » RFC1642).

参见

imap_utf7_decode

imap_utf8_to_mutf7

Encode a UTF-8 string to modified UTF-7

说明

stringfalse imap_utf8_to_mutf7 ( string $in )

Encode a UTF-8 string to modified UTF-7 (as specified in RFC 2060, section 5.1.3).

Note:

This function is only available, if libcclient exports utf8_to_mutf7().

参数

in
A UTF-8 encoded string.

返回值

Returns in converted to modified UTF-7, 或者在失败时返回 false.

参见

imap_mutf7_to_utf8

imap_utf8

Converts MIME-encoded text to UTF-8

说明

string imap_utf8 ( string $mime_encoded_text )

Converts the given mime_encoded_text to UTF-8, if the declared charset is known to libc-client. Otherwise the given text is decoded, but not converted to UTF-8.

参数

mime_encoded_text
A MIME encoded string. MIME encoding method and the UTF-8 specification are described in » RFC2047 and » RFC2044 respectively.

返回值

Returns the decoded string, if possible converted to UTF-8.

范例

示例 #1 Basic imap_utf8 Usage

<?php
echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
?>

以上例程的输出类似于：

Johannes Schlüter

参见

imap_mime_header_decode

imap_8bit — Convert an 8bit string to a quoted-printable string
imap_alerts — Returns all IMAP alert messages that have occurred
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_create — 别名 imap_createmailbox
imap_createmailbox — Create a new mailbox
imap_delete — Mark a message for deletion from current mailbox
imap_deletemailbox — Delete a mailbox
imap_errors — Returns all of the IMAP errors that have occurred
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_fetchmime — Fetch MIME headers for a particular section of the message
imap_fetchstructure — Read the structure of a particular message
imap_fetchtext — 别名 imap_body
imap_gc — Clears IMAP cache
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 — 别名 imap_headerinfo
imap_headerinfo — Read the header of the message
imap_headers — Returns headers for all messages in a mailbox
imap_last_error — Gets the last IMAP error that occurred during this page request
imap_list — Read the list of mailboxes
imap_listmailbox — 别名 imap_list
imap_listscan — Returns the list of mailboxes that matches the given text
imap_listsubscribed — 别名 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 — Gets the message sequence number for the given UID
imap_mutf7_to_utf8 — Decode a modified UTF-7 string to UTF-8
imap_num_msg — Gets the number of messages in the current mailbox
imap_num_recent — Gets 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_rename — 别名 imap_renamemailbox
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_savebody — Save a specific body section to a file
imap_scan — 别名 imap_listscan
imap_scanmailbox — 别名 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 given mailbox
imap_setflag_full — Sets flags on messages
imap_sort — Gets and sort messages
imap_status — Returns status information on a mailbox
imap_subscribe — Subscribe to a mailbox
imap_thread — Returns a tree of threaded message
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_to_mutf7 — Encode a UTF-8 string to modified UTF-7
imap_utf8 — Converts MIME-encoded text to UTF-8