Creating user accounts and logging in programmatically

Summary

If your web site has its own sign in form where users should specify their e-mail (or just login) and password to log into their private area, it makes sense to use these credentials to log into their WebMail Pro accounts. Of course, it's inconvenient to type the same credentials again in WebMail sing-in form. Special integration API allows you to avoid this. It allows direct entering not only message list, but other WebMail screens like compose new message, calendar, etc.

To bypass WebMail sign-in screen and enter user's email account directly, it's necessary to pass some data that identify user in WebMail system. WebMail provides Integration object for this purpose.

NB: This was only tested with .NET Framework 4.* and seems it will not work with newer versions of .NET.

Integration object

Usage of Integration object is simple:

1. Add a reference to WebMail.dll to your project (in Visual Studio 'Project->Add Reference...'). WebMail.dll is located in the bin subfolder of the root folder of your AfterLogic WebMail installation.

2. Import WebMail namespace:

using WebMail;

3. Create "CIntegration" object:

Integration integr = new Integration(@"C:\WebMail-Pro-Net\data", @"http://myserver/webmailpro/");

The first parameter is a physical path (not URL) to the WebMail data folder. The same path is specified in web.config file in the WebMail root folder. Relative paths like ../webmail_pro_data are supported too.

The second parameter is URL path to the WebMail root folder necessary for correct UserLoginByEmail method work. Please note, it's not a physical path like C:\inetpub\wwwroot\WebMail, but an URL like http://www.mydomain.com/webmail or relative URL like subparts/webmail.

4. Now, for instance, we need to log a user into WebMail bypassing standard sign in screen. Let's call UserLoginByEmail method for this purpose:

integr.UserLoginByEmail(@"user@domain", "user", "password", WMStartPage.Mailbox);

"user@domain" - user's full e-mail address;

"user" - user's login (username). It may be either full e-mail address or just username without domain part, depends on your mail server configuration;

"password" - user's password. May be equal to null;

WMStartPage.Mailbox - enumeration member determining the screen the user will be redirected to after logging in.

For more various examples, see Usage Examples.

Methods

GetAccountById(id)	Gets Account object by id of user in the database (awm_accounts.id_acct), or null on error.
GetAccountByMailLogin(email, login)	Gets Account object by e-mail address and login or null on error. email, login - required parameters.
CreateUser(email, login, password)	Creates a user in WebMail database. email, login, password - required parameters Default values are assigned to all other settings like POP3/IMAP4/SMTP servers, etc.
CreateUserFromAccount(account)	Creates a user in WebMail database using the settings specified in Account object. If WebMail is used with XMail Server, the user will also be created in XMail Server data structure.
UserExists(email, login)	Checks if the user exists in WebMail database. email, login - required parameters. Returns true if the user exists, false if doesn't.
UserLoginByEmail(email, login, password, startPage, recipient)	Performs login and redirects the user into WebMail system. IMPORTANT: that user must already exist in WebMail Pro database, otherwise, logging in will fail, in this case, it's necessary to create the user first. See this example for more details. email, login - required parameters. startPage - enumeration member determining the screen the user will be redirected to after logging in. password - may be equal to null. If null, password validation is not performed, i.e. means "any password", but not "empty password". recipient - e-mail address which will be put into To field. Is used in case of redirection to compose message screen (WMStartPage.NewMessage) only, in other cases should be null.
DeleteUserById(id)	Deletes the specified user from WebMail database. To get id, you can use Account.ID. You can get Account object with GetAccountByMailLogin method. If WebMail is used with XMail Server, the user will also be deleted from XMail Server data structure.
DomainExists(name)	Checks if the domain with the specified name exists in WebMail database. name - required parameter (e.g. domain.com). Returns true if the domain exists, false if doesn't.
CreateDomain(domain)	Creates a domain in WebMail database using the settings specified in Domain object. If WebMail is used with XMail Server, the domain will also be created in XMail Server data structure.
DeleteDomain(domain)	Deletes the specified domain from WebMail database. If WebMail is used with XMail Server, the domain will also be deleted from XMail Server data structure.
All these methods may throw WebMailException.

WMStartPage enumeration members

determines the screen the user will be redirected to after logging in

Value	Description
Mailbox	Message list screen
NewMessage	Compose message screen
Settings	User's settings screen
Contacts	User's contacts screen (addressbook)
Calendar	User's calendar screen

Account object

represents a user account in WebMail, contains all user account settings and is used for more flexible user accounts management

Value	Description
ID (int)	Account unique identifier (awm_accounts.acct_id).
Email (string)	Email address.
DefaultAccount (bool)	Indicates if the account is default (primary), i.e. can be used for logging into WebMail.
MailIncomingProtocol (WebMail.IncomingMailProtocol)	Protocol of the account. Possible values: IncomingMailProtocol.Pop3 - POP3 protocol. IncomingMailProtocol.Imap4 - IMAP4 protocol. IncomingMailProtocol.WMServer - local mail server protocol.
MailIncomingHost (string)	Incoming mail server address (e.g. mail.domain.com).
MailIncomingPort (int)	Incoming mail server port number (110 for POP3, 143 for IMAP4).
MailIncomingLogin (string)	Login for incoming mail server.
MailIncomingPassword (string)	Password for incoming mail server.
MailOutgoingHost (string)	Outgoing mail server address (e.g. mail.domain.com).
MailOutgoingPort (int)	Outgoing mail server port number (25 for SMTP).
MailOutgoingLogin (string)	Login for outgoing mail server.
MailOutgoingPassword (string)	Password for outgoing mail server.
FriendlyName (string)	A name to be added to e-mail address in From field of outgoing messages.
GetMailAtLogin (bool)	Indicates if message receiving should be performed automatically after logging into WebMail under this account.

Domain object

Value	Description
ID (int)	Domain unique identifier (awm_domains.id_domain).
Name (string)	Domain name.
MailIncomingProtocol (WebMail.IncomingMailProtocol)	Protocol of the account. Possible values: IncomingMailProtocol.Pop3 - POP3 protocol. IncomingMailProtocol.Imap4 - IMAP4 protocol. IncomingMailProtocol.WMServer - local mail server protocol.
MailIncomingHost (string)	Incoming mail server address (e.g. mail.domain.com).
MailIncomingPort (int)	Incoming mail server port number (110 for POP3, 143 for IMAP4).
MailOutgoingHost (string)	Outgoing mail server address (e.g. mail.domain.com).
MailOutgoingPort (int)	Outgoing mail server port number (25 for SMTP).
MailOutgoingAuthentication (bool)	Use SMTP authentication

Usage examples

Example 1

On the ASP.NET page you want to launch WebMail from, add the lines similar to the following:

Integration integr = new Integration(@"C:\WebMail-Pro-Net\data", @"http://www.mydomain.com/WebMail-Pro-Net/");
try
{
    integr.UserLoginByEmail(@"user@domain", "user", "password", WMStartPage.NewMessage, "user1@domain");
}
catch (WebMailException ex)
{
    // handle exception
}

The code above will redirect to WebMail system and immediately open message compose screen with 'user1@domain' address in To field. Please note, the account you need to log into must already exist in WebMail Pro database.

Once UserLoginByEmail method called, there are two cases possible:

• Specified email address was found in WebMail database. The user is redirected to Inbox of the email account. Email account properties are taken from the database (you can adjust them in Admin Panel).
• Specified email address was NOT found in WebMail database or an error occurred. In such case WebMailException will be thrown.

Example 2

On the ASP.NET page you want to launch WebMail from, add the lines similar to the following:

Integration integr = new Integration(@"C:\WebMail-Pro-Net\data", @"http://www.mydomain.com/WebMail-Pro-Net/");
try
{
    integr.CreateUser("user@localhost", "user", "password");
}
catch (WebMailException ex)
{
    Response.Write(ex.Message);
}

This sample demonstrates simple creating user in WebMail database. On error, it displays error description.

Example 3

On the ASP.NET page you want to launch WebMail from, add the lines similar to the following:

Integration integr = new Integration(@"C:\WebMail-Pro-Net\data", @"http://www.mydomain.com/WebMail-Pro-Net/");
try
{
    Account acct = integr.GetAccountByMailLogin("user@localhost", "user", "password");
    Response.Write(acct.Email);
}
catch (WebMailException ex)
{
    // handle exception
}

This sample gets all user's data (as Account object) from WebMail database.

Example 4

On the ASP.NET page you want to launch WebMail from, add the lines similar to the following:

Integration integr = new Integration(@"C:\WebMail-Pro-Net\data", @"http://www.mydomain.com/WebMail-Pro-Net/");

string email = "john_doe@mydomain.com";
string login = "john_doe";
string password = "mypassword";

string pop3 = "pop.mydomain.com";
string smtp = "smtp.mydomain.com";

try
{
    integr.UserLoginByEmail(email, login, password, WMStartPage.Mailbox, null);
}
catch (WebMailException)
{
    // Failed to log in, will try creating such account
    Account acct = new Account();
    acct.Email = email;
    acct.MailIncomingLogin = login;
    acct.MailIncomingHost = pop3;
    acct.MailIncomingPassword = password;
    acct.MailIncomingPort = 110;
    acct.MailOutgoingLogin = login;
    acct.MailOutgoingHost = smtp;
    acct.MailOutgoingPassword = password;
    acct.MailOutgoingPort = 25;
    acct.MailIncomingProtocol = IncomingMailProtocol.Pop3;
    acct.MailOutgoingAuthentication = true;

    try
    {
        integr.CreateUserFromAccount(acct);

        try
        {
            integr.UserLoginByEmail(email, login, password, WMStartPage.Mailbox, null);
        }
        catch (WebMailException ex)
        {
            Response.Write("Error: failed to log into the account. Reason: " + ex.Message);
        }
    }
    catch (WebMailException ex)
    {
        Response.Write("Error: failed to create the account. Reason: " + ex.Message);
    }
}

Also, you need to add a reference to WebMail.dll to your project (in Visual Studio 'Project->Add Reference...'). WebMail.dll is located in the bin subfolder of the root folder of your AfterLogic WebMail installation. Importing WebMail namespace is necessary too:

using WebMail;

This universal sample can be used in most cases. First, it tries to log user into his account. If the account doesn't exist, it tries to create it (with extended settings set). On success, it tries to log into the account just created. On any error, it displays error details.

IMPORTANT NOTE: The main difference between this example and Example 1 is that Example 1 allows logging into accounts which already exist in WebMail database, while this example creates new accounts in the database if they don't exist there. Sometimes, it's necessary to log into existing accounts only and you should refer to Example 1 in such case.

Example 5

Example 4 creates user with extended settings set, i.e. it calls CreateUserFromAccount method. This is necessary when you need to explicitly specify mail server settings (like in this sample, to create user in a domain not listed in Admin Panel) or any other settings. If you need to create an account with default settings specified in Admin Panel, you may simplify this sample as follows:

Integration integr = new Integration(@"C:\WebMail-Pro-Net\data", @"http://www.mydomain.com/WebMail-Pro-Net/");

string email = "john_doe@mydomain.com";
string login = "john_doe";
string password = "mypassword";

try
{
    integr.UserLoginByEmail(email, login, password, WMStartPage.Mailbox, null);
}
catch (WebMailException)
{
    // Failed to log in, will try creating such account
    try
    {
        integr.CreateUser(email, login, password);

        try
        {
            integr.UserLoginByEmail(email, login, password, WMStartPage.Mailbox, null);
        }
        catch (WebMailException ex)
        {
            Response.Write("Error: failed to log into the account. Reason: " + ex.Message);
        }
    }
    catch (WebMailException ex)
    {
        Response.Write("Error: failed to create the account. Reason: " + ex.Message);
    }
}

Example 6

All the examples above assume WebMail Pro and your application are deployed on the same physical machine. In other words, you can easily reference WebMail.dll on local filesystem as well as specify physical path to the WebMail data folder. What to do if you need to integrate them when they're running on two different machines? The steps below would allow you to achieve that.

Let's assume your application is deployed on machine A, WebMail on machine B. The following conditions should be met:

1. Both the machines must be in the same local network.

2. MS Access database cannot be used as it cannot be accessed from local network, it's required to use MS SQL Server or MySQL database.

3. Both A and B machines must be able to connect to the same database server.

