Get messages by UID sequence

src/Mailbox.php

@@ -178,6 +178,30 @@ public function getMessages(ConditionInterface $search = null, int $sortCriteria
         return new MessageIterator($this->resource, $messageNumbers);
     }
 
+    /**
+     * Get message iterator for a sequence
+     *
+     * @param string $sequence Message numbers
+     *
+     * @return MessageIteratorInterface
+     */
+    public function getMessageSequence(string $sequence): MessageIteratorInterface
+    {
+        \imap_errors();
+
+        $overview = \imap_fetch_overview($this->resource->getStream(), $sequence, FT_UID);
+        if (false === $overview) {
+            if (false !== \imap_last_error()) {
+                throw new InvalidSearchCriteriaException(\sprintf('Invalid sequence [%s]', $sequence));
+            }
+
+            $messageNumbers = [];
+        } else {
+            $messageNumbers = array_column($overview, 'uid');
+        }
+        return new MessageIterator($this->resource, $messageNumbers);
+    }
+
     /**
      * Get a message by message number.
      *

src/MailboxInterface.php

@@ -85,6 +85,15 @@ public function clearFlag(string $flag, $numbers): bool;
      */
     public function getMessages(ConditionInterface $search = null, int $sortCriteria = null, bool $descending = false): MessageIteratorInterface;
 
+    /**
+     * Get message iterator for a sequence
+     *
+     * @param string $sequence Message numbers
+     *
+     * @return MessageIteratorInterface
+     */
+    public function getMessageSequence(string $sequence): MessageIteratorInterface;
+
     /**
      * Get a message by message number.
      *

tests/MailboxTest.php

@@ -71,6 +71,15 @@ public function testGetMessages()
         $this->assertSame(3, $aggregateIteratorMethodInc);
     }
 
+    public function testGetMessageSequence()
+    {
+        $inc = 0;
+        foreach ($this->mailbox->getMessageSequence('1:*') as $message) {
+            ++$inc;
+        }
+        $this->assertSame(3, $inc);
+    }
+
     public function testGetMessageThrowsException()
     {
         $message = $this->mailbox->getMessage(999);