@Mail Webadmin Development

1 Introduction to the @Mail Webadmin
2 User Functions
3 Domains Functions
4 Example Code
5 Related Technical / support information

1 Introduction to the @Mail Webadmin

This document is for programmers who want to implement @Mail with another software package. You can learn how to add / delete / modify users and control the @Mail software via HTTP calls. Allowing you intergrate @Mail with your existing software or accounting programs.

Using other applications, there are different ways to talk to the Webadmin scripts. You can use the <form> Tags within a HTML document, or call on a Webadmin-URL while giving the variables like http://mydomain.com/webadmin/admin.pl?func=deleteuser&Account=exampleuser%40yourdomain.com

Notice: You can't send an @-symbol in URL format. Replacing the @ with %40 will encode the string so and make it able to send the e-mail. If you are interested in sending other illegal characters in URL format, please check out http://www.asciitable.com/. They have an overview of all ASCII characters and their codes. Make sure you replace a character by a %-sign, followed by the hexadecimal (Hx) code in the overview.

An important thing to consider when letting an application communicate to the Webadmin scripts, is that you only allow access to the Webadmin from the IP you are running the application from. This can be done by modifying the .htaccess file in the Webadmin-directory. Make sure you set this otherwise other parties will be able to access your Webadmin scripts.

# allow only access from IP 192.168.0.5
allow from 192.168.0.5
deny all

2 User Functions

The following functions are designed to add/delete/modify users to the system. Listed per item are the variables needed to perform the operations.

Adding a User

<form method="post" action="http://yourdomain.com/atmail.pl">
<input type=hidden name=func value=newuser>
<input type=hidden name=NewUser value=1>
<input type=hidden name=username value=exampleuser>
<input type=hidden name=pop3host value=yourdomain.com>
<input type=hidden name=password value=secret>

<input type=hidden name=FirstName value=FirstName> (optional)
<input type=hidden name=LastName value=LastName> (optional)
<input type=hidden name=BirthDay value=4> (int) (optional)
<input type=hidden name=BirthMonth value=5> (int) (optional)
<input type=hidden name=BirthYear value=1980> (int) (optional)
<input type=hidden name=Gender value=F> (optional)
<input type=hidden name=Address value=Address> (optional)
<input type=hidden name=City value=City> (optional)
<input type=hidden name=PostCode value=PostCode> (optional)
<input type=hidden name=State value=State> (optional)
<input type=hidden name=Country value=au> (optional)
<input type=hidden name=TelHome value=TelHome> (optional)
<input type=hidden name=TelWork value=TelWork> (optional)
<input type=hidden name=FaxHome value=FaxHome> (optional)
<input type=hidden name=FaxWork value=FaxWork> (optional)
<input type=hidden name=TelMobile value=TelMobile> (optional)
<input type=hidden name=TelPager value=TelPager> (optional)
<input type=hidden name=OtherEmail value=alternate@email.net> (optional)
<input type=hidden name=PasswordQuestion value="This reminds me of my password"> (optional)
<input type=hidden name=Language value=Language> (has to exist in @Mail) (optional)
<input type=hidden name=LoginType value="Interface Type"> (has to exist in @Mail) (optional)
<input type=hidden name=Industry value=Industry> (optional)
<input type=hidden name=Occupation value=Occupation> (optional)

</form>

You can also formulate a URL to perform the action like:

http://yourdomain.com/atmail.pl?func=newuser&NewUser=1&username=exampleuser&pop3host=yourdomain.com&password=secret

I let out the optional fields here to avoid a very long line, but in general you should be able to find out how to communicate with the scripts used in @Mail. Unlike the command used above, all other commands take can be accessed using the webadmin/admin.pl script instead of the atmail.pl script used to add users.

Deleting a User

<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type="hidden" name="func" value="deleteuser">
<input type="hidden" name="user" value="exampleuser@yourdomain.com">
</form>

or http://yourdomain.com/webadmin/admin.pl?func=deleteuser&user=exampleuser%40yourdomain.com

Notice: You can't send an @-symbol in URL format. Replacing the @ with %40 will encode the string so and make it able to send the email. If you are interested in sending other illegal characters in URL format, please check out http://www.asciitable.com/. They have an overview of all ASCII characters and their codes. Make sure you replace a character by a %-sign, followed by the heximal (Hx) code in the overview.

Modifying a User

<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type="hidden" name="func" value="update">
<input type="Account" name="user" value="exampleuser@yourdomain.com">

<input type=hidden name="FirstName value="FirstName">
<input type=hidden name="LastName" value="LastName">
<input type=hidden name="BirthDay" value="4">
<input type=hidden name="BirthMonth" value="5">
<input type=hidden name="BirthYear" value="1980">
<input type=hidden name="Gender" value="F">
<input type=hidden name="Address" value="Address"> 
<input type=hidden name="City" value="City">
<input type=hidden name="PostCode" value="PostCode">
<input type=hidden name="State" value="State">
<input type=hidden name="Country" value="au">
<input type=hidden name="TelHome" value="TelHome">
<input type=hidden name="TelWork" value="TelWork">
<input type=hidden name="FaxHome" value="FaxHome">
<input type=hidden name="FaxWork" value="FaxWork">
<input type=hidden name="TelMobile" value="TelMobile">
<input type=hidden name="TelPager" value="TelPager">
<input type=hidden name="OtherEmail" value="alternate@email.net">
<input type=hidden name="PasswordQuestion" value="This reminds me of my password">
<input type=hidden name="Language" value="Language">
<input type=hidden name="LoginType" value="Interface Type">
<input type=hidden name="Industry" value="Industry">
<input type=hidden name="Occupation" value="Occupation">

