Customizing the Thread Format

Response Manager appends a thread number to all incoming and outgoing messages. The format of this thread number is (Thread: number). If you prefer, you can replace the Thread: portion with your own text. The ability to change the thread format is particularly useful for sites that exchange email messages with other Response Manager servers. If two Response Manager servers use the same thread format, messages originating from one server will be associated with the same-numbered, but otherwise unrelated, thread on the other server. Since Response Manager considers the entire text of the thread identifier when associating messages with threads, customizing the thread format to make it unique will avoid the problem of other servers’ thread numbers interfering with yours, and vice versa.

Changing the thread prefix will cause new messages sent or received in any existing threads to get new thread numbers. For this reason, it is recommended that if you wish to use a custom thread format, you set it immediately upon installation.

The thread format is stored in the Response Manager database and requires execution of SQL to change. We therefore recommend that you contact emailtopia Support for assistance in changing it. However, if you have SQL expertise, you may set the thread format yourself.

To change Response Manager’s thread format:

  1. Stop the emailtopia Response Manager service.

  2. Connect to the Response Manager database (the default name is rmdb) using a SQL query program such as SQL Query Analyzer.

  3. Execute the following SQL statement, replacing Thread: with the text you’d like to use instead of the default:

     update rm_config set thread_prefix='Thread:'
    

    For example, if you’d like your thread format to look like (AcmeCorpID-1234) use this SQL statement:

     update rm_config set thread_prefix='AcmeCorpID-'
    

    Do not include parentheses. The final thread string that appears in message subjects is composed of these pieces:

    ( + threadPrefix + threadNumber + )

    The thread prefix may be from 3 to 16 characters in length and contain numbers, letters, dashes (-), colons (:), and spaces (however, spaces are not allowed at the beginning or end of the prefix).

Using the Email History Feature

Response Manager allows you to view all messages received from or sent to a particular email address. This functionality can be very useful for integration with CRM applications such as SalesForce. This feature is not enabled by default.

The Email History function does not respect Response Manager user privileges. All messages matching the entered email address can be viewed by anyone who uses it.

To enable the Email History feature:

  1. Stop the emailtopia Response Manager service.

  2. Open the Response Manager\Server\Logic\mailserver.xml file in a text editor such as Notepad.

  3. Find the following text: email_history_active="no" and change no to yes.

  4. Save the file.

  5. Start the emailtopia Response Manager service.

URL Format

To view the all email messages sent to or received from a specified address, open a Web browser and enter a URL in the following format:

http://rmaddress:rmport/emailHistory?email=email&mailbox=mailbox&include=include

where:

Examples

These examples assume that the Response Manager server is running on rm.example.com:8888.

List all messages to or from joe@xyz.com in any group mailbox:

http://rm.example.com:8888/emailHistory?email=joe@xyz.com

List all sales group mailbox messages to or from joe@xyz.com:

http://rm.example.com:8888/emailHistory?email=joe@xyz.com&mailbox=sales

List all sales and asset group mailbox messages to or from joe@xyz.com:

http://rm.example.com:8888/emailHistory?email=joe@xyz.com&mailbox=sales,asset

List all current messages to or from joe@xyz.com in any group mailbox:

http://rm.example.com:8888/emailHistory?email=joe@xyz.com&include=current

REST Call

A REST call with similar functionality is available for lower-level, more flexible integration with your systems. It returns data in JSON format.

URL Format

The email history REST call is made using the HTTP GET method, using the following URL format:

http://rmaddress:rmport/api/v1/emailHistory?emailAddress=emailAddress&groupMailbox=groupMailbox&include=include&sort=sort

Basic authentication, using any valid Response Manager account, is required.

The parameters are as follows (note that they are slightly different than the email history web page URL parameters):

Results Format

Results are returned in JSON format, like so:

	{
	  "emailHistory": [
		 {
			"fromAddress": "\"GM B\" <gmb@rm.example.com>",
			"groupMailbox": {
			  "id": 4,
			  "name": "gmb"
			},
			"htmlDetailUrl": "/messagesuite/MsServlet?message_id=19360",
			"messageDate": "2016-01-13T15:50:28Z",
			"messageID": 19360,
			"messageType": "outgoing",
			"subject": "Re: lorem ipsum (Thread:14153)",
			"threadID": 14153,
			"toAddress": "<customer@foobar.com>"
		 }, …
		]
	}

The following table describes each emailHistory item attribute:

Name Contains
fromAddress The From header value of the message.
groupMailbox An object containing the id and name of the group mailbox the message resides in.
htmlDetailUrl The web page URL for viewing the message content. The URL is relative; use the same protocol/server/port as used for the REST call in order to construct a complete URL. Authentication is required and whether the message will be viewable will be determined by the privileges of the authenticated user.
messageDate The date of the message, in ISO 8601 format. For messages with a messageType of incoming, this is the received date; for outgoing messages, this is the sent date.
messageID Response Manager’s internal ID for the message.
messageType incoming or outgoing.
subject The message subject.
threadID The thread ID of the message.
toAddress The To header value of the message.

Archive Database Connection Setup

To perform archive database searches with the email history web page URL or REST call, you must have an Archive database connection defined. Do this using the following steps:

  1. Using a text editor such as Notepad, open the database.xml file, located in the server’s Server\Logic directory. (If you are running Windows 2008 or later, use the Run As Administrator option to launch the text editor; if you don’t you will be unable to save changes.)

  2. Copy the existing connection element (for the MailServer connection) and paste it between that connection and the </connections

         ...
         />
     <connection
         name="Archive"
    
         driver="com.microsoft.sqlserver.jdbc.SQLServerDriver"
         url="jdbc:sqlserver://10.0.1.11:49279;databaseName=rmarchivedb"
    
         maxconnections="10"
    
         maxstatements="1"
         maxexecutions="500"
         maxidleseconds="30"
    
         debug="false"
         diagnostic="true"
    
         report_timing="30"
    
         username="rm"
         password="wjaF17FrA7"
         />
     </connections>
     ...
    
  3. In the pasted connection, change the value of the name attribute to Archive.

  4. In the url attribute, change the databaseName value to the name of the archive database. If your archive database is not on the same SQL server as the production Response Manager database, you will also need to edit the server, instance, and/or port information.

  5. If the archive database requires a different login than the production database, change the values of the username and password attributes. Use the PasswordEncryptor.exe application, located in \Server\bin\Utilities, to encrypt the database password.

  6. Save the file.

  7. Restart the emailtopia Response Manager service.

Configuring Duplicate Email Message Detection

The duplicate email message detection feature of Response Manager prevents your server from becoming bogged down with numerous identical messages generated by malfunctioning email sending software or mail loops. When this feature is activated, duplicate messages are discarded or forwarded to another address according to your settings.

Configuration

Duplicate detection is off by default. To enable it and configure its operation, use a text editor such as Notepad to edit the mailserver.xml file, which is located in the \Server\Logic subdirectory of the Response Manager installation folder. Follow these instructions to do so:

  1. Stop the emailtopia Response Manager service.

  2. Open the mailserver.xml file and add the following three attributes to the <instance> element:

     dupe_threshold_number="0"
     dupe_threshold_hours="0"
     dupe_forwarding_address=""
    

    For example, you may add the attributes after the existing web_services_active attribute:

    Duplicate detection configuration attributes in the mailserver.xml file
    Duplicate detection configuration attributes in the mailserver.xml file
  3. Specify the desired value for each setting by entering it between the quotes after its name.

    dupe_threshold_number
    The number of apparently-identical messages to allow into the system before discarding of messages begins. For example, if this value is set to 30 , the server will allow into the system 30 messages that appear to be the same according to the duplicate determination criteria (see Duplicate determination below). But when a thirty-first or subsequent message like the first thirty arrives, it is discarded.

    A value of 0 causes duplicate detection to be turned off.

    dupe_threshold_hours
    The number of hours to consider when counting messages and determining whether the dupe_threshold_number has been exceeded. For example, if set to 1 , only messages received within the last hour are counted.

    A value of 0 causes duplicate detection to be turned off.

    dupe_forwarding_address
    The email address to which duplicate messages are to be forwarded. E.g.: dupes@example.com. This value must not be an address on the Response Manager server (such as a group mailbox address) or any address that is forwarded to the Response Manager server (such as an Exchange server mailbox address that is set to forward mail to a Response Manager group mailbox.)

    If empty, messages are not forwarded, but simply discarded.

For example, if you want to have Response Manager discard a message when you’ve already received 30 or more that appear to be the same within the last hour, set the values as follows:

dupe_threshold_number="30"
dupe_threshold_hours="1"
dupe_forwarding_address=""
  1. Save the mailserver.xml file and exit your text editor.

  2. Start the emailtopia Response Manager service.

The Response Manager server will now detect and discard duplicates according to your settings.

Duplicate Determination

Response Manager uses the From address and Subject of messages in order to detect duplicates. If these values are exactly the same for two messages, the messages are considered to be the same. Messages that differ in either or both these values (even if only in capitalization) are considered to be different.

Logging

Messages that are discarded as duplicates are logged specially in Response Manager’s mail log (see Mail Log). In the third field of the entry for a message that is discarded, DUP is logged instead of OK. For example, the following log excerpt shows three messages received normally followed by two discarded as duplicates:

Sep 15, 2011 10:46:47 AM IN OK 250 example.emailtopia.com…
Sep 15, 2011 10:46:48 AM IN OK 250 example.emailtopia.com…
Sep 15, 2011 0:46:49 AM IN OK 250 example.emailtopia.com…
Sep 15, 2011 10:46:50 AM IN DUP 250 example.emailtopia.com…
Sep 15, 2011 10:46:51 AM IN DUP 250 example.emailtopia.com…

(If a message arrives via POP, the second field shows POP instead of IN.)

Configuring Active Directory/LDAP User Authentication

