В PHP есть несколько десятков функций объединённых в один модуль для работы с почтовыми серверами по протоколу IMAP. Но сделаны они весьма ужасно. Ещё бы, ведь они появились ещё в PHP 4 и содержат в себе все самые худшие практики архитектуры и дизайна которые только можно было придумать. Одной из проблем является то, что эта библиотека оперирует двумя видами идентификаторов писем: в одном случае это $msg_number, а в другом — $uid. Причём, какого либо внятного объяснений различий в официальной документации не приводится.
$uid — UID сообщения в ящике, а $msg_number — номер сообщения, это всё, что есть в документации. Но в чём же между ними разница? Зачем нужны два вида идентификаторов? Непонятно. Возможно, нужно изучать спецификацию IMAP протокола для получения просветления. В результате чего может возникать путаница, когда вместо $msg_number функции был передан $uid, в лучшем случае вы получите ошибку:
Warning: imap_headerinfo(): Bad message number
А в худшем случае — вы получите содержимое другого письма, задеплоите это в продакшен и узнаете об ошибке когда случится что-то нехорошее!
Ещё больше усугубляет ситуацию то, что часть функций умеет принимать и возвращать оба этих идентификатора. Например, функция imap_fetch_overview возвращает оба идентификатора, причём первый из них под именем msgno! Помимо uid, она возвращает ещё и какой-то message_id! Нужно больше идентификаторов богу идентификаторов!
Например, функция imap_fetchheader по-умолчанию принимает $msg_number, но если третьим параметром указать FT_UID, то в качестве значения $msg_number можно будет передать $uid. Но функция imap_headerinfo принимает только $msg_number и попытка передать ей uid ничем хорошим не закончится!
Также существуют две костыльные функции: imap_uid и imap_msgno, которые конвертируют один вид идентификаторов в другой.