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.
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);
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.
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'.
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.
bool add_account ( string user, string password [, array forwards] )
Returns true on success, false on failure.
bool add_alias ( string user [, string password [, array forwards]] )
Returns true on success, false on failure.
bool delete_user ( string user )
Returns true on success, false on failure.
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? |
bool list_users ()
Returns an array with user info on success, false on failure. See chapter 2.4 for a description of the array.
bool set_password ( string user, string password )
Returns true on success, false on failure.
bool set_forwards ( string user [, array forwards] )
Returns true on success, false on failure.
bool set_hardquota ( string user [, string quota] )
quota is given in bytes.
Returns true on success, false on failure.
bool set_softquota ( string user [, string quota] )
quota is given in bytes.
Returns true on success, false on failure.
bool set_messagesize ( string user [, string size] )
Returns true on success, false on failure.
bool set_messagecount ( string user [, string count] )
Returns true on success, false on failure.
bool set_expiry ( string user [, string timestamp] )
Returns true on success, false on failure.
bool set_enabled ( string user, bool enable )
Returns true on success, false on failure.
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.
bool set_catchall ( [string user] )
If user is omitted, catchall is removed.
Returns true on success, false on failure.
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.
string autoresponse_get ( string user )
Returns autoresponse message on success, false on failure.
Hint: Have a look at 4.5 Parse
bool autoresponse_set_enabled ( string user, bool enable )
Returns true on success, false on failure.
bool autoresponse_isset ( string user )
Returns true if autoresponse is activated, false if disabled.
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>" } }
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.
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().
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.
For your convenience, I've included local copies of important VMailMgr documents.
by Daniel Lorch 2002