View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Bruni Emiliano > Qmail-Mysql-0.02 > Qmail::Mysql



Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  


Qmail::Mysql - A perl module for mysql database used by qmail-mysql


  use Qmail::Mysql
  my $qmail = new Qmail::Mysql(  
                     sql_control_file    => '/var/qmail/control/sqlserver',
                     mailbox_base        => '/var/spool/pop/users',
                     password_type       => 'Password',
                     multihosting        => 0,
                     multihosting_join   => '@'

  # add new domain as deliver local
  # check if domain is a local domain
  # remove a domain as delivel local

  # add new mailbox ( with pop3 password 'mypass'
  # pop3 user account is
  # 'foo'         if multihosting => 0 or
  # '' if multihosting => 1 
  # (the '@' in the pop3 account can be changed using multihosting_join)
  # This command creates also a Maildir directory in
  # mailbox_base/xxxxxx
  # where xxxxxx is
  # 'foo'         if multihosting => 0 or
  # '' if multihosting => 1
  # check to see if a mailbox already exists
  # remove mailbox
  # add an alias ( is an alias for (
  # check if this alias exists
  # remove this alias


The purpose of this module is to interface with the database structure used by the mysql patch of the qmail mailer daemon developed by Iain Patterson.

This patch transfer the mailbox information of the smtp protocol and the authentication information of the pop3 protocol from some file in the filesystem into some tables of a mysql database.

So lists of local deliver domains, the mail addresses, the aliases, the mailboxes of the smtp/pop3 qmail daemon if controlled by database tables instead of file.

This module can be used to add/remove local deliver domains, to add/remove real local mailbox, to add/remove alias and mailing-lists.

Thanks to Iain patch, all changes will be immediately see by qmail processes.

To have more info about qmail-mysql patch take a look at Iain Patterson web site (

To connect to database this module uses the same account used by qmail processes. In the qmail-mysql patch documentation this user is set with "SELECT" only privilege over qmail database.

To permit this module to read,add and delete qmail records standard privileges must be extended to "INSERT" and "DELETE" and "UPDATE".

As mysql administrator user you can execute this sql query to extend the qmail privilage supposing that qmail user is 'qmail', that database is local and it's named 'qmail' too.

          TO "qmail"@"localhost";



The new constructor return an istance of Qmail::Mysql object.

  $qmail = new Qmail::Mysql(  
                        [ mailbox_base        => $mbox_base_path ] ,
                        [ multihosting        => ( 0 | 1 )       ] ,
                        [ multihosting_join   => $mjoin_string   ] ,
                        [ password_type       => ( 
                                               'Password'       | 
                                               'Crypt-Password' |
                                                              )  ] ,
                                [ sql_control_file    => $sqlserver_path ] ,

It's the parent path of all Maildir folders that is under this path will be created the user mailbox folders under which users e-mails will be stored

Default value is '/var/spool/pop/users'


It's a boolean value that set if the mail server offers mailbox for only one domain or it's a multihosting server and accept mail for more that one domain.

In a single hosting there isn't possibility of confusion between user mailboxes. A mailbox for user 'foo' will be created under mailbox_base/foo and pop3 user account will be 'foo'.

In a multi hosting there can be more that one user with name 'foo' one for domain '' and the other for domain '' as an example. To avoid confusion, in this environment the mailbox for use 'foo' of the domain '' will be created under mailbox_base/ and his pop3 user account will be '' while for user of '' domain ia mailbox will be created undef mailbox_base/ and his pop3 user account will be ''.

Default value is a single hosting mode that is 0.


When multihosting is true this option set the string for building pop3 user account joined username,this value and the domain name.

Default value is '@' so pop3 user account coincides with user e-mail.


In agreement with mailbox table, this value is used to set Password-type mailbox field that indicates what kind of password is set in the Password field in the same table.

If password_type is 'Password', the password parameter of the mail_add method must be a clean text password; if password_type is 'Crypt-Password' the password parameter must be a string returned by unix crypt function; if password_type is 'MySQL-Password' the password parameter must be set as the value returned by mysql internal password function.

In the database password field will be stored a clean text password, a crypt unix password or a mysql password value.

Default value is 'Password' and therefore clean password will be used.


To connect to qmail database, this module uses the same login account of the qmail process. In the qmail process, following qmail-mysql documentetion, the database login access information is stored in a file located at ~qmail/control/sqlserver.

With this parameter you set the path to sqlserver file to permit this module to read and use qmail database connection.

Default value is '/var/qmail/control/sqlserver'






rcpt_add( $rcpt_host )


rcpt_exists( $rcpt_host )


rcpt_del( $rcpt_host )


mail_add( $username , $domain , $password )


mail_exists( $username , $domain )


mail_del( $username , $domain )


alias_add( $alias_mail , $real_mail )


alias_exists( $alias_mail , $real_mail )


alias_del( $alias_mail , $real_mail )



No diagnostics error returned.


Nothing exported


DBI, DBD::mysql, File::Path


Emiliano Bruni, <info/at/ebruni_dot_it>


The Iain Patterson web site

syntax highlighting: