Personal tools
You are here: Home Project Papers Communicating with Congress by way of Advocacy Groups: The Topic Code

Communicating with Congress by way of Advocacy Groups: The Topic Code

(part of the ongoing project, Advocating for a Healthy Online Political Ecology )

  1. Background
  2. The Problem
  3. The Current Electronic Messaging Infrastructure
  4. The Solution: The Topic Code and Exposing the XML Layer
  5. Future Developments
  6. Frequently Asked Questions About the Topic Code
  7. Examples


It is vital for technology experts to work closely with political wonks and legislative experts to develop the tools and applications for a healthy online political ecology. In the case of sending messages to Congress by way of advocacy groups this has been a very long road with plenty of bumps and scrapes along the way. This paper sets out to explain a major step in the evolution of citizen to Congress communication. To develop a solution to the current situation an effort had to be made to meld the interests of everyone with technology. And bringing together political folks with technical folks often results in both sides speaking past each other.

However, there are some interesting parallels between the goals of both the political and technical folks. Both sides have similar abstract principles. For both those principles should include the need to keep barriers to entry as low as possible, to use a common words and avoid jargon, be as open as possible, abide by standards that are reached by consensus, avoid complex solutions when simple ones will suffice, make sure that any records can be preserved for historical and analytical purposes, allow as much communication as possible, and not let noise crowd out worthwhile interaction. It is not an accident that these principles apply equally well to healthy and successful political discourse and powerful online technology: both a body politic and the Internet can be defined as being a network. And it is crucial that these principles be raised at the beginning any discussion of any new political technology.

It may be difficult for non-technically inclined people to understand the underlying technology that powers the web. And tech staff often has an understandably difficult time explaining the various and brand new technologies. However, people who oversee legislative or political organization and ignore technology and relegate it to their technological staff to make crucial decisions will often waste resources and opportunities. In the early days of the Internet when the general audience was skewed and the tools untested, the harm done was minimal. Now the Internet has reached much of the promises of the early days, near universal access, a key communications vehicle, and a considerable workforce multiplier, administrative linchpin (what organization does not depend on email, Blackberry alerts, etc?). All of this is easier stated than done, but there can be some straightforward considerations that can be addressed to attain the goals of successful organizations that function within a healthy online political ecology.

The Problem

I will use the example of citizen to congressional communication where organizations direct citizen supporters to electronically petition members of Congress. Since 1993 when public email was made available for congressional offices to receive messages, citizens have opted in greater numbers to use the Internet as the means to send messages to Congress. Quickly, advocacy organizations saw this communications vehicle as advantageous for many reasons. However, it added a layer to the communications route from citizen to Congress. Where the layer added lay is the most difficult aspect of the problem, because a solution had been worked out for receiving messages from each member’s of Congress official web site.

Compounding the issue was the issue of volume. Where in the past, if messages came in with unintentionally or intentionally bad data (e.g. incorrect address), the staffer could either correct the incorrect information or physically sort out the bad letters. Now the messages come into one long list that can entail scrolling for hours. And since the overall volume of correspondence has increased, the ability to physically sort incoming messages (e.g. moving the rack of telegrams to a shelf for another week), the level of staffing has not increased to accommodate the additional load. Also, much the staffers are unaware of the many tools at their disposal to sort, correct, and delete bad messages. And the outside groups are constantly working to further increase the overall messaging into this system.

Under paid and overworked staff have taken to setting up roadblocks to outside messages generally including not having or an email address for constituents to send messages. Additionally, taking advantage of the extra layer added by many outside groups (which could just route people to the actual web form with a web link), several offices have added CAPTCHA, "Completely Automated Public Turing test to tell Computers and Humans Apart" barriers to their web forms (mainly in the form of a logic puzzle). Members of Congress unable to individually to better their offices situation and not knowledgeable about the underlying technology approve of such measures. The increase in the barriers to electronically communicate with congressional offices has frustrated the attempts for outside groups to pass messages from citizens on to congressional offices.

The problem created by the listed conditions is that the ability of citizens and elected officials to communicate has been seriously compromised. Representational democracy in a republic relies on the free flow of ideas and concerns between citizens and elected representatives. Understanding that this is the actual problem as opposed to the various causes and symptoms of the situation is paramount. The breakdown of communication can lead to Members of Congress being unable to take the pulse of their most vocal constituencies, to a large segment of citizens to become disengaged or disenchanted with the quality of their representation.

