Net::ManageSieve(3pm)

📦

version 0.13 · 3 versions

0.13 · ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.13 · ubuntu jammy
0.13 · debian bookworm, debian trixie

, in ubuntu noble, ubuntu resolute, ubuntu stonking

💌 Net::ManageSieve 💌

okay bestie so this is a ManageSieve Protocol Client, and it lives in the Net::ManageSieve module. that's the whole vibe. let's go 💅

✨ SYNOPSIS ✨

    use Net::ManageSieve;

    # Constructors
    $sieve = Net::ManageSieve->new('localhost');
    $sieve = Net::ManageSieve->new('localhost', Timeout => 60);

🌸 DESCRIPTION 🌸

so this module is a client interface to the ManageSieve protocol (link right here: <http://tools.ietf.org/html/draft-martin-managesieve-09>), and ngl the docs are just gonna assume you already know the protocol's whole deal. like, the concepts? assumed. ✨

you literally have to make a new Net::ManageSieve object with the new method first — that's the entry fee. once you've done that, every single ManageSieve command is accessed through this object. main character object energy.

📌 note: ManageSieve lets you manipulate scripts on a host running a ManageSieve service. this module does not perform, validate, or anything-like-that the Sieve scripts themselves. it's a client, not a script babysitter, okay?

also: this module works in taint mode. periodt 💜

🦋 EXAMPLES 🦋

example one: prints the capabilities of the server known as mailhost.

    #!/usr/local/bin/perl -w

    use Net::ManageSieve;

    $sieve = Net::ManageSieve->new('mailhost');
    print "$k=$v\n" while ($k, $v) = each %{ $sieve->capabilities };
    $sieve->logout;

example two: lists all the stored scripts on the server, and it requires TLS bestie, no exceptions.

    #!/usr/local/bin/perl -w

    use Net::ManageSieve;

    my $sieve = Net::ManageSieve->new('mailhost', tls => 'require')
      or die "$@\n";
    print "Cipher: ", $sieve->get_cipher(), "\n";
    $sieve->login('user', 'password')
      or die "Login: ".$sieve->error()."\n";
    my $scripts = $sieve->listscripts
      or die "List: ".$sieve->error()."\n";
    my $activeScript = pop(@$scripts);
        print "$_\n" for sort @$scripts;
    print $activeScript
      ? 'active script: ' . $activeScript
      : 'no script active'
     , "\n";
    $sieve->logout;

😭 ERROR HANDLING 😭

okay so by default, all functions return undef when they fail, and they set an error description into $@. you can also grab that description with the error() method. two ways, same tea. 🍓

the constructor accepts a setting called on_fail, and it changes the whole behaviour by switching up the step that assigns $@. if its value is:

"warn" — the program carps the error description.
- and if "debug" is enabled too? the description gets printed twice. not a drill, it's just extra like that. 🙈
"die" — the program croaks.
a CODE ref — this subroutine gets called with these arguments:

 &code_ref ( $object, $error_message )

the return value controls whether or not the error message gets assigned to $@. private functions may just signal that an error occurred but keep $@ unchanged. in that case, $@ remains unchanged if code_ref returns true.

⚠️ note: even if the code ref returns false, $@ might get clobbered by called modules. this is especially true in the new() constructor. so like, be careful out there 💀

otherwise — the default behaviour sticks around, by setting $@.

👑 CONSTRUCTOR 👑

`new ( [ HOST ] [, OPTIONS ] )`

this is the constructor for a brand new Net::ManageSieve object. HOST is the name of the remote host you want a ManageSieve connection to. yes, required-ish, we'll get there.

HOST is optional. if you don't give a HOST, you can pass it as the Host option instead (described below, keep scrolling bestie). and if you give neither? localhost gets used. defaults, we love them. ✨

OPTIONS get passed in a hash-like fashion, key and value pairs, very chill. the possible options are:

Host — the ManageSieve host to connect to. it may be a single scalar, as defined for the PeerAddr option in IO::Socket::INET, or a reference to an array with hosts to try in turn. the host method will return the value which was used to connect to the host.
LocalAddr and LocalPort — these parameters are passed directly to IO::Socket, so you can bind the socket to a local port. 🫶
Timeout — max time, in seconds, to wait for a response from the ManageSieve server (default: 120).
Port — pick a port on the remote host to connect to (default is 2000).
Debug or debug — enable debugging if true (default OFF).

📌 note: all of the above options are passed through to IO::Socket::INET.

tls — issue STARTTLS right after connecting. if tls is a HASH ref, the mode lives in member "mode"; otherwise tls itself is the mode, and an empty SSL option HASH gets passed to starttls(). the "mode" may be one of "require" — fail if TLS negotiation fails — or "auto", "on" or "yes", if TLS is to be attempted but a failure is just ignored. ✨ (Aliases: TLS, Tls)
on_fail — changes the error handling of all functions that would otherwise return undef and set $@. go read the ERROR HANDLING section, i literally just wrote it for you 💅 (Aliases: On_fail)

example:

    $sieve = Net::ManageSieve->new('mailhost',
                           Timeout => 30,
               );

that one uses the first host it can connect to successfully, "mailhost" on port 2000 (the default port), then "localhost" on port 2008.

    $sieve = Net::ManageSieve->new(Host => [ 'mailhost', 'localhost:2008' ],
                           Timeout => 30,
                           tls => {
                                mode => require,
                                SSL_ca_path => '/usr/ssl/cert',
                           }
               );

🔥 METHODS 🔥

unless otherwise stated, all methods return either a true or false value, where true means the operation was a success. slay. when a method says it returns a value, failure comes back as undef or an empty list. the error is specified in $@ and can be returned with the error method. and hey, if you want a whole different error handling scheme, go check the ERROR HANDLING section. 🌈

close () — closes the connection to the server. any already cached data is kept active though. that said, there should be no pending data if a user calls this function.
starttls ( %SSL_opts ) — initiates a TLS session. may only be used before any authentication. the SSL_opts is a HASH containing any options you can pass to IO::Socket::SSL->new(). nothing is passed by default. to detect later whether the connection is encrypted, use the encrypted() function.
- Return: $self, or "undef" on failure — and in that failure case the socket is still functioning, it's just not encrypted. 😭
encrypted () — returns "undef" if the connection is not encrypted, otherwise "true".
get_cipher (), dump_peer_certificate (), peer_certificate ($field) — returns "undef" if the connection is not encrypted, otherwise these functions directly call the equally named function of IO::Socket::SSL. 💜
auth (USER [, PASSWORD [, AUTHNAME ] ]) — authentificates as USER. if the module Authen::SASL is available, this module is tried first. in that case, the USER parameter may be a Authen::SASL object, which is not furtherly modified. if USER is no Authen::SASL object, USER is passed as user, PASSWORD as pass and AUTHNAME as authname to Authen::SASL->new(). if AUTHNAME is undefined, USER is passed as authname. this way you can authentificate against Cyrus: auth('cyrus', $password, $username). if Authen::SASL is not available, or the initialization of it fails, this function attempts to authentificate via the PLAIN method instead.
- Aliases: login, authentificate.
logout () — sends the LOGOUT command to the server and closes the connection to the server. bye bestie 👋
- Aliases: quit, bye.
host () — returns the remote host of the connection.
capabilities ([reget]) — returns the capabilities as a HASH ref, e.g.:

      {
        'starttls' => 1,
        'sasl' => 'PLAIN LOGIN',
        'implementation' => 'dovecot',
        'sieve' => 'fileinto reject envelope vacation imapflags notify subaddress relational comparator-i;ascii-numeric regex'
      };

if the argument bool is specified and is boolean TRUE, the capabilities are reaquired from the server using the CAPABILITY command.

📌 note: the initial capabilities may be different from the set acquired later.

havespace (NAME, SIZE) — returns whether or not a script with the specified size (and name) might fit into the space of the user on the server.

⚠️ due to various reasons, the result of this function is not very reliable, because in the meantime lots of changes may take place on the server. it's giving "best guess" energy, not "promise". 🙈

putscript (NAME, SCRIPT) — stores the SCRIPT as name NAME on the server. the script is not activated by default. SCRIPT is a scalar in UTF-8.

🚫 the script must not be empty.

listscripts () — returns an ARRAY ref of the names of the scripts. the last entry in the list specifies the active script, and it's an empty string "" if there is none. e.g.:

      [       "script1",
              "script2",
              "script1"
      ]

that means script1 is active currently. ✨

setactive (NAME) — activates the script named NAME.
getscript (NAME) — returns the named script. the contents is in perl-internal UTF8.
deletescript (NAME) — deletes the script named NAME. gone, deleted, not coming back. 💅
error () — returns the locally cached error information in the form:

 error description respn=last server response

debug ( [state] ) — returns the current state of debugging. if state is given, the boolean value enables or disables debugging.
"str2utf8([encoding,] string)" — encodes the string into internal UTF8. if encoding is specified, it is tried first; then "utf-8-strict", and if all fails, "Latin1", which is not fail. 🧚

💀 BUGS 💀

the module tries hard to pass valid UTF8 data to the server and transforms the results into perl internal UTF8. if the latter fails, the transmitted octets are decoded using Latin1.
script names, user names and passwords are not checked or "SASLprep"'ed (RFC 4013/3454). script names with [\0\r\n] are rejected.
we accept non-synchronizing literals {num+} from the server.

🌟 AUTHOR 🌟

Steffen Kaiser. this module heavily bases on Net::SMTP and Net::Cmd. (iconic lineage honestly 👑)

🎀 COPYRIGHT 🎀

and that's the whole page bestie, no cap. this one's perl v5.36.0, dated 2022-10-13, and it's the Net::ManageSieve(3pm) manual — go forth and slay those Sieve scripts. mwah 💋✨🦋

📦 where this page comes from

ubuntu noble: libnet-managesieve-perl 0.13-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libnet-managesieve-perl 0.13-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libnet-managesieve-perl 0.13-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms