How to: Manage the Hosted Email Service

 

Applies To: Windows Server 2012 Essentials

Once you have created an adapter that implements IHostedEmailAdaptor, you can access your hosted email service management features. These features include email account creation, deletion, and password resetting. For most scenarios, an administrator will access their email accounts through the Dashboard UI’s that you have updated and modified. (For more information, see Modifying the UI.) You can also write separate applications to access the same management capabilities. Regardless of your scenario, you access the service management capabilities through HostedEmailManager.

HostedEmailManager exposes a number of management features, from creating, deleting, updating, and enabling/disabling an account, retrieving account and domain information, and resetting passwords. The object exposes both synchronous and asynchronous versions of the members. In addition, the object exposes events you can hook into for account update warnings. Generally speaking, the features you implement in IHostedEmailAdaptor are available through HostedEmailManager.

Warning

In addition to working through the HostedEmailManager object, you can also retrieve service information through the HostedEmailIntegrationManager object. For more information see How to: Manage the Add-In.

The following code samples all demonstrate how to use the HostedEmailManager to retrieve and modify information regarding the hosted email service. For the complete code samples, see Quickstart: Creating a Hosted Email Adapter.

Example

The following code demonstrates how to use the HostedEmailManager to hook into events and retrieve email domains. The code below was designed to retrieve the domain information, immediately after a successful connection attempt was made from the Dashboard to the hosted service.

private void Manager_ConnectCompleted()  
        {  
            manager.HostedEmailAccountUpdated += OnEmailAccountUpdated;  
            QueryDomainNames();  
            QueryMailboxNumber();  
        }  
        private void OnEmailAccountUpdated(object sender, HostedEmailAccountUpdatedEventArgs e)  
        {  
            QueryMailboxNumber();  
        }  
  
        private void QueryDomainNames()  
        {  
            manager.BeginGetDomains((sender, e) =>  
            {  
                if (e.Error != null)  
                {  
                    UpdateDomains(false, true);  
                }  
                else  
                {  
                    domains = e.Result;  
                    UpdateDomains(false, false);  
                }  
            });  
        }  
  

Example

The following code sample shows how to retrieve the email account information for a specified Windows Server Essentials user. This particular code is designed to be used on a Dashboard UI that displays the distribution lists that a specified user belongs to.

private void LoadEmailAccountInfo(string wssUserName)  
{  
    HostedEmailManager manager = new HostedEmailManager(Constants.AdaptorId);  
    if (!manager.Connect())  
    {  
        throw new InvalidOperationException("HostedEmailManager connection failed");  
    }  
    var info = manager.GetAccount(wssUserName);  
  
    if (info == null || info.ExtendedProperties == null || !info.ExtendedProperties.ContainsKey(Constants.ExtendedParam_DGs))  
    {  
        throw new InvalidOperationException("Cannot load distribution groups that the user belongs to");  
    }  
    accountId = info.AccountId;  
    userDGs = info.ExtendedProperties[Constants.ExtendedParam_DGs].Split(Constants.ExtendedParam_DGs_Delimiter);  
}  
  

Example

The following code sample shows how to link an OK button click to an account update. The code sample is pulled from a UI update on the Advanced button of the User Properties form.

private HostedEmailManager manager = new HostedEmailManager(Constants.AdaptorId);  
…  
private void buttonOK_Click(object sender, EventArgs e)  
        {  
            if (null != EmailAccountInfo.ExtendedProperties)  
            {  
                EmailAccountInfo.ExtendedProperties[KeyForwardEmail] = this.textBoxEmail.Text;  
                EmailAccountInfo.ExtendedProperties[KeyActiveSync] = this.checkBoxActiveSync.Checked.ToString();  
            }  
  
            bool err = false;  
  
            using (ManualResetEvent done = new ManualResetEvent(false))  
            {  
                ThreadPool.QueueUserWorkItem((state) =>  
                {  
                    if (!manager.Connected)  
                    {  
                        if (!manager.Connect())  
                        {  
                            err = true;  
                            done.Set();  
                            return;  
                        }  
                    }  
  
                    try  
                    {  
                        manager.UpdateAccount(UserName, EmailAccountInfo);  
                    }  
                    catch (Exception)  
                    {  
                        err = true;  
                    }  
  
                    done.Set();  
                });  
                done.WaitOne();  
            }  
  
            if (err) popupErrorMsg();  
        }