Fortunately, fixing the problem involved a couple of simple solutions and an understanding of the current electronic messaging infrastructure and various issues that have arisen.

The Current Electronic Messaging Infrastructure

For about twenty years a computerized system for handling correspondence to Congress has developed into a fairly efficient application called a Correspondence Management System (CMS). Essentially, messages would arrive at a congressional office. Staffers would read the messages, data entry the name and postal address as well as a name or computer file name for the response to be drafted for each message. Quite often if there had been other correspondence on the same issue received it was likely that there already existed a name for the response letter which may already or not been written. Then each office had their own system for drafting, approving and then printing the responses.

In the pre-Internet age advocacy organizations brought their supporters voices to Congress, using included postcards, Western Union “telegrams,” and other easy to identify campaigns diminished in proportion (if not in actual numbers). Whereas, some offices would take postcard trays and stack them for months and others might dismiss them altogether, generally they were viewed as a hassle to deal with by staff. Quite often the cards or letters seemed to be an adjunct to fundraising direct mail pieces and the messages were often not timely or relevant to pending legislation. Many congressional staff weakened the effect of the messages by not including them in a timely manner to the mail reports that many Members of Congress if at all as well as describing them as less important when reported.

When the House of Representatives and Senate first started allowing individual offices to have public email addresses for constituent communications, the existing CMS applications did not have a means for dealing with email differently than all other forms of messages. Most offices just printed the email messages and added them to the stack of other letters, faxes, postcards and telegrams in order to keep the system that their office had developed using the CMS application. The responses would be then printed and mailed to the postal address given on the correspondence. Some offices tried to email responses by using the email software to directly respond despite the extra work entailed by being unable to use their CMS application to accurately track and send responses as well as create accurate mail reports.

To solve this disconnect the company Intelligent Solutions (now absorbed as a division Lockheed Martin) worked with Congresswoman Eshoo’s office to expand the ability of the CMS used in that office. The first step was to analyze the problem of receiving the message directly into the CMS application (at that time known as Quorum 10). Email messages were essentially unformed electronic data for all but the email address and subject manner (except where the received email address and subject were contradicted by the unformed message, in which case the whole message would be considered unformed).

Intelligent Solutions and Eshoo’s office decided to use web forms as an electronic way to allow messages to be formed in such a way to be automatically added the CMS. The response would be posted similar to a web mail system does today with a password created for the initial correspondence and used for any following correspondence as well. The web form automatically sent an email with a formatted XML body (within the text of the email message, not as an attachment). Other offices adopted this system called CitizenDirect.

The CitizenDirect web system was developed as an additional method of communication electronically, not in order to supersede or replace email. However, many offices that used CitizenDirect decided to turn off their office’s public email to allow for the much easier to deal with CitizenDirect messages. At about the same time web sites for members of Congress not using CitizenDirect, became popular. Those offices used the web form developed by the House Information Resources staff or their own as a means to receive messages that although unformed would at least include all the required information. Many of these offices, inundated with email messages that were not from constituents and often unrelated to any aspect of the official business of their offices, turned off their email addresses.

Soon after developing CitizenDirect, Intelligent solutions created a sophisticated method add-on to their CMS called the Internet Mail Agent for accepting unformed emails, in addition to the XML formatted ones, directly into their CMS application and also allowed for responding with email instead of the password protected message posted to the web. The same XML formatting was retained for the messages and eventually was adopted officially by the House of Representatives for all CMS vendors as well as the official Write Your Rep web form system.

The XML format (see example 1) allowed for the name, email address, postal address, whether a response was requested, as well as a text message. The IMA system allowed for some other data as well which was not included in the official format adopted. However, it was generally impossible for outside organizations to use the system directly.

Many advocacy groups decided to use commercial solutions that could track each of the 540 plus House and Senate offices accepting constituent messages electronically. Generally the system would write through the web forms on the congressional web sites. In other words, a constituent would fill out a web form on the web site of an advocacy web site, and that data would be used by the commercial solutions to automatically fill in the web forms on the congressional sites.

The XML layer that allowed easy data communication was very simple, but unavailable. In addition, outside organizations greatly increased the amount of messages through the system, making the solution of a one track solution to processing and tracking correspondence actually harder. Although there was always bad information, the multiple layer system fostered an increase of potential mistakes and problems. Many offices complained about bad actors (those outside groups that due to the low cost of sending messages would feel free to bombard congressional offices with intentionally false data or misrepresent the efforts of citizens).  Although most well trained offices using the powerful CMS applications as well as pre-populated databases of all registered voters should have been able to deal with most bad incoming data, most offices seemed to be unable to manage.