4. If the database connection is configured (in Admin Panel / WebMail / Database Settings) through DSN, you should create the same DSN on both A and B machines. In case of database connection through Host, nothing additional should be done on machine A.

5. Integration object created by your application on machine A needs access to WebMail configuration file (\App_Data\settings\settings.xml) which is located on machine B. There're two ways to pull it round:

a) share WebMail data folder on machine B and set the Integration object on that path.

b) duplicate \DATA\settings folder along with settings.xml on machine A.

a. The way with sharing WebMail data folder.

Let's look at pros and cons of this way:

+ a single instance of settings.xml file, you don't need to bother about synchronizing the second copy on machine A when the original is changed by AdminPanel on machine B;

- you need to share the data folder for network access and take some security measures.

The easiest way is to share the data folder for public access, but it's insecure as any user is able to get the contents of that folder. You should create a new domain user and share the WebMail data folder to it, read permission is enough. So, no security breach would appear. The below is a bit modified Example 1:

Powerup.LicenseKey = "Your license key here";   // Your MailBee.NET Security license key here
Impersonation imperson = new Impersonation();
imperson.LogonAs("network_user", "domain.local", "password");

Integration integr = new Integration(@"\\LOCAL-SERVER\WebMail-Pro-Net\data", @"http://www.mydomain.com/WebMail-Pro-Net/");

try
{
   integr.UserLoginByEmail(@"user@domain", "user", "password", WMStartPage.NewMessage, "user1@domain");
}
catch (WebMailException ex)
{
  // handle exception
}
finally
{
  imperson.Logoff();
}

The trick is in the first three lines and the finally block. Your ASP.NET application is running under a local system account (local for machine A, usually, it's NETWORK SERVICE), but that local account is not allowed to access the network path you shared WebMail Pro data folder at. So, your application has to impersonate the domain user you've shared the data folder to.

Arguments of LogonAs method:

• "network_user" - name of domain user account you shared the data folder to;
• "domain.local" - name of the domain the user account belongs to;
• "password" - password of the domain user account.

Also, you should add reference to MailApi.dll to your project and import MailBee.Security namespace.

If you'll be using Impersonation implemented in MailBee.NET Objects, you'll need a license for MailBee.NET Security component. Alternately, you can use impersonation implemented in any third-party component.

b. The way with duplicating WebMail settings folder.

Pros and cons:

+ nothing needs to be shared, no additional security measures needed;

- you need to synchronize the copy of settings.xml file on machine A with the one on machine B when AdminPanel updates it (when you change settings in its interface).

If you chose this way, you should copy the \App_Data\settings folder (with contents) from machine B to A and set integration script on that path as in the samples above.

Example 7

Now, let's take advantage of both the integration aspects. First, please create test-iframe.aspx/test-iframe.aspx.cs file as shown here and copy/paste the code from Example 4 there, then modify the example to get it working in your environment. It's assumed that you placed that file into the web folder of your ASP.NET application. Now, just add the following line to one of your ASP.NET pages:

<iframe src="test-iframe.aspx" style="width: 900px; height: 600px;"></iframe>

As you can see, it refers to the file with the integration script you created previously. Both test-iframe.aspx and the page you placed the IFRAME to are in the same folder.

Now, you may wonder how to pass authentication data from your ASP.NET application to UserLoginByEmail method called in test-iframe.aspx. Don't pass that data through GET method (in URL after ? char) for security reasons, but use server-side ASP.NET sessions instead. Example:

• A part of default.aspx file:

<%
// Store credentials in session
Session["email"] = "john_doe@mydomain.com";
Session["login"] = "john_doe";
Session["password"] = "mypassword";
%>
<iframe src="test-iframe.aspx" style="width: 900px; height: 600px;"></iframe>

• A part of test-iframe.aspx.cs file:

Integration integr = new Integration(@"C:\WebMail-Pro-Net\data", @"http://www.mydomain.com/WebMail-Pro-Net/");

try
{
    integr.UserLoginByEmail(Session["email"], Session["login"], Session["password"], WMStartPage.Mailbox, null);
}
catch (WebMailException ex)
{
    Response.Write("Error: failed to log into the account. Reason: " + ex.Message);
}