<input type="hidden" name="UserStatus" value="0">
(1 = disabled, 0 = enabled)

<input type="hidden" name="UserQuota" value="5120">
(Mailbox Quota in kB)

<input type="hidden" name="Group" value="GroupName">
(A group your user may be a member of)

<input type="hidden" name="FullName" value="Firstname Lastname">
(Displayed Name)

</form>

http://yourdomain.com/webadmin/admin.pl?func=update&Account=exampleuser%40yourdomain.com&FirstName=FirstName&LastName=LastName....

If you fail to give the values to the old variables when posting the form, the old variables for the user will be overwritten with empty values.

Listing Users

When listing users, you can give all the user variables like Account, FirstName, Lastname, TelHome to select on. The Search function literally lets you create the SQL query to look for so you have to define options such as LIKE, NOT LIKE, "=" (equals) or "!=" (not equals). I will give an example below:

# Searching for Ben
<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type="hidden" name="func" value="searchinguser">
<input type="hidden" name="FirstName" value="ben">
<input type="hidden" name="FirstName_o" value="=">
</form>

http://yourdomain.com/webadmin/admin.pl?func=searchinguser&FirstName=ben&FirstName_o=%3D

# Searching for people with Ben in their First Name
<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type="hidden" name="func" value="searchinguser">
<input type="hidden" name="FirstName" value="Ben">
<input type="hidden" name="FirstName_o" value="LIKE">
</form>

http://yourdomain.com/webadmin/admin.pl?func=searchinguser&FirstName=Ben&FirstName_o=LIKE

# Searching for people with Ben in their name that are not from Australia
<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type="hidden" name="func" value="searchinguser">
<input type="hidden" name="FirstName" value="Ben">
<input type="hidden" name="FirstName_o" value="LIKE">
<input type="hidden" name="Country" value="au">
<input type="hidden" name="Country_o" value="!=">
</form>

http://yourdomain.com/webadmin/admin.pl?func=searchinguser&FirstName=Ben&FirstName_o=LIKE&Country=au&Country_o=%21%3D

# Available Fields to search using this function

Account, Group, UserStatus, pop3host, FirstName, LastName, Gender, 
BirthDay, BirthMonth, BirthYear, Address, City, PostCode, State, Country, 
OtherEmail, PasswordQuestion, Language, LoginType, Industry, Occupation

Notice: For every Field you query for you have to make a Field_o field as well.

Purging Users

Using the Purge Users function you can automatically delete all users that have been inactive for a certain amount of time.

<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type="hidden" name="func" value="purgeusers">
<input type="hidden" name="days" value="2">
<input type="hidden" name="confirm" value="yes">
</form>

http://yourdomain.com/webadmin/admin.pl?func=purgeusers&days=2&confirm=yes

Sending the form in the example above will cause all users that have inactive for at least 2 days to be deleted.

3 Domains Functions

adding and deleting domains work exactly the same as users, only you have to give less variables when creating a form. The form is somewhat more simple.

Adding a Domain

<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type=hidden name=func value=domains>
<input type=hidden name=Add value=1>
<input type=hidden name=Domain value=yourdomain.com>
</form>

http://yourdomain.com/webadmin/admin.pl?func=domains&Add=1&Domain=mydomain.com

Deleting a Domain

<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type=hidden name=func value=domains>
<input type=hidden name=Delete value=1>
<input type=hidden name=Del value=mydomain.com>
</form>

http://yourdomain.com/webadmin/admin.pl?func=domains&Delete=1&Del=mydomain.com

Listing All Domains

<form method="post" action="http://yourdomain.com/webadmin/admin.pl">
<input type=hidden name=func value=domains>
</form>

http://yourdomain.com/webadmin/admin.pl?func=domains

4 Example code

The example Perl code below, will create a new @Mail account via the command-line.

#!/usr/bin/perl
# makeacct.pl :
# Change to your @Mail URL
my $atmailscript = "http://192.168.1.1/atmail3/atmail.pl";

# Load the Perl module to communicate via http
use LWP::Simple;

# Define the account to create, from the command line arguments
my $user = $ARGV[0];
my $pass = $ARGV[1];
my $pop3host = $ARGV[2];
my $language = $ARGV[3] || 'english';
my $interface_type = $ARGV[4] || 'blue_pane';

die "Please specify an account username, password and pop3host" if(!$user && !$pass && !$pop3host);

print get("$atmailscript?username=$user&password=$pass&pop3host=$pop3host& Language=$language&LoginType=$interface_type&NewUser=1");
# End

To run the script:

command# perl makeacct.pl myuser mypass mydomain

5 Contact Support

For additional support, please visit our web site, http://webbasedemail.com
Or send us an eMail : support@CalaCode.com