IMAP::Admin(3)

💖 IMAP::Admin — the Cyrus admin page 💖

hiii bestie, you've landed on IMAP::Admin(3), straight out of the User Contributed Perl Documentation corner of the manual. grab a snack, this one's actually useful 🍓

---

✨ NAME ✨

Cyrus::IMAP::Admin — the Cyrus administrative interface Perl module. yeah. that's the whole name. iconic, honestly 👑

---

🦋 SYNOPSIS 🦋

okay so here's the whole vibe in code, no cap:

use Cyrus::IMAP::Admin;

my $client = Cyrus::IMAP::Admin->new('mailhost'[, $flags]);
$rc = $client->create('user.auser'[, $partition]);
$rc = $client->delete('user.auser');
$rc = $client->deleteacl('user.buser', 'user1', 'user2');
%acls = $client->listacl('user.buser');
@mailboxes = $client->list('*');
@mailboxes = $client->list('%', 'user.');
@mailboxes = $client->subscribed('*');
%quota = $client->quota($root);
($root, %quota) = $client->quotaroot($mailbox);
$rc = $client->rename($old, $new[, $partition]);
$rc = $client->setacl($mailbox, $user =E<gt> $acl[, ...]);
$rc = $client->setquota($mailbox, $resource =E<gt> $quota[, ...]);
$rc = $client->xfer($mailbox, $server[, $partition]);

---

🌸 DESCRIPTION 🌸

This module is a Perl interface to Cyrus administrative functions. It's what powers Cyrus::IMAP::Admin::Shell — you probably know her as cyradm — and you can also use it in your own Perl administrative programs. she's versatile like that 💅

---

🎀 METHODS 🎀

A bunch of these methods come in two flavors: a cyradm-compatible name and a shorter name. Whenever a short name exists, that's the one shown in the synopsis; the cyradm-compatible one should be pretty obvious once you see it.

heads up bestie: in general, methods return undef or empty lists when something goes wrong. but plot twist — sometimes a method returns an empty list with no error at all (like list on a hierarchy that doesn't exist), so if you really need to know, you gotta check the error state yourself with the error method. don't get caught lacking 🙈

💫 new($server[, $flags])

Instantiates a cyradm object. fun fact: this is literally a Cyrus::IMAP object with a few extra methods bolted on, so every single Cyrus::IMAP method is available to you if you need it. (and in particular? you will always want to use the authenticate method. always. periodt.)

💫 error

Returns the last error that happened, or undef if the last operation was a slay. This is, in some cases (like list), the only way to tell the difference between "successfully returned an empty list" and "something exploded."

Calling error does not reset the error state, so writing this is completely legal:

@folders = $cyradm->list($spec);
print STDERR "Error: ", $cyradm->error if $cyradm->error;

💫 createmailbox / create

• createmailbox($mailbox[[, $partition], \%opts])
• create($mailbox[, $partition])

Creates a brand new mailbox on the specified partition, or the default one if you don't say. ✨

💫 deletemailbox / delete

• deletemailbox($mailbox)
• delete($mailbox)

Deletes a mailbox. and bestie, listen — same as with cyradm, you'll probably need to give yourself the c ACL on that mailbox first using setaclmailbox. yes really. do it first. 💀

💫 deleteaclmailbox / deleteacl

• deleteaclmailbox($mailbox, $user[, ...])
• deleteacl($mailbox, $user[, ...])

Deletes one or more ACLs from a mailbox. bye felicia 👋

💫 listaclmailbox / listacl

• listaclmailbox($mailbox)
• listacl($mailbox)

Returns a hash of mailbox ACLs — each key is a Cyrus user, and each value is the ACL that user has. cute little key-value moment 🎀

💫 listmailbox / list

• listmailbox($pattern[[, $reference], \%opts])
• list($pattern[[, $reference], \%opts])

Lists mailboxes that match the given pattern, starting from the given reference. The result is a list; every element is an array holding the mailbox name, its attributes, and the separator. (this interface may change, so don't get too attached 😭)

💫 listsubscribed / subscribed

• listsubscribed($pattern[, $reference])
• subscribed($pattern[, $reference])

Exactly like listmailbox, except it only shows the mailboxes you're actually subscribed to. no lurkers allowed 🫶

💫 listquota / quota

• listquota($root)
• quota($root)

Returns a hash with the quota for the quota root you specified. psst — use listquotaroot to find the quota root for a mailbox if you don't know it.

💫 listquotaroot / quotaroot

• listquotaroot($mailbox)
• quotaroot($mailbox)

Returns a list: first element is the quota root for the mailbox, and the rest of the elements are a hash describing its quota. main character first, details after 💅

💫 renamemailbox / rename

• renamemailbox($from, $to[, $partition])
• rename($from, $to[, $partition])

Renames the given mailbox, and optionally moves it to a whole different partition while she's at it. glow-up + relocation 🦋

💫 setaclmailbox / setacl

• setaclmailbox($mailbox, $user => $acl[, ...])
• setacl($mailbox, $user => $acl[, ...])

Sets ACLs on a mailbox. The ACL can be one of these special strings — none, read (lrs), post (lrsp), append (lrsip), write (lrswipkxte), delete (lrxte), or all (lrswipkxte) — or literally any combination of the ACL codes below:

• l — Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)
• r — Read (SELECT/EXAMINE the mailbox, perform STATUS)
• s — Seen (set/clear \SEEN flag via STORE, also set \SEEN flag during APPEND/COPY/FETCH BODY[...])
• w — Write flags other than \SEEN and \DELETED
• i — Insert (APPEND, COPY destination)
• p — Post (send mail to mailbox)
• k — Create mailbox (CREATE new sub-mailboxes, parent for new mailbox in RENAME)
• x — Delete mailbox (DELETE mailbox, old mailbox name in RENAME)
• t — Delete messages (set/clear \DELETED flag via STORE, also set \DELETED flag during APPEND/COPY)
• e — Perform EXPUNGE and expunge as part of CLOSE
• a — Administer (SETACL/DELETEACL/GETACL/LISTRIGHTS)

💫 setquota($mailbox, $resource, $quota[, ...])

Sets quotas on a mailbox. quick note: Cyrus currently only defines one resource, STORAGE. and as defined in RFC 2087, the units are groups of 1024 octets (i.e. Kilobytes). math girlies rise 🧮✨

💫 xfermailbox / xfer

• xfermailbox($mailbox, $server[, $partition])
• xfer($mailbox, $server[, $partition])

Transfers (relocates) the given mailbox over to a different server. she's moving out, no forwarding address 🚚

---

👑 AUTHOR 👑

Brandon S. Allbery, allbery@ece.cmu.edu — thank you for your service king 🫡

---

🌈 SEE ALSO 🌈

Cyrus::IMAP Cyrus::IMAP::Shell perl(1), cyradm(1), imapd(8).

---

and that's the whole page bestie!! this was perl v5.42.3, dated 2026-09-11, and you just read the IMAP::Admin(3) manual. go forth and administer some mailboxes, you absolute icon 💖✨🎀🦋