Developer's guide

1. General

1.1 Terminology

It is necessary not to confuse some terms: Whenever I am talking about a user, I'm thinking of the real unix user - as opposed to the virtual user which is created by VMailMgr.

1.2 How to use

The VMailMgr Interface is a PHP class. I suggest you to first create a new class which extends the base class in order to specify whether you are using TCP/IP or UNIX Domain sockets.

  include_once(dirname(__FILE__) . '/vm/vm.php');

TCP/IP sockets:

  class my_vmailmgr extends vmailmgr {
    var $tcp_host = "localhost";
    var $tcp_port = 322;
  }

.. or UNIX Domain sockets:

  class my_vmailmgr extends vmailmgr {
    var $unix_socket = "/tmp/.vmailmgrd";
  }

Finally, create an instance of this class:

  $vm = new my_vmailmgr($domain, $password);

1.3 Which password?

There are certain commands that can be performed both with the user's password and the virtual user's password:

  virtual user user
2. Basic Functions
2.1 Add Account   x
2.2 Add Alias   x
2.3 Remove Account/Alias   x
2.4 Information on particular user x x
2.5 List available users   x
3. Set Attributes
3.1 Password x x
3.2 Forwards x x
3.3 Hardquota   x
3.4 Softquota   x
3.5 Message Size   x
3.6 Message Count   x
3.7 Expiry   x
3.8 Personal   x
3.9 Catch All   x
4. Autoresponder
4.1 Set x x
4.2 Get x x
4.3 Enable/Disable x x
4.4 Status (enabled or disabled?) x x

Note: The first parameter of vmmi's constructor still remains $domain. Do not attempt to create an instance like:

  $vm = new my_vmailmgr("user@example.com", $password);

This won't work. The following is correct:

  $vm = new my_vmailmgr("example.com", $password);

There's a working example on chapter 1.4.

1.4 Verifying Passwords

Unfortunately, the VMailMgr daemon does not offer a command to verify a password. I suggest you to use a command that does not apply any changes. This adds some overhead, but unfortunately there is no alternative. To verify the user's password I recommend:

  $vm = new my_vmailmgr("example.com", $password_to_verify);
  if($vm->list_users() !== false) {
    echo "Password OK";
  }
  else {
    echo "Password invalid";
  }

To verify the virtual user's password I recommend:

  $vm = new my_vmailmgr("example.com", $password_to_verify);
  if($vm->user_info($user_to_check) !== false) {
    echo "Password OK";
  }
  else {
    echo "Password invalid";
  }

Make sure you do also type-checking (!== instead of != or just a plain !).

Hint: You might also want to have a look at 'login.php'.

1.5 Why set_enabled() instead of enable() and disable()?

There are several set_enabled() functions instead of enable()/disable() pairs. You may wonder why? Because it allows more elegant code. Suppose we have the following (fragment of a) HTML form:

  <select name="enable">
    <option value="yes">yes
    <option value="no">no
  </select>

With enable()/disable() we'd have to write:

  if($_REQUEST['enable'] == 'yes') {
    $vm->enable();
  }
  else {
    $vm->disable();
  }

But with set_enable() we can just write:

  $vm->set_enable($_REQUEST['enable'] == 'yes');

Of course you could use the ternary operator "?:", but that's not the point.

2. Basic Functions

2.1 Add Account

bool add_account ( string user, string password [, array forwards] )

Returns true on success, false on failure.

2.2 Add Alias

bool add_alias ( string user [, string password [, array forwards]] )

Returns true on success, false on failure.

2.3 Remove Account/Alias

bool delete_user ( string user )

Returns true on success, false on failure.

2.4 Information on particular user

array user_info ( string user )

Returns an array with user info on success, false on failure. This array looks like:

key type explanation
flags array (see table below)
username string Username
password bool Has this account a password set?
mailboxdir string Path to virtual user's mailbox
personal string Personal info
hardquota string Hardquota in bytes, "-" if not set
softquota string Softquota in bytes, "-" if not set
messagesize string Maximum message size, "-" if not set
messagecount string Maximum message count, "-" if not set
creation string Account creation time as UNIX timestamp
expiry string Account expiry time as UNIX timestamp, "-" if not set

The flags-key is itself an array which can have the following values. These values are defined in ./lib/vdomain/vdomain.h of VMailMgr's sourcecode.

Note: The only flag that appears to be set (as of VMailMgr 0.95) is 'mailbox_enabled' - the other one's are (somehow) redundant anyway.

key type explanation
pass bool Password set?
dest bool (Probably) destination mailbox set?
hardquota bool Hardquota set?
softquota bool Softquota set?
msgsize bool Message size limit set?
msgcount bool Message count limit set?
expiry bool Expiry date set?
mailbox_enabled bool Mailbox enabled?
personal bool Personal info set?

2.5 List available users

bool list_users ()

Returns an array with user info on success, false on failure. See chapter 2.4 for a description of the array.

3. Set Attributes

3.1 Password

bool set_password ( string user, string password )

Returns true on success, false on failure.

3.2 Forwards

bool set_forwards ( string user [, array forwards] )

Returns true on success, false on failure.

3.3 Hardquota

bool set_hardquota ( string user [, string quota] )

quota is given in bytes.

Returns true on success, false on failure.

3.4 Softquota

bool set_softquota ( string user [, string quota] )

quota is given in bytes.

Returns true on success, false on failure.

3.5 Message Size

bool set_messagesize ( string user [, string size] )

Returns true on success, false on failure.

3.6 Message Count

bool set_messagecount ( string user [, string count] )

Returns true on success, false on failure.

3.7 Expiry

bool set_expiry ( string user [, string timestamp] )

Returns true on success, false on failure.

3.8 Enable/Disable

bool set_enabled ( string user, bool enable )

Returns true on success, false on failure.

3.9 Personal

bool set_personal ( string user [, string text] )

text is a string with arbitrary content. vmmi uses it to store the virtual user's full name.

Returns true on success, false on failure.

3.10 Catch All

bool set_catchall ( [string user] )

If user is omitted, catchall is removed.

Returns true on success, false on failure.

4. Autoresponder

4.1 Set

bool autoresponse_set ( string user, string message )

'message' also has to include mail headers. Make sure to at least provide 'From:' and 'Subject:'. Example:

  $vm->autoresponse_set("foobar", "From: Foo Bar <user@example.com>
Subject: Autoresponse: %S

This is my autoresponse message.");

Returns true on success, false on failure.

4.2 Get

string autoresponse_get ( string user )

Returns autoresponse message on success, false on failure.

Hint: Have a look at 4.5 Parse

4.3 Enable/Disable

bool autoresponse_set_enabled ( string user, bool enable )

Returns true on success, false on failure.

4.4 Status (enabled or disabled?)

bool autoresponse_isset ( string user )

Returns true if autoresponse is activated, false if disabled.

4.5 Parse

array autoresponse_parse ( string message )

This is a helper function intended to parse a message returned by autoresponse_get(). The array corresponding to the example autoresponse set in 4.1 would look like this (output generated with var_dump()):

  array(2) {
    ["body"]=>
    string(87) "This is my autoresponse message."
    ["headers"]=>
    array(2) {
      ["Subject"]=>
      string(16) "Autoresponse: %S"
      ["From"]=>
      string(14) "Foo Bar <user@example.com>"
    }
  }

5. Advanced Functions

5.1 Send raw message to daemon

The most low-level function you can get is:

string send ( string data )

Sends data to the VMailMgr daemon and returns a response string, false on failure. The VMailMgr protocol requires you to prepend every message with a two-byte length index. This function will help:

string arglen ( string data )

Returns data length encoded as two bytes. But you might prefer 5.2, as it isn't as low-level as this.

5.2 Send your own command to daemon

This is a wrapper function around send() which takes care of prepending length bytes and formatting the command just like VMailMgr wants it.

bool raw ( string cmd, array args )

cmd is the command sent to VMailMgr, args an array of arguments. Example:

  $vm->raw("deluser", array("example.com", "user", "password"));

This would delete a user.

Hint: You might want to have a look at 'vm.php'. All commands discussed here are invoking raw().

5.3 Retrieve last response from daemon

This varies depending on whether you are "inside" or "outside" the class. As you know raw() only returns a bool value whether your command succeded or failed. When you need the rest of VMailMgr's response (for example with commands like "listdomain" and "lookup"), you can get it from:

  $this->response;

This variable has to be considered private (as you know PHP 4.x does not yet support real private member variables). From "outside" the class use the following command instead:

string last_response ()

Returns VMailMgr's last response. The header is already stripped. If you need the full response, use send() instead.

6. Important VMailMgr Documents

For your convenience, I've included local copies of important VMailMgr documents.

6.1 Client-Server Interaction (Protocol description)

protocol.txt

6.2 Record Format

record-format.txt

by Daniel Lorch 2002