One major aspect of most messages and especially those generated through advocacy groups, is that the messages tend to be easily lumped into clusters that could receive the same response. Many offices and most of the CMS applications had methods, although rudimentarily, to separate the messages into clusters for assigning and coding them by which response should be used.

The Solution: The Topic Code and Exposing the XML Layer

Any solution to the problem needed be simple and easy to adopt, decrease barriers to citizen sending messages themselves or through an intermediary advocacy group and allowed congressional offices to better handle receiving and sending messages. The House Democratic Leadership set out to solve the problem. Majority Leader Steny Hoyer’s office set up a test of this solution to help congressional offices.

The decision was made to test a solution with actual congressional offices that opened the XML layer to outside groups (many thanks to the office of Rep. Sam Farr who endured the most rounds of testing and giving feedback). Also, a Lockheed Martin’s division (formally Intelligent Solutions) had added a new XML field or tag to their system in the previous year. The new field was called topic and was set to accept URIs (also commonly known as web addresses/URL’s as well as lesser known URNs). The topic field (see example 2) would allow an individual sender or larger group to pick any URL that identified the topic of the message. Offices tested receiving test messages at first and then with the help of Care2 tested actual messages submitted through Care2’s petition system. All of the tests proved successful, even with real world data.

URLs are universal, unique addressable codes that are compatible with XML as well as being widely used on the Internet. Using them for the topic field allowed for several possibilities. The most important aspect was to allow outside groups to add a code to messages sent by various citizens that would identify all of the messages as being part of the same effort. Additionally, the intention was that the URL picked would be the URL/web address that the advocacy group had posted a web page or form that described the topic of the message.

By using the URL that the citizen had visited as part of their sending of a message, the receiving office could:

  1. immediately identify all incoming messages as being part of the same group with 100% accuracy;
  2. let the legislative correspondent immediately click on the URL to see the genesis of the messages for quick research (in the current CMS, see example 3);
  3. delete any campaign en masse if deemed fraudulent;
  4. tabulate messages almost instantly since they could be clustered almost automatically by topic code, whether or not the individual messages had been read;
  5. use their own topic codes for messages coming from their own web forms to allow for immediate data entry and tabulation;
  6. avoid haphazard alternative solutions that did not seamlessly fit into their current system;
  7. use the system for free;
  8. learn the system in minutes;
  9. be able to save hours of staff time weekly on assigning and handling incoming messages.

For the citizen, the use of the topic is completely optional, and does not create a two tier system for messages sent through advocacy groups and directly from the individual citizen to the congressional office. In addition, as standard URNs or URLs are adopted officially for legislative bills, those and other open standard URIs can be used to more accurately denote the topic of the legislation rather than solely for clustering purposes (note that although votes in the House do have a standard and archival naming solution by using the URL’s, few people write in about past votes). Because the new system is designed to be much more transparent and efficient, citizens can feel that their words will be noted in a timelier manner, accurate and responded to on average more quickly.

For advocacy groups this new system provides some enormous advantages. First, messages will be easier to send now that the XML layer is exposed. Additionally, the system makes it possible for hundreds, if not thousands, of messages to be processed almost instantly by the receiving congressional office so that the time between mobilizing supporters and receiving offices tabulating results can be in minutes rather than the current days and weeks. By using a URL that is part of the organization’s Internet domain for the topic code, the advocacy group is using a topic code controlled by the organization and does not need pre-approval or any form of coordination with any part of Congress. By using the specific URL of the web page used for the particular effort, the advocacy group is ensuring that the recipient congressional office will find what inspired the constituents to participate, give background information and indicate which group was able to rally a large number of supporters to their cause. Also, no one owns, has patented, controls or is paid for the use of the topic code.

Counter-intuitively, using the topic code can increase the chance that individual messages will be read by congressional offices. Currently, many offices just use keyword or phrases to attempt to cluster messages with varying amounts of accuracy without needing to read the messages that become clustered. In other cases, staffers skim the messages as quickly as possible to glean which response should be assigned. Only messages that do not fit into a cluster are likely to be given more attention. However, a topic code that uses a URL of a web page that asks citizens to include personal stories, will likely alert the researching staffer that the messages likely to include personally relevant information.

