This page documents the protocol used between VPOP3 and the Status Monitor. It's not intended for any other purpose, so it's a bit limited, but in certain cases you may find this useful
Before the Status Monitor receives any updates or can issue commands it must log in using a user's credentials.
There are three ways to login:
This is a basic plain-text login. Note that the password is transmitted in plain text
Send the command
LOGIN <username> <password>
You will receive a line beginning with either “+OK” if the authentication succeeded or “-ERR” if the authentication failed for some reason (incorrect password, permissions not allowed, etc)
eg, for the user postmaster, password 'admin'
+OK VPOP3 Status Server Ready <3.d28.51abf1c9> LOGIN postmaster admin +OK Logged in OK (Build 2886)
This is a challenge-response login in the spirit of APOP in the POP3 protocol. The password is not transmitted over the wire in plain text.
When you connect to VPOP3, VPOP3 sends a welcome line like:
+OK VPOP3 Status Server Ready <3.d28.51abf1c9>
The <3.d28.51abf1c9> text is the 'challenge' including the < and > characters
You need to concatenate the challenge and the user's password and perform an MD5 hash on it, then send use that as the response. Then send the command
ALOGIN <username> <response>
You will receive a line beginning with either “+OK” if the authentication succeeded or “-ERR” if the authentication failed for some reason (incorrect password, permissions not allowed, etc)
eg, for the user postmaster, password 'admin'
+OK VPOP3 Status Server Ready <3.d28.51abf1c9> ALOGIN postmaster 9077A0BE9A986C3AE3B32D25C417A98D +OK Logged in OK (Build 2886)
This is a challenge-response login intended for use by an automated system which you do not want to configure with a real password. Instead of a password it uses the 'WebAPI' key specified in Services → Webmail Server → Advanced (minimum 10 characters)
When you connect to VPOP3, VPOP3 sends a welcome line like:
+OK VPOP3 Status Server Ready <3.d28.51abf1c9>
The <3.d28.51abf1c9> text is the 'challenge' including the < and > characters
You need to concatenate the challenge and the WebAPI key and perform an MD5 hash on it, then send use that as the response. Then send the command
APILOGINALOGIN <username> <response>
You will receive a line beginning with either “+OK” if the authentication succeeded or “-ERR” if the authentication failed for some reason (incorrect password, permissions not allowed, etc). If the authentication succeeds then you are logged in as the 'Main Administrator' user.
eg, for if the WebAPI key is “1234567890”
+OK VPOP3 Status Server Ready <3.d28.51abf1c9> APILOGIN 290A4D2C7DAA7A2F8D88F9BE61B650C2 +OK Logged in OK (Build 2886)
Immediately that you are logged into the Status Server, VPOP3 will send status updates to you. Initially it will send a big burst of data to get you up-to-date, then it will send updates as and when they occur. The data is 'pushed' to you, you do not need to request an update.
Each data line begins with a single character indicating the type of update, then the rest of the data is the update data, then finally it ends with a CR/LF pair.
Note that you will only receive a type of update if the permissions for the logged in user allow that user to have those updates.
An update line beginning with '0' (ASCII code 48) indicates a status line update, shown in the Status Monitor activity log
The structure of the line is:
0<time><text>
An update line beginning with '1' (ASCII code 48) indicates a connection status update. This is the text which usually appears in the 'Connection' box of the Status Monitor
The structure of the line is:
1<text>