Organizations using Active Directory or other LDAP servers for user authentication can extend some of the benefits of this technology to Response Manager user accounts. While Response Manager accounts must still be created and maintained in Response Manager Admin, you may set up Response Manager so that it uses your LDAP server for authentication. When turned on, this feature is used when a user logs in to Response Manager either with a mail client or with Response Manager Admin. The passwords assigned to users in Response Manager Admin are ignored. Use of LDAP authentication is especially useful for organizations that have security policies requiring frequent password changes.

When a user’s password changes, it is still necessary to manually update the account password saved in the user’s mail program.

To turn on the LDAP authentication feature for your Response Manager server, follow these steps:

  1. Create your user accounts in Response Manager Admin. The username field for each user must match exactly that of the corresponding account in Active Directory. Normally, these will be the same as the user names entered for Windows logins.

  2. In a web browser, go to the /horton/auth/ page on your Response Manager’s web server. For example: http://rmserver.example.org:8888/horton/auth/.

    Generate Active Directory/LDAP Authorization File page
    Generate Active Directory/LDAP Authorization File page
  3. Complete the form according to these instructions:

    In this field… …do this
    Account suffix Enter the suffix that will be added to each username before being authenticated. (At some sites, a suffix may not be necessary. In that case, leave it empty.)
    Account prefix Enter the prefix that will be added to each username before being authenticated. (At some sites, a prefix may not be necessary. In that case, leave it empty.)
    Provider URL Enter the URL for your LDAP service.
  4. Click Get authorization.xml File. If you are given the option of saving or opening the file, choose to save it.

  5. Stop the emailtopia Response Manager and emailtopia Response Manager Reports services.

  6. Copy the saved authorization.xml file to both of these locations on your Response Manager server:

    • Server\Logic\
    • Reports\Logic\
  7. Restart the emailtopia Response Manager and emailtopia Response Manager Reports services.

  8. To confirm that your server is now using LDAP for authentication, open the service.txt file in the Response Manager\Server\logs directory. Near the end, you should see a line containing the text LDAP Authorization successfully initialized.

  9. As a final test, make sure you can successfully connect to Response Manager using Response Manager Admin or a mail client. Perform this test using any account other than administrator.

The built-in administrator account is treated specially: it is never authenticated using LDAP.

Changing the Maximum Allowed Size of Messages

Very large messages (e.g., messages with large and/or many attachments) can cause problems in any mail system. Not only do they take up disk space for storage, but they consume network bandwidth, memory, and processing power. For these reasons, Response Manager limits messages to 20MB. If a mail client or server tries to send a larger message, it is rejected.

This limit can be changed by editing the value of the ms_config.max_message_size_mb column in the Response Manager database. For example, to change the limit to 15MB, execute this SQL statement against the database:

update ms_config set max_message_size_mb = 15

The change will take effect the next time the emailtopia Response Manager service is restarted.

Removing Received Headers from Outgoing Messages

Normally, as a message passes from client to server to server via SMTP, a Received header is added to the message at every step to show the route the message traveled. This tracing information, which is required by the SMTP standard, is useful for troubleshooting message routing problems.

An outgoing message sent by a user through Response Manager would therefore normally have a Received header similar to the following:

Received: FROM steve.company.local ([10.0.1.27]) BY responsemanager.company.local 
  ESMTP; Thu, 11 Apr 2013 12:28:10 -0400

Since this header contains internal machine names and IP addresses, some Response Manager customers prefer not to have this information included in outgoing messages. The hide_received setting lets you specify that this information should be removed from each message leaving Response Manager.

Once a message leaves Response Manager, Received headers will still be added by servers that receive it (for example, by your Exchange server, if that’s where outgoing mail is forwarded).

To have Response Manager remove all Received headers from outgoing messages:

  1. Stop the emailtopia Response Manager service.

  2. Open the Response Manager\Server\Logic\mailserver.xml file in a text editor such as Notepad.

  3. Find the following text: hide_received="no" and change no to yes. If there is no hide_received attribute, add it yourself at the end of the <instance> element. E.g.:

     telnet_port="23" web_services_active="yes" hide_received="yes"></instance>
    
  4. Save the file.

  5. Start the emailtopia Response Manager service.

Specifying the Addresses to Which Errors Are Sent

When certain important errors occur, Response Manager will send an email to an address list you specify. For example, an error message will be sent if there are unrecoverable problems picking up a message from your POP server.

To set the email address(es) that Response Manager should send errors to:

  1. Stop the emailtopia Response Manager service.

  2. Open the Response Manager\Server\Logic\mailserver.xml file in a text editor such as Notepad.

  3. Find the following text: email_errors_to and change the value in quotes after it to include the desired email addresses. Separate multiple addresses with semicolons (;). If there is no email_errors_to attribute, add it yourself at the end of the <instance> element. E.g.:

     telnet_port="23" web_services_active="yes" email_errors_to="harold@example.com; mary@example.com"></instance>
    
  4. Save the file.

  5. Start the emailtopia Response Manager service.

→ Next: Moving a Group Mailbox

This documentation looks best when viewed with Internet Explorer 9 or greater or the current version of Google Chrome.