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:

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

更新日志

版本说明
5.3.2Added INTERNALDATE support to imap_append.

范例

示例 #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: me@example.com\r\n"
                   . "To: you@example.com\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="foo@example.com"}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

更新日志

版本说明
5.3.3Add the udate property.

范例

示例 #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

说明

object 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 includes the envelope, internal date, size, flags and body structure along with a similar object for each mime attachment. The structure of the returned objects is as follows:

typePrimary body type
encodingBody transfer encoding
ifsubtypeTRUE if there is a subtype string
subtypeMIME subtype
ifdescriptionTRUE if there is a description string
descriptionContent description string
ifidTRUE if there is an identification string
idIdentification string
linesNumber of lines
bytesNumber of bytes
ifdispositionTRUE if there is a disposition string
dispositionDisposition string
ifdparametersTRUE if the dparameters array exists
dparametersAn array of objects where each object has an "attribute" and a "value" property corresponding to the parameters on the Content-disposition MIME header.
ifparametersTRUE if the parameters array exists
parametersAn array of objects where each object has an "attribute" and a "value" property.
partsAn array of objects identical in structure to the top-level object, each of which corresponds to a MIME body part.
ValueTypeConstant
0textTYPETEXT
1multipartTYPEMULTIPART
2messageTYPEMESSAGE
3applicationTYPEAPPLICATION
4audioTYPEAUDIO
5imageTYPEIMAGE
6videoTYPEVIDEO
7modelTYPEMODEL
8otherTYPEOTHER
ValueTypeConstant
07bitENC7BIT
18bitENC8BIT
2BinaryENCBINARY
3Base64ENCBASE64
4Quoted-PrintableENCQUOTEDPRINTABLE
5otherENCOTHER

参见

  • 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
指定在邮箱层级的何处开始查找。

在组成 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 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
指定在邮箱层级的何处开始查找。

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

返回值

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
指定在邮箱层级的何处开始查找。

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

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
指定在邮箱层级的何处开始查找。

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

返回值

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

说明

string imap_mail_compose ( array $envelope , array $body )

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

参数

envelope
An associative array of headers fields. Valid keys are: "remail", "return_path", "date", "from", "reply_to", "in_reply_to", "subject", "to", "cc", "bcc", "message_id" and "custom_headers" (which contains associative array of other headers).

body
An indexed array of bodies

A body is an associative array which can consist of the following keys: "type", "encoding", "charset", "type.parameters", "subtype", "id", "description", "disposition.type", "disposition", "contents.data", "lines", "bytes" and "md5".

返回值

Returns the MIME message.

范例

示例 #1 imap_mail_compose example

<?php

$envelope["from"]= "joe@example.com";
$envelope["to"]  = "foo@example.com";
$envelope["cc"]  = "bar@example.com";

$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 class="function">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:

Datedate of last change (current datetime)
Driverdriver
Mailboxname of the mailbox
Nmsgsnumber of messages
Recentnumber of recent messages
Unreadnumber of unread messages
Deletednumber of deleted messages
Sizemailbox 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?= <keld@example.com>";

$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:  <keld@example.com>

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

说明

string 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
FlagDescription
/service=servicemailbox access service, default is "imap"
/user=userremote user name for login on the server
/authuser=userremote authentication user; if specified this is the user name whose password is used (e.g. administrator)
/anonymousremote access as anonymous user
/debugrecord protocol telemetry in application's debug log
/securedo not transmit a plaintext password over the network
/imap, /imap2, /imap2bis, /imap4, /imap4rev1equivalent to /service=imap
/pop3equivalent to /service=pop3
/nntpequivalent to /service=nntp
/norshdo not use rsh or ssh to establish a preauthenticated IMAP session
/ssluse the Secure Socket Layer to encrypt the session
/validate-certvalidate certificates from TLS/SSL server (this is the default behavior)
/novalidate-certdo not validate certificates from TLS/SSL server, needed if server uses self-signed certificates
/tlsforce use of start-TLS to encrypt the session, and reject connection to servers that do not support it
/notlsdo not do start-TLS to encrypt the session, even with servers that support it
/readonlyrequest 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.

更新日志

版本说明
5.3.2params added
5.2.0n_retries added

范例

示例 #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.

更新日志

版本说明
5.2.0n_retries added

范例

示例 #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 <doe@example.com>, postmaster@example.com, 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 <hartmut@example.com>

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 » RFC2060, section 6.4.4).

参数

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', 'foo@example.com', '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

说明

array 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.

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

说明

string 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.

参数

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

返回值

Returns an UTF-8 encoded string.

参见

  • imap_mime_header_decode

目录