It is seems important to mention that groups can send messages with an XML tag/field that says that the sender does not require/desire a response. Various CMS system deal with that request differently. It is also important to understand that individual congressional offices are under no rule that requires that messages received are read, recorded, archived or responded to. For this reason the ability is generally not used, but can be.

Due to the testing overseen by the House Democratic Leadership, the topic code has also been tested with the less current Lockheed Martin CMS, and the InterAmerica CMS (the Monarch CMS system should have no problem with shortly adopting the topic code as well according to Monarch). Between the above systems, almost all House offices and most Senate offices can easily use the topic code system. For all congressional offices, there is no purchase necessary and the setting up the system can take either minutes or under a month at most for some. It is unknown how many can currently accept and use the topic code already, but everyone that uses the current Lockheed Martin CMS and has a public email address already accept the topic code.  And as the system can immediately start making assigning responses to incoming messages much more efficient and save significant staff time and resources, and as there a workshops held to explain how to turn on and use the system, adoption could be ubiquitous for offices seeking to increase and improve constituent communications.

Except for Care2 there are not yet any outside organizations or commercial firms known to use the XML format and the topic field. However, as many offices can already accept the XML format and almost others can without cost, outside groups stand to fall behind competing organizations in bringing timely support in the form of constituents expressing support. In that the system is simple and easy to implement advocacy groups should be able to quickly add or develop the means to send XML formatted messages with topic codes to accepting congressional offices.

Future Developments

