Net::Doveadm - Dovecot’s administrative interface protocol


    my $doveadm = Net::Doveadm->new(
        io => $io_object,

        # Required for authentication,
        # but we warn if the server doesn’t ask for them.
        username => $username,
        password => $password,

        username => $cmd_username,
        command => [ $cmd, @args ],

    my $result_ar;

        # If using non-blocking I/O …
        # $io_object->flush_write_queue();

        last if $result_ar = $doveadm->receive();

        # If using non-blocking I/O, put a select(), poll(),
        # or similar call here.



This module implements client logic for the Doveadm protocol, which facilitates administrative communication with a Dovecot server via TCP or a local socket.

Note that this is the original Doveadm protocol, not the newer, HTTP-based one.


This module is designed, rather than to interact directly with a socket or other filehandle, to use IO::Framed as an abstraction over the transmission medium. If so desired, a compatible interface can be substituted for IO::Framed; in particular, the interface must implement IO::Framed’s write() and read_until() methods.

If you use IO::Framed, you should not enable its allow_empty_read() mode. The Doveadm protocol is strictly RPC-oriented, and the only successful end to a session is one that the client terminates.

Note that blocking and non-blocking I/O work nearly the same way; the SYNOPSIS above demonstrates the difference. A particular feature of this setup is that it’s possible to send multiple successive requests before reading responses to those requests.


All errors that this module throws are instances of Net::Doveadm::X::Base. At this time, further details are subject to change.


CLASS-new( %OPTS )

Instantiates this class. %OPTS are:

  • io - An instance of IO::Framed or a compatible interface.

  • username - The username to use in authentication. Required if the server asks for it; if given and the server does not ask for it, a warning is given.

  • password - As with username.

Note that no I/O happens in this method.

OBJ->send( %OPTS )

Send (or enqueue the sending of) a command. %OPTS are:

  • command - An array reference whose contents are (in order) the command name and all arguments to the command. Note that some calls, e.g., mailbox list, are “compound commands” rather than a command with argument.

  • username - Optional, the username to send with the command.

  • verbosity - Optional, either 1 (“verbose”) or 2 (“debug”).

Note that, if the server handshake is not yet complete, this will attempt to finish that before actually sending a message.

$RESULT = OBJ->receive()

Looks for a response to a previously-sent command. If such a response is ready, it will be returned as an array reference; otherwise, undef is returned.

Note that, if the server handshake is not yet complete, this will attempt to finish that before actually trying to retrieve a message.



Felipe Gasper (FELIPE)


Copyright 2018 by Gasper Software Consulting


This distribution is released under the same license as Perl.