Назад
Регистрация Войти
Войти через VK Войти через FB Войти через Google Войти через Яндекс




Поиск по сайту




Наш Telegram бот: @htmlweb_bot

IMAP, POP3 и NNTP

В этом разделе описаны функции работы с почтой и почтовыми серверами по протоколам IMAP, POP3 и NNTP

Для большего понимания методики работы этих функций будет полезно ознакомиться с перечисленными ниже документами RFC:

  • RFC821: Simple Mail Transfer Protocol (SMTP).
  • RFC822: Стандарт текстовых сообщений интернет ARPA.
  • 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).

imap_open. Подключение к серверу и открытие почтового ящика

int imap_open (string mailbox, string username, string password [, int flags])

Функция возвращает дескриптор открытого почтового ящика IMAP или значение FALSE при возникновении ошибки. Эту функцию можно также использовать для подключения к серверам POP3 и NNTP, но в этом случае некоторые функции пакета будут недоступны.

В аргументе mailbox указывается имя сервера и путь к почтовому ящику. Имя сервера заключается в фигурные скобки и состоит из имени сервера или его IP-адреса, необязательного имени протокола, которое надо предварять символом слеша, и необязательного значения номера порта подключения, которое начинается с двоеточия. Имя сервера необходимо указывать всегда. Иногда бывает полезно указывать имя сервера в переменной, но следует учитывать, что фигурные скобки имеют специальное значение для переменных в строках в двойных кавычках, поэтому открывающую скобку следует предварять слешем, например \{$SERVER/ pop3:110}INBOX.

Специальное имя INBOX обозначает основной ящик пользователя и папку входящих сообщений. Если имя ящика включает дополнительные символы помимо стандартных латинских символов, то имя предварительно нужно закодировать функцией imap_utf7_encode(). Разделителем иерархии почтовых ящиков обычно является слеш, но для некоторых серверов им также может быть точка.

При помощи аргументов username и password указываются имя и пароль пользователя.

В аргументе flags указываются параметры открытия ящика в виде битовой маски. Эти параметры приведены в следующем списке.

  • OP_READONLY - открытие ящика для чтения
  • OP_ANONYMOUS - не использовать разделы новостей .newsrc. Применяется только для NNTP.
  • OP_HALFOPEN - применяется для имен IMAP и NNTP, если необходимо осуществить подключение без открытия ящика.
  • CL_EXPUNGE - автоматически удалить ящик при его закрытии. См. также imap_delete() и imap_expunge().

Для подключения к серверу IMAP, использующему на локальной машине порт 143, можно использовать следующий вызов:

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

Для подключения к серверу POP3, использующему на локальной машине порт 110, используется следующий вызов:

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

Для подключения к серверу NNTP на локальной машине, использующему порт 119, используется следующий вызов:

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

Следующий пример демонстрирует подключение к серверу IMAP your.imap.host и вывод имеющихся ящиков и сообщений для пользователя username.

$mbox = imap_open ("{your.imap.host:143}", "username", "password");
echo "<p><h1>Ящики Mailboxes</h1>\n";
$folders = imap_listmailbox ($mbox, "{your.imap.host:143}", "*");

if ($folders == FALSE)   echo "Ошибка ящиков не обнаружено <br>\n";
else 
   while (list ($key, $val) = each ($folders)) 
      echo "\t $val <br>\n";
echo "<p><h1>Сообщения в INBOX</h1>\n";
$headers = imap_headers ($mbox);

if ($headers == FALSE) {   echo "Ошибка - сообщений нет <br>\n";  }
else 
   while (list ($key,$val) = each ($headers)) 
      echo "\t $val <br>\n";
imap_close($mbox);

После работы этого кода на экран будут выведены следующие строки:

Ящики Mailboxes 
   {localhost:143}linnn/igf<br>
   {localhost:143}linnn<br>
   {localhost:143}INBOX<br>
Сообщения в INBOX
   1)13-May-2001 Имя отправителя   Заголовок (1621 chars)<br>

imap_reopen. Переподключение и выбор другого ящика

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

Функция аналогична imap_open(), но она не создает новый дескриптор подключения, а использует уже существующий дескриптор imap_stream. Имя пользователя и его пароль не изменяются. В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

imap_close. Отключение от сервера

int imap_close (int imap_stream [, int flags])

Функция закрывает поток подключения, связанный с дескриптором imap_stream. Если в аргументе flags указывается значение CL_EXPUNGE, то при закрытии ящика из него автоматически удаляются все сообщения, помеченные на удаление.

imap_ping. Проверка активности подключения 

int imap_ping (int imap_stream)

Функция возвращает значение TRUE, если подключение все еще действительно. Если оно разорвано, то возвращается значение FALSE.

Вызов функции может использоваться для обнаружения свежих сообщений и для поддержания активности связи с серверами, разрывающими связь через определенный промежуток времени бездействия. Но если учитывать, что время тайм-аута сценария обычно не превышает минуты, а время разрыва связи наступает через сравнительно длительный период, то едва ли эта функция будет полезна при работе веб-сценариев.

imap_listmailbox. Получение списка почтовых ящиков

array imap_listmailbox (int imap_stream, string ref, string pattern)

Функция возвращает массив имен почтовых ящиков. Аргументы рассматривались в описании функции imap_getmailboxes(). 

$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$list = imap_listmailbox($mbox,"{your.imap.host}","*");

if(is_array($list)) {
   reset($list);
   while (list($key, $val) = each($list))
      print imap_utf7_decode($val)."<br>\n";
}
else
   print "imap_listmailbox failed: ".imap_last_error()."\n";
imap_close($mbox);

imap_getmailboxes. Получение описания почтовых ящиков

array imap_getmailboxes (int imap_stream, string ref, string pattern)

Функция возвращает массив объектов, содержащих описания каждого ящика. Каждый объект имеет три атрибута, в которых указывается полное имя ящика name, разделитель иерархии ящиков delimiter и битовое поле attributes, которое может состоять из компонентов, перечисленных в следующем списке:

  • LATT_NOINFERIORS (1) - ящик не имеет вложенных ящиков.
  • LATT_NOSELECT (2) - контейнер, который нельзя открыть.
  • LATT_MARKED (4) - ящик маркирован. Используется только с параметром UW-IMAPD.
  • LATT_UNMARKED (8) - ящик маркирован. Используется только с параметром UW-IMAPD.

Имена ящиков могут содержать символы национальных алфавитов из набора ASCII, которые могут быть закодированы и затем декодированы функцией imap_ utf7_decode().

Аргумент ref должен содержать обычную спецификацию сервера, как в функции imap_open(), а аргумент pattern указывает, с какого ящика следует начинать перебор значений, а также шаблон для возвращаемых ящиков.

В аргументе pattern могут быть указаны два специальных значения. Символ звездочки означает, что следует возвращать всю иерархию ящиков, а символ процента заставляет функцию возвращать только текущий иерархический уровень без вложенных ящиков.

Пример использования функции:

$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$list = imap_getmailboxes($mbox,"{your.imap.host}","*");

if(is_array($list)) {
   print_r ($list);
}
else
   print "imap_getmailboxes failed: ".imap_last_error()."\n";
imap_close($mbox);

См. также imap_getsubscribed().

imap_createmailbox. Создание почтового ящика

int imap_createmailbox (int imap_stream, string mbox)

Функция предназначена для создания новых почтовых ящиков. Имя создаваемого ящика указывается в аргументе mbox. Имена, содержащие национальные символы, должны кодироваться функцией imap_utf7_encode().

В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

См. также imap_renamemailbox(), imap_deletemailbox() и imap_open().

Пример использования функции:

$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$name1 = "newbox";
$name2 = imap_utf7_encode("мой личный ящик");

if(@imap_createmailbox($mbox,
      imap_utf7_encode("{your.imap.host}INBOX/$name1"))) {
   $status = @imap_status($mbox,"{your.imap.host}INBOX/$name1",SA_ALL);
   if($status) {
      echo  "Статус нового ящика '$name1': <br>\n",
         "Messages:   ". $status->messages   ."<br>\n",
         "Recent:     ". $status->recent     ."<br>\n",
         "Unseen:     ". $status->unseen     ."<br>\n",
         "UIDnext:    ". $status->uidnext    ."<br>\n",
         "UIDvalidity:". $status->uidvalidity."<br>\n";
      if(imap_renamemailbox($mbox,"{your.imap.host}INBOX/$name1",
            "{your.imap.host}INBOX/$name2")) {
         echo "Ящик '$name1' переименован в '$name2'<br>\n";
   }
   else{
      print "imap_renamemailbox failed: ".imap_last_error()."<br>\n";
   }
}

else{
   print  "imap_status failed: ".imap_last_error()."<br>\n";
}
if(@imap_deletemailbox($mbox,"{your.imap.host}INBOX/$name2")) {
   print "new mailbox removed <br>\n";
}
else {
   print  "imap_deletemailbox failed: ".
      implode("<br>\n",imap_errors())."<br>\n";
}
}

else {
   print  "could not create new mailbox: ".
      implode("<br>\n",imap_errors())."<br>\n";
}
imap_close($mbox);

imap_renamemailboximap_renamemailbox. Переименование ящика

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

Функция позволяет переименовать существующий ящик. Имя ящика задается аргументом old_mbox, а его новое имя указывается в параметре new_mbox. Формат этих аргументов рассматривался в описании функции imap_open().

В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

См. также imap_createmailbox(), imap_deletemailbox(), imap_open().

imap_deletemailbox. Удаление почтового ящика

int imap_deletemailbox (int imap_stream, string mbox)

Функция позволяет удалить существующий ящик. Имя ящика задается аргументом mbox. В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

См. также imap_createmailbox(), imap_renamemailbox() и imap_open().

imap_check. Проверка текущего ящика

object imap_check (int imap_stream)

Функция возвращает объект, содержащий информацию о текущем почтовом ящике. При возникновении ошибки возвращается значение FALSE.

