---
name: "Cyrus::IMAP::Admin"
section: "3pm"
platform: "linux"
package: "libcyrus-imap-perl"
version: "3.10.2-1+deb13u2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Cyrus::IMAP::Admin"
---

# Cyrus::IMAP::Admin(3pm)

Cyrus administrative interface Perl module

## NAME

Cyrus::IMAP::Admin - Cyrus administrative interface Perl module

## SYNOPSIS

```
  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 is used to implement Cyrus::IMAP::Admin::Shell (otherwise known as **cyradm** and also available for use in Perl administrative programs.

## METHODS

Many of the methods have a **cyradm**-compatible name and a shorter name. The shorter name is shown in the synopsis when it exists; the **cyradm**-compatible name should be reasonably obvious.

In general, methods return undef or empty lists on error.  In some cases a method may return an empty list without an error (i.e. `"list"` of a nonexistent hierarchy), so it may be necessary to check the error state explicitly via the `"error"` method.

- new($server\[, $flags\])

  Instantiates a **cyradm** object.  This is in fact a Cyrus::IMAP object with a few additional methods, so all Cyrus::IMAP methods are available if needed. (In particular, you will always want to use the `"authenticate"` method.)

- error

  Return the last error that occurred, or undef if the last operation was successful.  This is in some cases (such as `"list"`) the only way to distinguish between a successful return of an empty list and an error return.

  Calling `"error"` does not reset the error state, so it is legal to write:

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

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

  - create($mailbox\[, $partition\])

  Create a new mailbox on the specified or default partition.

- deletemailbox($mailbox)

  - delete($mailbox)

  Delete a mailbox.  As with **cyradm**, you will probably need to add the **c** ACL for yourself to the mailbox with `"setaclmailbox"` first.

- deleteaclmailbox($mailbox, $user\[, ...\])

  - deleteacl($mailbox, $user\[, ...\])

  Delete one or more ACL from a mailbox.

- listaclmailbox($mailbox)

  - listacl($mailbox)

  Returns a hash of mailbox ACLs, with each key being a Cyrus user and the corresponding value being the ACL.

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

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

  List mailboxes matching the specified pattern, starting from the specified reference.  The result is a list; each element is an array containing the mailbox name, attributes, and the separator.  (This interface may change.)

- listsubscribed($pattern\[, $reference\])

  - subscribed($pattern\[, $reference\])

  Like `"listmailbox"` but only shows subscribed mailboxes.

- listquota($root)

  - quota($root)

  Returns a hash specifying the quota for the specified quota root.  Use `"listquotaroot"` to find the quota root for a mailbox.

- listquotaroot($mailbox)

  - quotaroot($mailbox)

  Returns a list, the first element is the quota root for the mailbox and remaining elements are a hash specifying its quota.

- renamemailbox($from, $to\[, $partition\])

  - rename($from, $to\[, $partition\])

  Renames the specified mailbox, optionally moving it to a different partition.

- setaclmailbox($mailbox, $user =\> $acl\[, ...\])

  - setacl($mailbox, $user =\> $acl\[, ...\])

  Set ACLs on a mailbox.  The ACL may be one of the special strings `"none"`, `"read"` (`"lrs"`), `"post"` (`"lrsp"`), `"append"` (`"lrsip"`), `"write"` (`"lrswipkxte"`), `"delete"` (`"lrxte"`), or `"all"` (`"lrswipkxte"`), or any combinations of the ACL codes:

  - 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\[, ...\])

  Set quotas on a mailbox.  Note that Cyrus currently only defines one resource, `"STORAGE"`.  As defined in RFC 2087, the units are groups of 1024 octets (i.e. Kilobytes)

- xfermailbox($mailbox, $server\[, $partition\])

  - xfer($mailbox, $server\[, $partition\])

  Transfers (relocates) the specified mailbox to a different server.

## AUTHOR

Brandon S. Allbery, allbery@ece.cmu.edu

## SEE ALSO

Cyrus::IMAP Cyrus::IMAP::Shell [**perl**(1)](/perl/1.md), [**cyradm**(1)](/cyradm/1.md), [**imapd**(8)](/imapd/8.md).