WebMail Pro PHP documentation

Sending login credentials via POST

Introduction

The product supports logging in programmatically by supplying login credentials which come from external application. In some cases, however, that approach might be not suitable, typical case is when WebMail and external application run on different servers.

There is another way to log user in, it's done by sending POST data to WebMail. Data can come from HTML form, from JavaScript application, etc.

Configuration

For security reasons, this option is disabled by default. You can enable it by adding the following item to array defined in data/settings/config.php file:

'labs.allow-post-login' => true,

Then you can submit POST requests to WebMail Pro, with '?postlogin' appended to its URL. So if your product installation is found at http://yourdomain.com/webmail/ URL, you should supply http://yourdomain.com/webmail/?postlogin URL here. WebMail expects 'email' and 'password' parameters via POST.

Error handling

In case if authentication error occurs while using this login approach, user is redirected to standard login page of WebMail Pro with error message displayed on top. However, you can override this behavior and supply URL of your error page using the following setting in data/settings/config.php file:

'labs.post-login-error-redirect-url' => 'http://yourdomain.com/error.php',

Error code will be sent to that error page and you'll be able to access it in your code as follows:

$iErrCode = $_GET["error"];

The following error codes are currently supported:

* 102 - AuthError (authentication issue, or the account is disabled)

* 104 - DataBaseError

* 105 - LicenseProblem

* 901 - MailServerError

Usage example

The simplest way to test this approach is to have a basic HTML form which contains the login details:

<form action="http://yourdomain.com/webmail/?postlogin" method="post">
Email: <input type="text" name="Email"><br>
Password: <input type="text" name="Password"><br>
<input type="submit" value="Login">
</form>

This allows for building custom login forms and bypassing default login screen of webmail interface.

Using GET requests

While using POST is usually convenient, we've added GET support as well. So you can direct user to URL of the following kind:

http://yourdomain.com/webmail/?postlogin&Email=test%40user.com&Password=12345

Note that parameters here need to be supplied in URL encoded way. For example, if email is test@user.com and password is 123&45, URL would look like:

http://yourdomain.com/webmail/?postlogin&Email=test%40user.com&Password=123%2645

Naturally, it's less secure compared to POST as credentials are visible in URL. Still, that might be an option in some cases.