When the Congress settles on standards for legislative metadata (e.g. how bills and other legislative documents should be represented on the Internet and more legislative data is published electronically using powerful and well annotated standards (usually in XML with permanent and understandable URLs), then the opportunity for enhanced Internet communication will be possible. Unfortunately, there is no universal and unique naming convention for most documents, organizations and other important legislative objects for the Internet and many well meaning organizations have adopted proprietary solutions that are inherently incomplete in scope or audience. If Congress announces smart standards that use the URI system and well documented and meaningful XML formatted documents, a renaissance of Internet applications and web services will be possible. It is also crucial that organizations, individuals and Members of Congress use the promulgated standards. 

Those standards, the use of the topic code and other Internet standards will help create an environment where organizations can publish online independently of each other, yet create what I have called “connected conversations.” It is important to realize that a healthy online political ecology is more likely to exist when individuals and disparate organizations can control their own ability to publish and everyone uses a common language which accurately names common documents and other objects.

In terms of new technology, the use of simpler systems will more likely create a creative and complex political ecosystem. The most significant development is called REST or RESTful architecture. The best explanation of REST can be read in the book, RESTful Web Services by Leonard Richardson and Sam Ruby  ( Essentially, web sites can be both human readable and machine readable. The methods are simple and based on the Internet and web standards as they are currently. Future solutions to help improve citizens’ ability to learn about legislation, improve communication with each other and elected representatives will likely come from adoption of RESTful web sites and web services.

Frequently Asked Questions about the Topic Code Feature

What is the cost to congressional offices?

All offices pay for CMS applications. There is no additional charge for the use or acceptance of the topic field in a message.


What is the cost to advocacy organizations or individuals?

Use of the topic field not restricted nor patented. There has never been any charge by any congressional organization for receiving constituent message nor will there be with or without the use of the topic field. Whether a commercial organization charges for services or software for forwarding messages to Congress that include the topic field as a premium is unknown. No commercial or non-profit organization paid for or contributed to the development of the topic field system with except as noted in the document.


Does an advocacy group need to get permission or be certified to send a message with the topic field?

There is no current certification for people or groups to send messages to Congress. It is questionable if any pre-approval, certification or other formal restrictions would be found constitutional. However, individual offices can decide to have email addresses and/or web forms which those offices can choose to deal with as they see fit. Currently, many offices have created barriers to receiving messages through the Internet. As long as, those barriers do not include payment or certification, barriers are within the rules of Congress.


Does exposing the XML format provide any risks to the office?

In that most offices currently accept XML formatted messages internally, those risks have already existed to some extent. However, in that some offices have accepted XML messages publicly for over a dozen years it is unclear what risks beyond the ones currently faced (bad data, unrelated correspondence, etc). Badly formatted messages have and will continue to not be automatically sent into the CMS systems.


Does using the topic field mean that offices will avoid reading messages?

The topic field is optional and the use of it does not preclude offices reading the full message from a citizen. As the current system allows offices to assign letters using inaccurate keyword and pattern tools, as well as skimming of messages, there will likely not be a change in how many messages get read. Staffing levels play a much more significant role in whether messages are read individually. However, the topic field is likely to promote reading messages for those campaigns that indicate that the messages will include helpful, new and/or personal details that offices might find useful to know.


Will offices save time accepting the topic field?

The answer is that dealing with incoming correspondence will be greatly assisted. As the volume of correspondence is likely to increase, especially during politically significant times, the topic field may save countless hours of assigning responses to incoming messages. Also, creating accurate and timely mail reports will be significantly improved.


Should advocacy organizations send in databases or other files with formatted data instead?

This stop gap measure has some serious incipient problems. First is that there is no official system for receiving email attachments (in fact, many offices have a policy of not opening attachments except in pre-approved circumstances). In addition, the ad hoc nature of this process currently favors groups that have special relationships with offices. Also, sending the messages in bulk preclude the ability of citizens to continue to send messages after the bulk file has been sent. In addition, as offices often pay for lists which are delivered as files as opposed to incoming correspondence, it will put a special onus for congressional offices to ensure that the file would not be classified as a gift.


Should advocacy organizations avoid other means of communications beside this system such as phone calls and paper materials?

Of course not.


What happens when advocacy groups forward messages that are deemed to be the work of bad or incompetent actors?

As always, it is up to a congressional office to have a good CMS and well trained staff that can ascertain whether incoming messages are bad. Most offices have access to systems that can tell if postal addresses are legitimate and registered voter lists to check names. However, there is no perfect system. In addition, using the topic field to cluster incoming messages will allow offices to delete messages based on the topic field in such cases.


Why not use CAPTCHA (logic puzzles or pictures) on web forms to keep messages that are not generated by actual citizens?

First there is damage made to representative government when barriers are put up. Having the noise of bad actors corrupt actual citizens’ ability to be heard is a serious problem as well. Unfortunately, the CAPTCHA system is best used for systems where money or other very sensitive information is being captured, and petitioning government should not use restrictive systems. Furthermore, groups using the XML format with the topic field will run the risk of ruining their efforts by allowing bad data to be sent to Congress. And with better trained staff and using current and future CMS capabilities, offices should be able to deal with great loads of incoming messages and sort out bad ones and better deal with constituent messages.


Can congressional offices create their own topic field codes?

Yes, they can pick URLs from their own site. This may help them create easy to fill out web forms that allow their constituents to self identify the topic of their message. The topic field code need not be exposed or seen by the public to work (for example, the web form might just state pick the option to support or oppose a specific pending bill). The office could then use the topic field codes to cluster the responses to help save time.


Could advocacy groups use non-existent URLs?

Although it would not make any sense to use URLs that are not in a domain that the advocacy group controls, there may be reasons to use a URL that does not actually represent a real web page. For example, the advocacy group has a password protected area or their current web site uses bizarre URLs. In those cases, the organization might opt to create a URI (URLs are a subset of URIs) that was easy to understand, such as I would recommend having a better architected web site that allowed for better URLs. Also, the advantage of having a URL that the congressional office can quickly find may be viewed as less helpful.


Isn’t using the keyword and pattern systems just as good as using topic code?

As long as certain advocacy groups send in messages without topic codes, then offices may find those features invaluable. However, the topic field code uses a well established system for the Internet, which is universal, unique and usually leads to a web page with additional information. Offices can use the topic code to assign affiliation and issue codes to their CMS records.


Why not use the ISSUE field (also known as SUBJECT) field for outside groups?

The IQ system (the current Lockheed Martin CMS) generally needs to only allow preset codes for these fields. The topic field is not a field that needs pre-populated values to be received properly as do the other fields. Also without an accepted naming convention there is no way to easily set the code without collaboration with the advocacy group and the system would likely not be universal.



Example 1: An example of an XML message that would be in an email sent to the CMS








<ADDR1>100 West Alisal Street</ADDR1>







<MSG>This is a test of the topic system. Please contact Daniel Bennett at





Example 2: An example of the above XML message with the topic code added (emphasis added for clarity)








<ADDR1>100 West Alisal Street</ADDR1>








<MSG>This is a test of the topic system. Please contact Daniel Bennett at Thanks.




Example 3: A screenshot of a received message using Topic code with clickable link in the Lockheed Martin IQ version 3 CMS (thanks to Rep. Sam Farr’s office for example)





This document created by Daniel Bennett is available for distribution, copying, modification by any person or organization with or without attribution and without consent. This work is hereby released into the Public Domain. To view a copy of the public domain dedication, visit or send a letter to Creative Commons.
Document Actions
What's News