Свойства возвращаемого объекта перечислены в следующем списке:

  • Date - время последнего доступа к содержимому ящика.
  • Driver - протокол доступа к ящику.
  • Mailbox - полное имя почтового ящика.
  • Nmsgs - общее количество сообщений в ящике.
  • Recent - количество новых сообщений в ящике.

Пример использования этой функции:

$mbox = imap_open("{localhost}","igor","igx324879",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
print_r(imap_check ($mbox));
imap_close($mbox);

В результате работы этого кода на экран будут выведены следующие строки:

stdClass Object
(
   [Date] => Sun, 13 May 2008 14:31:38 +0400 (Московское время (лето))
   [Driver] => imap
   [Mailbox] => {igor:143/imap/user="igor"}<no_mailbox>
   [Nmsgs] => 0
   [Recent] => 0
)

imap_status. Получение статуса указанного ящика

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

Функция возвращает объект, содержащий информацию о почтовом ящике с именем mailbox. При возникновении ошибки возвращается значение FALSE. Набор свойств возвращаемого объекта варьируется в зависимости от указанного значения аргумента options. Возможные значения этого параметра приведены в следующем списке:

  • SA_MESSAGES - возвратить в status->messages общее количество сообщений в ящике.
  • SA_RECENT - возвратить в status->recent количество новых сообщений.
  • SA_UNSEEN - возвратить в status->unseen количество непрочитанных сообщений.
  • SA_UIDNEXT - возвратить в status->uidnext номер uid для следующего нового сообщения.
  • SA_UIDVALIDITY - в status->uidvalidity возвратить константу действительности uid ящика.
  • SA_ALL - возвращаются все перечисленные значения. Объект также содержит свойство status->flags, отражающее в объединенном битовом поле набор параметров создания.

Пример использования функции:

$mbox = imap_open("{your.imap.host}","username","password",OP_HALFOPEN)
      || die("can't connect: ".imap_last_error());
$status = imap_status($mbox,"{your.imap.host}INBOX",SA_ALL);

if($status) {
   print_r($status);
}
else
   print "imap_status failed: ".imap_lasterror()."\n";
imap_close($mbox);

imap_mailboxmsginfo. Получение информации о текущем ящике

object imap_mailboxmsginfo (int imap_stream)

Функция сходна с imap_status(), но она также вычисляет объем всех сообщений, находящихся в ящике. Функция возвращает объект, свойства которого перечислены в следующем списке:

  • Date - время последней модификации.
  • Driver - протокол доступа к ящику.
  • Mailbox - имя почтового ящика.
  • Nmsgs - количество сообщений.
  • Recent - количество полученных сообщений.
  • Unread - количество непрочитанных сообщений.
  • Deleted - количество удаленных сообщений.
  • Size - размер почтового ящика.

Пример использования функции:

<?php
$mbox = imap_open("{your.imap.host}INBOX","username", "password")
      || die("can't connect: ".imap_last_error());
$check = imap_mailboxmsginfo($mbox);

if($check) {
   print "Date: "    . $check->Date    ."<br>\n" ;
   print "Driver: "  . $check->Driver  ."<br>\n" ;
   print "Mailbox: " . $check->Mailbox ."<br>\n" ;
   print "Messages: ". $check->Nmsgs   ."<br>\n" ;
   print "Recent: "  . $check->Recent  ."<br>\n" ;
   print "Unread: "  . $check->Unread  ."<br>\n" ;
   print "Deleted: " . $check->Deleted ."<br>\n" ;
   print "Size: "    . $check->Size    ."<br>\n" 

}
else {
   print "imap_check() failed: ".imap_last_error(). "<br>\n";
}
imap_close($mbox);
?>

imap_num_msg. Получение количества сообщений в текущем ящике 

int imap_num_msg (int imap_stream)

Функция возвращает количество сообщений, хранящихся в почтовом ящике.

imap_num_recent. Получение количества новых сообщений в текущем ящике

int imap_num_recent (int imap_stream)

Функция возвращает количество новых сообщений в почтовом ящике.

imap_listsubscribed. Получение списка активных ящиков

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

У пользователя может быть сложная структура папок почтового аккаунта, но, как правило, для синхронизации и отображения в программе почтового клиента выбираются только несколько ящиков, а остальные не затрагиваются.

Функция возвращает в массиве имена папок, выбранных для синхронизации. Она аналогична функции imap_listmailbox().

imap_getsubscribed. Получение описания активных ящиков

array imap_getsubscribed (int imap_stream, string ref, string pattern)

Функция аналогична imap_getmailboxes(), но она возвращает имена только тех ящиков, которые были выбраны для синхронизации.

imap_subscribe. Сделать ящик активным 

int imap_subscribe (int imap_stream, string mbox)

Указанный ящик в дальнейшем будет использоваться для синхронизации. В случае успешного выполнения возвращается значение TRUE. При возникновении ошибки возвращается значение FALSE.

imap_unsubscribe. Сделать ящик неактивным

int imap_unsubscribe (int imap_stream, string mbox)

Функция делает ящик неактивным, и в дальнейшем он не будет использоваться для синхронизации.

imap_search. Поиск в текущем ящике

array imap_search (int imap_stream, string criteria, int flags)

Функция возвращает список почтовых ящиков, в которых было обнаружено соответствие критерию, указанному в аргументе criteria. В строке критерия указываются искомые слова, разделенные пробелами. Если необходимо искать фразу, то ее следует заключать в двойные кавычки. Перед набором слов указывается имя поля, в котором следует производить поиск. Можно также указать флаги просматриваемых сообщений. Применяемые флаги перечислены в следующем списке:

  • ALL - все сообщения, содержащие перечисленные слова.
  • ANSWERED - только сообщения, на которые был выслан ответ.
  • BCC "string" - искать строку "string" в поле Bcc.
  • BEFORE "date" - сообщения с датой, меньшей, чем "date".
  • BODY "string" - сообщения, содержащие в своем теле строку "string".
  • CC "string" - искать строку "string" в поле Cc.
  • DELETED - удаленные сообщения.
  • FLAGGED - сообщения со статусом "Важное".
  • FROM "string" - искать строку "string" в поле From.
  • KEYWORD "string" - искать сообщения, содержащие слово "string".
  • NEW - просматривать только новые сообщения.
  • OLD - просматривать только старые сообщения.
  • ON "date" - просматривать сообщения с датой "date".
  • RECENT - просматривать свежие сообщения, имеющие флаг RECENT.
  • SEEN - просматривать прочитанные сообщения, имеющие флаг SEEN.
  • SINCE "date" - просматривать сообщения, полученные позже "date".
  • SUBJECT "string" - искать слово "string" в поле темы Subject.
  • TEXT "string" - искать сообщения, содержащие текст "string".
  • TO "string" - искать сообщения, содержащие строку "string" в поле адресата To.
  • UNANSWERED - просматривать сообщения, на которые не был написан ответ.
  • UNDELETED - просматривать не удаленные сообщения.
  • UNFLAGGED - просматривать сообщения без флагов.
  • UNKEYWORD "string" - искать сообщения, не содержащие слово "string".
  • UNSEEN - поиск вести в еще не просмотренных сообщениях.

Чтобы найти все сообщения от отправителя Peter, на которые не был выслан ответ, указывается строка UNANSWERED FROM Peter. Поиск не чувствителен к регистру. Приведенный список критериев взят из исходного текста библиотеки и может быть не полным. Более подробная информация приведена в документе RFC2060, section 6.4.4.

Допустимым значением аргумента flags является SE_UID. Оно указывает, что вместо относительных последовательных номеров сообщений следует возвращать уникальные идентификаторы UID.

imap_scanmailbox. Поиск текста в сообщениях 

array imap_scanmailbox (int imap_stream, string ref, string pattern, string content)

Функция подобна imap_listmailbox(), но она возвращает имена только тех ящиков, которые содержат в себе строку content.

imap_fetch_overview. Получение описания сообщений

array imap_fetch_overview (int imap_stream, string sequence [, int flags])

Функция возвращает в массиве объекты, содержащие информацию о сообщениях, номера которых перечислены в строке sequence. Эта строка должна содержать номер сообщения или номера нескольких сообщений через запятую, без пробелов. Можно также указать диапазон номеров, использовав двоеточие. Если в значении аргумента указана константа FT_UID, то это указывает на то, что номера являются уникальными идентификаторами UID.

Свойства объектов массива перечислены в следующем списке:

  • subject - тема сообщения.
  • from - отправитель.
  • date - дата отправки.
  • message_id - идентификатор сообщения.
  • references - ссылки на message_id.
  • size - размер в байтах.
  • uid - уникальный идентификатор сообщения UID в ящике.
  • msgno - порядковый номер сообщения в ящике.
  • recent - флаг "новое сообщение".
  • flagged - флаг "важное сообщение".
  • answered - на сообщение написан ответ.
  • deleted - сообщение выбрано для удаления.
  • seen - прочитанное сообщение
  • draft - флаг "черновик".

Пример использования функции:

$mbox = imap_open("{your.imap.host:143}","username","password")
      || die("can't connect: ".imap_last_error());
$overview = imap_fetch_overview($mbox,"2,4:6",0);

if(is_array($overview)) { print_r($overview); }
imap_close($mbox);

В результате работы этого кода на экран будет выведена следующая информация:

Array
(
   [0] => stdClass Object
      (
      [subject] => Поздравление
      [from] => IG <ig@igor.>
      [date] => Sun, 13 May 2001 01:41:00 +0400
      [message_id] => <000801c0db2c$3c46a2c0$0100007f@igor>

      [size] => 1621
      [uid] => 289703661
      [msgno] => 1
      [recent] => 0
      [flagged] => 0
      [answered] => 0
      [deleted] => 0
      [seen] => 1
      [draft] => 0
      )

imap_headers. Получение списка сообщений текущего ящика 

array imap_headers (int imap_stream)

Функция возвращает массив, содержащий заголовки имеющихся сообщений. Сообщения вложенных папок не просматриваются.

imap_headerinfo. Просмотр заголовка сообщения 

object imap_headerinfo (int imap_stream, int msg_number [, int fromlength [, int subjectlength [, string defaulthost]]])

Функция возвращает объект, содержащий различную информацию о сообщении. В качестве примера можно привести следующий вызов функции:

$mbox = imap_open ("\{$SERVER/pop3:110}INBOX", "igor7", "igx321"); 
print_r(imap_header($mbox,1));

В результате работы этого кода на экран будут выведены следующие строки:

stdClass Object
(
   [date] => Sun, 13 May 2005 01:41:00 +0400
   [Date] => Sun, 13 May 2005 01:41:00 +0400
   [subject] => Послание
   [Subject] => Послание
   [message_id] => <000801c0db2c$3c46a2c0$0100007f@igor>

   [toaddress] => igor@localhost
   [to] => Array
      (
      [0] => stdClass Object
         (
         [mailbox] => igor
         [host] => localhost
         )
      )
   [fromaddress] => IG <ig@igor.>
   [from] => Array
      (
      [0] => stdClass Object
         (
         [personal] => IG
         [mailbox] => ig
         [host] => igor.
         )
      )
   [reply_toaddress] => IG <ig@igor.>

   [reply_to] => Array
      (
      [0] => stdClass Object
         (
         [personal] => IG
         [mailbox] => ig
         [host] => igor.
         )
      )
   [senderaddress] => IG <ig@igor.>
   [sender] => Array
      (
      [0] => stdClass Object
         (
         [personal] => IG
         [mailbox] => ig
         [host] => igor.
         )
      )
   [Recent] => N
   [Unseen] =>

   [Flagged] =>
   [Answered] =>
   [Deleted] =>
   [Draft] =>
   [Msgno] =>    1
   [MailDate] => 13-May-2005 01:41:00 +0400
   [Size] => 1581
   [udate] => 989703660
)

Структура и формат записей определяются реализацией серверного интерфейса и могут сильно различаться для различных систем. В большинстве случаев для сообщений протоколов IMAP, POP3 и NNTP форматы информационных полей идентичны.

Для сообщений news-серверов дополнительно возвращается свойство newsgroup.

Пары полей date, Date и subject, Subject обычно совпадают. В message_id хранится уникальный хеш сообщения, а в Msgno - относительный порядковый номер. В записях Size и udate возвращаются, соответственно, размер сообщения в байтах и время в формате UNIX Timestamp.

В большинстве случаев адреса fromaddress, reply_toaddress и senderaddress совпадают. Если у сообщения имеется поле Cc, то также возвращается адрес ccaddress.

imap_sort. Сортировка заголовков

array imap_sort (int stream, int criteria, int reverse, int options)

Возвращает массив номеров сообщений, сортированных по критерию. Если в аргументе reverse указывается значение TRUE, то сортировка проводится в обратном порядке.

Возможные значения аргумента criteria приведены в следующем списке:

  • SORTDATE - сортировка по дате сообщения.
  • SORTARRIVAL - сортировка по дате получения.
  • SORTFROM - сортировка по первому адресу в поле From.
  • SORTSUBJECT - сортировка по строке темы в поле Subject.
  • SORTTO - сортировка по первому адресу в поле To.
  • SORTCC - сортировка по первому адресу в поле получателей копии Nn.
  • SORTSIZE - сортировка по размеру сообщения.

Флаги options аргумента могут содержать следующие значения:

  • SE_UID - возвращать уникальный идентификатор сообщения UID вместо его порядкового номера.
  • SE_NOPREFETCH - не выполнять с сообщением предварительные манипуляции.

imap_fetchstructure. Получение полной информации о сообщении

object imap_fetchstructure (int imap_stream, int msg_number [, int flags])

Информация возвращается в объекте, который описывает формат и структуру сообщения в текущем ящике, указанного порядковым номером msg_number. Если в аргументе flags указывается значение FT_UID, то это свидетельствует о том, что в аргументе msg_number указан не номер сообщения, а его идентификатор UID.

Поля объекта приведены в следующем списке:

  • type - тип основного тела сообщения.
  • encoding - кодировка тела сообщения.
  • ifsubtype - принимает значение TRUE, если имеется вложенный тип.
  • subtype - вложенный тип MIME.
  • ifdescription - принимает значение TRUE, если есть строка описания сообщения.
  • description - строка описания.
  • ifid - принимает значение TRUE, если имеется строка идентификации.
  • id - строка идентификации.
  • lines - размер в строках.
  • bytes - размер в байтах.
  • ifdisposition - принимает значение TRUE, если есть строка размещения.
  • disposition - строка размещения.
  • ifdparameters - принимает значение TRUE, если есть массив дополнительных параметров.
  • dparameters - массив дополнительных параметров.
  • ifparameters - принимает значение TRUE, если существует массив обычных параметров.
  • parameters - массив параметров MIME.
  • parts - массив объектов, описывающих каждую часть сообщения.

Значения типа type основного тела перечислены в следующем списке:

  • 0 - простой текст.
  • 1 - составное сообщение.
  • 2 - простое сообщение.
  • 3 - приложение.
  • 4 - аудиосодержимое.
  • 5 - изображение.
  • 6 - видео.
  • 7 - другое.

Типы кодировки encoding перечислены в следующем списке:

  • 0 - 7BIT.
  • 1 - 8BIT.
  • 2 - BINARY.
  • 3 - BASE64.
  • 4 - QUOTED-PRINTABLE.
  • 5 - другие кодировки.

Для простого сообщения искомый объект может выглядеть следующим образом:

stdClass Object
(
   [ifsubtype] => 1
   [subtype] => PLAIN
   [ifdescription] => 0
   [ifid] => 0
   [lines] => 2
   [bytes] => 41
   [ifdisposition] => 0
   [ifdparameters] => 0
   [ifparameters] => 0
   [parameters] => stdClass Object
      (
      )
)

Для сложного сообщения объект будет выглядеть несколько сложнее:

stdClass Object
(
   [type] => 1
   [ifsubtype] => 1
   [subtype] => ALTERNATIVE
   [ifdescription] => 0
   [ifid] => 0
   [ifdisposition] => 0
   [ifdparameters] => 0
   [ifparameters] => 1
   [parameters] => Array
      (
         [0] => stdClass Object
            (
            [attribute] => boundary
            [value] => ----=_NextPart_000_0005_01C0DB4D.C33837A0
            )
        )
   [parts] => Array
      (
         [0] => stdClass Object
            (
            [encoding] => 4
            [ifsubtype] => 1
            [subtype] => PLAIN
            [ifdescription] => 0
            [ifid] => 0
            [lines] => 5
            [bytes] => 59
            [ifdisposition] => 0
            [ifdparameters] => 0
            [ifparameters] => 1
            [parameters] => Array
               (
               [0] => stdClass Object
                  (
                  [attribute] => charset
                  [value] => koi8-r
                  )
               )
             )
          [1] => stdClass Object
             (
             [encoding] => 4
             [ifsubtype] => 1
             [subtype] => HTML
             [ifdescription] => 0
             [ifid] => 0
             [lines] => 14
             [bytes] => 547
             [ifdisposition] => 0
             [ifdparameters] => 0
             [ifparameters] => 1
             [parameters] => Array
                (
                [0] => stdClass Object
                   (
                   [attribute] => charset
                   [value] => koi8-r
                   )
                )
             )
      )
)

imap_fetchheader. Получение заголовка сообщения

string imap_fetchheader (int imap_stream, int msgno, int flags)

Функция возвращает полный заголовок формата RFC822 сообщения с номером msgno из выбранного ящика.

Возможные значения аргумента flags указаны в следующем списке:

  • FT_UID - в аргументе msgno указан уникальный идентификатор UID.
  • FT_INTERNAL - возвращать текст как есть, а не в формате CRLF.
  • FT_PREFETCHTEXT - (RFC822). Одновременно получается текст сообщения, что сокращает общую длительность подключений IMAP. Полученный текст сохраняется в локальном буфере на время подключения.

imap_body. Получение сообщения

string imap_body (int imap_stream, int msg_number [, int flags])

Функция возвращает тело сообщения с номером msg_number из указанного ящика. Возможные значения аргумента flags перечислены в следующем списке:

  • FT_UID - в аргументе msgno указан уникальный идентификатор UID.
  • FT_PEEK - не устанавливать флаг сообщения Seen, если он еще не установлен.
  • FT_INTERNAL - возвращать текст как есть, а не в формате CRLF.

Функция возвращает полную точную копию сообщения. С ее помощью можно прочитать простые сообщения. Для составных сообщений функция может вернуть строку This is a multi-part message in MIME format. Чтобы извлечь отдельные части сообщения и обработать их согласно указанному типу MIME, нужно воспользоваться функциями imap_fetch_structure() и imap_fetch_body().

imap_fetchbody. Получение части сообщения

string imap_fetchbody (int imap_stream, int msg_number, string part_number [, flags flags])

Функция возвращает часть тела сообщения с номером msg_number из выбранного ящика. Спецификация указания перечисления номеров секций в аргументе part_ number определяется IMAP4.

Возможные значения аргумента flags перечислены в следующем списке:

  • FT_UID - в аргументе msgno указан уникальный идентификатор UID.
  • FT_PEEK - не устанавливать флаг сообщения Seen, если он еще не установлен.
  • FT_INTERNAL - возвращать текст как есть, а не в формате CRLF.

Для сложного сообщения, структура которого приведена в примере функции imap_fetchstructure(), содержание частей может быть усложненным.

Основная часть сообщения, которая возвращается вызовом imap_fetchbody ($m,1,0), выглядит следующим образом:

X-F: <ig@igor.> Sun May 13 01:41:00 2003
Received: from igor [127.0.0.1] by igor.
   (SMTPD32-6.06 EVAL) id ADEC10316; Sun, 13 May 2001 01:41:00 +0400
Message-ID: <000801c0db2c$3c46a2c0$0100007f@igor>
From: "IG" <ig@igor.>
To: <igor@localhost>
Subject: Приветствие
Date: Sun, 13 May 2001 01:41:00 +0400
MIME-Version: 1.0
Content-Type: multipart/alternative;
   boundary="----=_NextPart_000_0005_01C0DB4D.C33837A0"
X-Priority: 3
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook Express 5.00.2919.6700
X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2919.6700
X-RCPT-TO: <igor@localhost>
X-UIDL: 289703661
Status: U

Первая вложенная часть может быть получена при помощи вызова imap_ fetchbody($m,1,1). Выглядит она следующим образом:

Привет.
У нас все хорошо.
Пока.

Вторая вложенная часть, возвращенная вызовом imap_fetchbody($m,1,2), будет выглядеть сложнее:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META content="text/html; charset=koi8-r" http-equiv="Content-Type">
<META content="MSHTML 5.00.2920.0" name="GENERATOR">
<STYLE></STYLE>

</HEAD>
<BODY bgColor=#ffffff>
<DIV><FONT face="Arial Cyr" size=2> Привет.</FONT></DIV>
<DIV><FONT face="Arial CYR" size=2> У нас все хорошо.</FONT></DIV>

<DIV><FONT face="Arial CYR" size=2> Пока. </FONT></DIV>
</BODY></HTML>

imap_uid. Получение UID сообщения из порядкового номера 

int imap_uid (int imap_stream, int msgno)

Функция возвращает уникальный идентификатор сообщения UID. Он отличается от обычного порядкового номера, потому что номера перевычисляются при удалении сообщений. Вызов функции предельно прост:

echo imap_uid($mbox,1);  // выводит, например, 289703661

imap_msgno. Получение порядкового номера сообщения из UID

int imap_msgno (int imap_stream, int uid)

Действие функции обратно imap_uid().

imap_setflag_full. Установка флагов сообщения 

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

Функция позволяет установить флаги для выбранного сообщения. В аргументе sequence указывается перечисление номеров сообщений, для которых необходимо установить флаги, указанные в аргументе flag. Флаги обозначаются, как \\Seen, \\Answered, \\Flagged, \\Deleted, \\Draft и \\Recent.

В аргументе options может быть указано значение ST_UID, указывающее на то, что в аргументе sequence указан уникальный идентификатор UID.

Пример использования функции:

$mbox = imap_open("{your.imap.host:143}","username","password")
      || die("can't connect: ".imap_last_error());

if (imap_setflag_full($mbox,"2,4,15:19,23","\\Seen \\Flagged"))
   print "Флаги установлены\n";
imap_close($mbox);

imap_clearflag_full. Сброс флагов сообщения 

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

Действие функции противоположно imap_setflag_full(). Она сбрасывает флаги у выбранных сообщений.

imap_delete. Маркировка сообщения как удаленного

int imap_delete (int imap_stream, int msg_number [, int flags])

В аргументе msg_number указывается номер сообщения, а в параметре flags при значении FT_UID указывается, является ли номер идентификатором. Сообщения, помеченные к удалению, остаются в ящике, пока не будет вызвана функция imap_ expunge() или подключение с установленным флагом CL_EXPUNGE не будет закрыто функцией imap_close().

Пример использования функции:

$mbox = imap_open ("{your.imap.host}INBOX", "username", "password")
      || die ("can't connect: " . imap_last_error());
$check = imap_mailboxmsginfo ($mbox);
print "Сообщений до удаления: ". $check->Nmsgs . "<br>\n" ;
imap_delete ($mbox, 1);
$check = imap_mailboxmsginfo ($mbox);
print "Сообщений после удаления: ".$check->Nmsgs."<br>\n" ;
imap_expunge ($mbox);
$check = imap_mailboxmsginfo ($mbox);
print " Сообщений после expunge(): ".$check->Nmsgs."<br>\n" ;
imap_close ($mbox);

imap_undelete. Восстановление удаленного сообщения

int imap_undelete (int imap_stream, int msg_number)

Функция снимает флаг удаления с сообщения с номером msg_number. Этот флаг ранее мог быть установлен функциями imap_delete(), imap_mail_move(), или imap_ setflag_full().

imap_expunge. Удаление сообщений, помеченных к удалению

int imap_expunge (int imap_stream)

Функция полностью удаляет из ящика сообщения, имеющие флаг \\Deleted, который может быть установлен функциями imap_delete(), imap_mail_move() или imap_ setflag_full().

imap_mail_copy. Копирование сообщения в ящик

int imap_mail_copy (int imap_stream, string msglist, string mbox [, int flags])

Перечисление номеров копируемых сообщений указывается в строковом аргументе msglist. Их следует перечислять без пробелов через запятую, диапазоны указываются знаком двоеточия. Функция копирует выбранное сообщение в указанный ящик.

Ящик назначения, указываемый в аргументе mbox, указывается без имени сервера.

В аргументе flags можно указывать битовую маску из следующих констант:

  • CP_UID - номера являются уникальными идентификаторами UID.
  • CP_MOVE - удалять сообщения после копирования.

Вызов функции выглядит достаточно просто:

imap_mail_copy($m, "1,3:5","INBOX/Текущие")

imap_mail_move. Перемещение сообщения в ящик

int imap_mail_move (int imap_stream, string msglist, string mbox [, int flags])

Функция аналогична следующему вызову:

imap_mail_copy(imap_stream, msglist, mbox, flags | CP_MOVE )

imap_alertsimap_alerts. Получение извещений IMAP

array imap_alerts (void)

Функция возвращает массив, содержащий все извещения, посланные сервером от начала подключения или после прошлого вызова данной функции.

imap_mime_header_decode. Декодирование элементов MIME- заголовков

array imap_header_decode (string text)

Функция декодирует расширенные заголовки, посланные не в виде текста ASCII. Декодированные элементы возвращаются в массиве объектов, каждый из которых содержит значения "charset" и "text", в которых указываются кодировка и содержимое текста. Если заголовки не были закодированы, то значение элемента "charset" будет равно "default".

Пример использования функции:

$text="=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>";
print_r(imap_mime_header_decode($text));

В результате работы этого кода на экран будут выведены следующие строки:

Array(
   [0] => stdClass Object (
      [charset] => ISO-8859-1
      [text] => Keld Jorn Simonsen
   )
   [1] => stdClass Object (
      [charset] => default
      [text] =>  <keld@dkuug.dk>

   )
)

imap_mail_compose. Создание сообщения MIME по шаблону

string imap_mail_compose (array envelope, array body)

Функция создает новое сообщение:

<?php
$envelope["from"]="musone@afterfive.com";
$envelope["to"]="musone@darkstar";
$envelope["cc"]="musone@edgeglobal.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_append. Создание сообщения в ящике 

int imap_append (int imap_stream, string mbox, string message [, string flags])

Функция позволяет создавать сообщения в выбранном ящике. В аргументе message содержится текст сообщения, включая текст заголовка. Для многих серверов необходимо обозначать конец строк парой символов \r\n.

В аргументе flags можно указать флаги, присваиваемые сообщению.

Пример использования функции:

$stream = imap_open("{your.imap.host}INBOX.Drafts","username", "password");
$check = imap_check($stream);
print "Сообщений было: ". $check->Nmsgs."\n";
imap_append($stream,"{your.imap.host}INBOX.Drafts"

                   ,"From: me@my.host\r\n"
                   ."To: you@your.host\r\n"
                   ."Subject: test\r\n"
                   ."\r\n"
                   ."this is a test message, please ignore\r\n",
                   "\\Flagged \\Draft");
$check = imap_check($stream);
print "Сообщений стало: ". $check->Nmsgs."\n";
imap_close($stream);

Вспомогательные функции

imap_last_error. Получение описания последней ошибки

string imap_last_error (void)

Функция возвращает строку, содержащую полное описание ошибки IMAP, произошедшей в ходе исполнения скрипта. Стек сообщений не изменяется, и повторный вызов функции возвратит то же самое значение, если не произошло других ошибок.

imap_errors. Получение всех возникших ошибок

array imap_errors (void)

Функция возвращает массив, содержащий строки описания ошибок IMAP, произошедших от начала подключения или с момента последнего вызова данной функции. Вызов функции полностью очищает стек ошибок.

imap_rfc822_write_addressimap_rfc822_write_address. Форматирование строки адреса

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

Функция возвращает строку электронного адреса, сформированную из заданных значений, согласно правилам, указанным в RFC822. Вызов функции достаточно прост:

print imap_rfc822_write_address("ig","php.net","Igor Grigin");      
// выведет: Igor Grigin <ig@php.net>

imap_rfc822_parse_adrlist. Интерпретация адреса

array imap_rfc822_parse_adrlist (string address, string default_host)

Исходная строка с перечислением почтовых адресов, записанных в формате RFC822, указывается в аргументе address. Аргумент содержит имя хоста, добавляемое к адресу. Функция возвращает массив объектов, свойства которых указаны в следующем списке:

  • mailbox - имя ящика.
  • host - имя хоста.
  • personal - личное имя.
  • adl - доменный разделитель.

Пример использования функции:

$address_string = "Igor Grigin <ig@my.domain.net>,
   postmaster@somedomain.net, root";
$address_array = imap_rfc822_parse_adrlist($address_string,"our.net");

if(! is_array($address_array)) die("somethings wrong\n");
print_r($address_array);

В результате работы этого кода на экран будут выведены следующие строки:

Array(
   [0] => stdClass Object (
      [mailbox] => ig
      [host] => my.domain.net
      [personal] => Igor Grigin
   )
   [1] => stdClass Object (
      [mailbox] => postmaster
      [host] => somedomain.net
   )
   [2] => stdClass Object (
      [mailbox] => root
      [host] => our.net
   )
)

imap_rfc822_parse_headers. Интерпретация заголовков из строки

object imap_rfc822_parse_headers (string headers [, string defaulthost])

Функция сходна с imap_header(), но информацию она получает не от сервера IMAP, а из строки headers.

imap_utf7_decode. Декодирование строки UTF-7 

string imap_utf7_decode (string text)

Функция возвращает оригинальную строку после декодирования. Эта кодировка часто используется для адресов почтовых ящиков, содержащих национальные символы. Функция использует модифицированный алгоритм, описанный в RFC 2060, section 5.1.3. Устаревший алгоритм был описан в RFC1642.

Ещё примеры отправки почты на PHP

Читать дальше: Оптимизация PHP программ


.