DevCity.NET -
Using C# to Create Distribution Lists
Muthukumar V
I am a Programmer in C++/VC++/C#. 
by Muthukumar V
Published on 5/10/2005

   This article sets out to explain how to access the exchange domain and create a distribution list  programmatically using C# and Active Directory .    A sample program is used which combines  both CDO and ADSI for creating distribution list with C#. This can easily be extended to creating mailboxes also.


Home Page:

  A Distribution List can be created like a normal mailbox with only a small difference.  This is that it can contain other mailboxes and distribution lists as members for itself. A mailbox or a distribution list is created below the Site Container of an Exchange domain. Once this entity is created depending on the replication timing, it becomes available on the Global Address List. This article tries to explain how to access the exchange domain and create a distribution list and create a distribution list programmatically using C# and Active Directory.

   Typical Issues that arise when someone programmatically tries to create the distribution list is that they cannot create a distribution list if they are not connected to the server on the site. i.e., If the user of Site1 tries to modify the details of a Distribution List on a different site say Site2 through the program, this won't be permitted. In this case the user with administrator rights must logon again using the server which hosts the corresponding site.

   Some other issues could be like finding all the connected Sites, Servers in an exchange environment. Also parsing the address book for some data using ADSI will likely to be slow. This article and the sample program use an approach combining both CDO and ADSI for creating distribution list with C#. This can easily be extended to creating mailboxes also.

Microsoft Exchange Architecture:

A Microsoft Exchange Environment can be configured to contain many sites under a domain. Though all of us might know this, this might be useful if we do a small preview of the basic details.

If a domain is available as root, there could be many sites configured under the root domain of like London, Newyork, Moscow. This has many advantages.

  • Easier localized management of users.
  • Logical classification of employees/users
  • Faster access because of localized placement of servers
  • All the mail addresses can be accessed together through a Global Address List.
  • and many more..

   And apart from this each of the domains can contain many servers which can handle the mail delivery mechanisms to share the load of the site under the domain. The architecture looks something like this.

  Typically if a user wants to modify any Distribution List members or any other data of Distribution list the user has to have the relevant admin rights. The Microsoft Exchange Administrator program is usually used to make  the modifications on these data on Distribution List. Occasionally Outlook can also be used to modify the membership of the Distribution List, provided the logged on user is either an administrator or he is the owner of the distribution List. But whatever may be the case, cross site modifications are not allowed. So the program has to be careful to use the correct server in order to do the same.


Creating the Distribution List:
A distribution list can be created by accessing the Active directory. The object distinguished name of a distribution list will typically look like 

   A Distribution list needs two very basic attributes to be specified at the minimum. One is display name and the second is the alias. A distribution list or a Mailbox can be created only under the Recipients container. 

   To create a distribution list under the Recipients container,

  1. Get the ADSI DirectoryEntry for the Recipients container.
  2. Create a distribution list by specifying "groupOfNames".
  3. Specify the other properties like displaynames, smtp, x400, owner etc.,
  4. Ensure that the Security Descriptor is properly set for the owner attribute.
  5. Commit the changes to the AD.

  The class DirectoryEntry.Children.Add("distributionlistname","groupOfNames") can be used for creating a Distribution List under the recipients container. A call to this function returns an object for the DirectoryEntry for the newly created Distribution List. This does not actually get updated until we call the DirectoryEntry.commitchanges method.

   After getting a pointer to the Distribution list as an object of DirectoryEntry, the following properties are to be updated before calling CommitChanges.

DisplayName Property:

   This is denoted by the cn property name in Exchange. This can be updated by calling the DirectoryEntry.Properties["cn"]. Do call this once before committing the Changes. This ensures that the Display name is updated properly.

Alias Property:

   This is denoted by the uid propertyin Exchange Server. This is the alias name for the distribution list and will typically be used for creating the Object Distinguished name under the container.

Email Addresses Property:

   There could be many types of email addresses in an Exchange environment. They may be smtp, x400, ccmail etc., Set the relevant email addresses. If it is smtp, then mail attribute should be set and for X400 it is textencodedaddress.

   While discussing about the email addresses one point is worth mentioning. The Exchange server keeps all the Email addressing data under a node at SiteAddressing. This data can be pulled from an attribute called GateWay-Proxy, which is not available via ADSI. But it can be pulled using ADO.

Members of Distribution List:

   This is managed under the member property of Exchange. This is an array of list of mailboxes or distribution lists.


   This property is stored under the owner attribute of the Distribution List. There will be a problem when we create the DL and assign an owner. As the DL is freshly created, it won't have any SecurityDescriptor associated with it. To solve this problem, we can pull the SecurityDescriptor of the owner and assign it to the DL.

   The Properties of Exchange 5.5 do not understand the LDAP naming with slashes. It returns an error saying Protocol Error. In such cases, use the comma formatted LDAP Object Distinguished Names. I am not sure about the later versions of Exchange. Be sure to check this out.

   Also some of the properties while setting may return an error saying that the property is not found. In those cases, use the DirectoryEntry.Properties.Add function to add the property. The reason is because, the exchange directory may not keep the property fields if it is not a Required field. In such cases, adding the property will help.


Attached Sample

The attached sample includes two parts. One is the set of classes which can be reused as such for any C# DL Creation programs or may be extended. The second is the DL Creation functional part. This extensively uses CDO libraries for finding the necessary Server names, Site Names and the much needed Object Distinguished names for many entities.

   The attached sample project can be downloaded here.

Reusable Classes:

   There are two classes available in the DLManagement namespaces which can be used in other C# programs. One class called DLManager, holds the utility functions which could be used for common operations required for creation or modifications of distribution list. The other class DistributionList, holds the data regarding the Distribution List.

   These reusable classes can be downloaded here.


   Some of the functions in this DLManager are described as below. All the functions in this class are static public members. So they can be used without instantiating this class.

  • GetSites   - This function can return a list of sites under an Exchange organization.
  • GetOrganization - This function returns the Organization name for a CDO Address entry object
  • IsLDAPEntryWithSlashes - Some properties of Exchange 5.5 need the entries with comma separated names in Object Distinguished Names. This function can be used to check if the entry contains slashes.
  • GetHomeServer - This can be used to find the Home server for a particular distribution list.
  • UpdateDL     - This function can be used for either creating or modifying a DL. This takes care of setting all the above said properties, including adding the owner of the DL with its Security Descriptor.
  • FindDL - This function can find and populate the details of a DL and return an object of DistributionList class.
  • FindSMTPAddressing - This function gets the SMTP Addressing format for a site using ADO.


   This class contains only data members to hold the properties of DLs. This can be used either way to retrieve or update the Distribution Lists using the DLManager class.


    This application was written with Visual Studio .Net 2003. The Libraries used are as follows:

  • Microsoft CDO 1.21 Libraries. This is available by default in your system if Outlook 2000 or above is installed.
  • ADODB. This can be included from References --> Com --> Microsoft ActiveX Data Objects 2.6 & above.
  • System.DirectoryServices