Imap Class

Imap connects to an IMAP server over implicit TLS (port 993) by default and authenticates. Unlike Pop3, IMAP is stateful and leaves mail on the server: you select() a mailbox, then search() / fetch() within it. Fetched messages are parsed into the same hash shape as Pop3, plus IMAP identity fields (seq, uid, flags).

fetch / fetch_uid ask for the whole message: every part, every attachment. That is right when you are about to read one and ruinous when you are drawing a list of twenty, where nothing but the sender, the subject and the date is ever shown — a modest inbox costs megabytes and seconds to list.

The fetch_headers* family asks the server for four header lines instead (SUBJECT FROM TO DATE), so a list costs kilobytes. What comes back is parsed by the same code into the same hash, with text_body and html_body simply absent — fetch those when someone opens the message.

rows = mail.fetch_headers_set("100:*")     # one round trip for the whole run
for row in rows
  print("#{row["subject"]} — #{row["bytes"]} bytes, #{row["clips"]} attachment(s)")
end

msg = mail.fetch_uid(rows[0]["uid"])       # the body, only when it is wanted

A headers-only row carries two fields a full fetch does not need:

fetch_headers_range(lo, hi) and fetch_headers_set(set) are one command and one wait for the whole run, where a loop over fetch_headers_uid is one of each per message. A set is digits, ,, : and * — the RFC 3501 sequence-set grammar. Anything else is refused rather than interpolated onto the wire.

Every mutating verb above takes a sequence number, which is a position and moves whenever anything before it is removed. A client that stores messages holds UIDs, so it had to turn each one into a position first with a SEARCH UID n — a whole extra round trip, and an application that answers nothing while it waits. The uid_* methods are the same operations addressed the way the caller already knows how, in one turn instead of two:

mail.uid_mark_seen(4821)
mail.uid_move(4821, "Archive")

criteria is passed straight through as an IMAP search key, so any standard expression works:

mail.uid_search("UNSEEN")                       # unread
mail.search("FROM alice@example.com")           # by sender
mail.search("SINCE 1-Jun-2026 SUBJECT invoice") # combine keys
mail.search("ALL")                              # everything (the default)

Each fetched message is a hash carrying the same fields as Pop3 plus IMAP identity fields (seq, uid, flags). from is a single {name, address} hash (or null); to is an array of them. Missing headers/bodies are null.

parts is every text part with the type it declares, in the order the message carries them. text_body and html_body answer “the plain one” and “the HTML one”, which covers every message there is until one carries a third face: a text/markdown part is text like any other and neither of those two accessors will ever return it. Read parts when you want to prefer the source a message was written in.

{
  "seq":          1,
  "uid":          4821,
  "flags":        ["\\Seen", "\\Answered"],
  "size":         2048,
  "subject":      "Hello from Alice",
  "from":         { "name": "Alice", "address": "alice@example.com" },
  "to":           [ { "name": "Bob", "address": "bob@example.com" } ],
  "date":         "2026-06-01T10:00:00Z",
  "text_body":    "Hi Bob, ...",
  "html_body":    "<p>Hi Bob, ...</p>",
  "parts":        [ { "content_type": "text/plain",    "body": "Hi Bob, ..." },
                    { "content_type": "text/markdown", "body": "Hi **Bob**, ..." },
                    { "content_type": "text/html",     "body": "<p>Hi Bob, ...</p>" } ],
  "attachments":  [ { "name": "report.pdf", "content_type": "application/pdf", "size": 51200 } ],
  "raw":          "From: Alice ..."   # full RFC822 source
}

mail = Imap.new("imap.gmail.com", "me@gmail.com", "app-password")

info = mail.select("INBOX")
print("#{info["exists"]} messages, #{info["unseen"]} unread")

# Fetch and mark every unread message as read
for uid in mail.uid_search("UNSEEN")
  msg = mail.fetch_uid(uid)
  print("#{msg["date"]} — #{msg["from"]["address"]}: #{msg["subject"]}")

  for attachment in msg["attachments"]
    print("  attachment: #{attachment["name"]} (#{attachment["content_type"]})")
  end

  mail.mark_seen(msg["seq"])
end

mail.logout()