IMAP(3)

🦋 IMAP(3) 🦋

okay bestie, so this is the section 3 manual page for Cyrus::IMAP, from the User Contributed Perl Documentation corner of the universe. it's giving "perl module that talks to Cyrus" and honestly? iconic. let's get into it 💅

---

✨ NAME ✨

Cyrus::IMAP — the interface to the Cyrus imclient library. that's it, that's the name, no notes 💖

---

✨ SYNOPSIS ✨

here's the whole vibe, verbatim, no cap:

use Cyrus::IMAP;

my $client = Cyrus::IMAP->new('mailhost'[, $flags]);
$flags = Cyrus::IMAP::CONN_NONSYNCLITERAL;

($server, $mailbox) = Cyrus::IMAP->fromURL($url);
$url = Cyrus::IMAP->toURL($server, $mailbox);

$client->setflags($flags);
$client->clearflags(Cyrus::IMAP::CONN_INITIALRESPONSE);
$flags = $client->flags;
$server = $client->servername;
$client->authenticate;
$flags = Cyrus::IMAP::CALLBACK_NUMBERED || Cyrus::IMAP::CALLBACK_NOLITERAL;
$client->addcallback({-trigger => $str, -flags => $flags,
                      -callback => \&cb, -rock => \$var}, ...);
$client->send(\&callback, \&cbdata, $format, ...);
$client->processoneevent;
($result, $text) = $client->send(undef, undef, $format, ...);
($fd, $writepending) = $client->getselectinfo;

look at all those methods. it's a whole menu 🍓

---

✨ DESCRIPTION ✨

so the Cyrus::IMAP module is your lil gateway — it provides an interface to the Cyrus imclient library. these are, like, primarily useful for implementing cyradm operations inside a Perl script. and yeah, there are easier ways to do general client operations, but lowkey they may be more limited when it comes to authentication options while talking to a Cyrus imapd. tradeoffs, bestie 🫶

in the normal case, you attach to a Cyrus server and authenticate using the best available method:

my $client = Cyrus::IMAP::new('imap');
$client->authenticate;
if (!$client->send('', '', 'CREATE %s', 'user.' . $username)) {
  warn "createmailbox user.$username: $@";
}

🎀 simple mode (the easy era)

in simple mode, like the example up there, send() gets called with undef, 0, or '' for the callback and rock (that's callback data) arguments. it hands you back a list of ($result, $text) from the command. and if you call it in scalar context? it returns $result and drops $text into $@. cute, right?

in this mode you do not need processoneevent(). periodt ✋

🦋 want more control?

if you want more control, use the callback and rock arguments, and hit processoneevent() regularly to receive results from the IMAP server. it's giving "hands on the wheel" 🚗

👑 want EVEN more control?

if you need still more control, the getselectinfo() method returns a list containing a file descriptor — and no, not a Perl filehandle, an actual file descriptor — which you can pass to select(). and here's the tea: if the second element of that list is true, you should include it in the write mask as well as the read mask, because the imclient library needs to perform queued output. don't skip that part bestie 😭

for more information, consult the Cyrus documentation. that's the assignment 📚

---

✨ NOTES ✨

okay this is the fine-print section, but make no mistake, it MATTERS. read it. 💀

• send() behaves as if the Cyrus::IMAP::CONN_NONSYNCLITERAL flag is always set. why? because it's a wrapper for the C version, which cannot be made directly available from Perl, and synchronous literals require interaction with the IMAP server while parsing the format string. the good news: this is planned to be fixed in the future. so like, someday 🌈
• the 'LOGIN' mechanism can be used to authenticate with a plaintext username and password. this is intended as a workaround for a bug in early SASL implementations. using Cyrus::IMAP with non-Cyrus servers is not recommended, primarily because there are easier ways to implement IMAP client functionality in Perl. (however — and this is the plot twist — if you need SASL support, Cyrus::IMAP is currently the only way to get it.) slay, i guess 💅
• the file descriptor returned by getselectinfo() should not be used for anything other than select(). in particular, I/O on that file descriptor will almost certainly cause more problems than whatever problem you think you are trying to solve. not me watching you cause your own problems 🙈
• the toURL and fromURL routines are there to ease conversion between URLs and IMAP mailbox + server combinations. they're a simple frontend for the libcyrus functions of the same name. easy money 💖
• the imparse library routines are not implemented, because they are little more than a (failed) attempt to make parsing as simple in C as it is in Perl. yeah. they said that. 💀
• this module exists primarily so we can integrate Cyrus administration into our Perl-based account management system, and secondarily so we can rewrite cyradm in a sensible language instead of Tcl. usability for other purposes is not guaranteed. that's the whole origin story, bestie 🧚

---

✨ AUTHORs ✨

the masterminds, the main characters, the icons 👑

• Brandon S. Allbery <allbery@ece.cmu.edu>
• Rob Siemborski <rjs3+@andrew.cmu.edu>

---

✨ SEE ALSO ✨

go read these next, fr fr:

• Cyrus::IMAP::Admin
• perl(1)
• cyradm(1)
• imclient(3)
• imapd(8)

---

and that's the page, bestie 🎀 this whole thing is perl v5.42.3, dated 2026-09-11 — so yeah, it's fresh, it's giving current, and it's yours now. go forth and authenticate responsibly 💖✨🦋🌸💅