39410: How to set up ad hoc email addressing in MassTransit

use Google Translate

Applies to: 

Last update: 07-04-2016


Ad hoc file transfer is available in the Premier Edition of MassTransit 6.1.1 and later. It allows web clients to send files to users designated by email addresses that may or may not already have accounts in MassTransit. After logging in to the MassTransit Web (MTWeb) site, web client users are allowed to send files to any valid email address. When the web client clicks on the "Send" button, the files are sent to the MassTransit server. If the entered email address does not belong to an existing contact on the server, an account with that address is automatically created. All automatically created web contacts can be configured to expire or persist.

After MassTransit creates the account, an email action is triggered that sends a notification email to the recipient contact's email address. The email can contain an FTP or HTTP link allowing the contact to click the link and retrieve files from the MassTransit server. These links can either take the contact to the MTWeb or FTP login page with the contact's user name already populated. If the link contains a passkey, the contact is automatically logged in the MTWeb or FTP site without having to know their username and password. This article describes how to configure the ad hoc addressing feature as well as the security risks of the different types of email links if an email is intercepted by a third party. This article has instructions for MassTransit version 6.1.1 only. For versions 7.0 and later please refer to the Ad Hoc Delivery section of the MassTransit Server Configuration Guide.


Setting up the ad hoc addressing feature:

1. To set up ad hoc addressing, open the MassTransitEngine.cfg file located in the "MassTransit Server 6" installation directory. By default, this folder is placed on the system drive in:

~\Program Files\Group Logic\

On 64-bit versions of Windows, the default location of the MassTransit folder is on the system drive in:

~\Program Files (x86)\Group Logic\

Note: All lines beginning with "%%" in the MassTransitEngine.cfg file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see "%%" characters at the beginning of any of the settings you modify, delete them).

Under the AD-HOC ADDRESSING CONFIGURATION section in the MassTransitEngine.cfg file, find the "ADHOC_ADDRESSING_ENABLED" setting and set it to TRUE. This enables the feature globally for the MassTransit server. You will also need to enable ad hoc addressing for each web contact individually in the MassTransit Administrator. This is described in step 3 of this article.

You can create a profile account whose settings will propagate for every automatically created ad hoc account. To do that, enter an existing contact's name for the "ADHOC_AUTO_ACCOUNT_PROFILE" setting. When setting up this contact in the MassTransit Administrator, under the Mailbox tab you MUST choose the Default Mailbox option. Only settings found in the Contact Information Security tab are propagated to the new ad hoc contact.

If you have forwarding permissions established by MassTransit Master and Distribution lists, and you do not want to override them with the ad hoc addressing feature, set "ADHOC_OVERRIDE_MDL_PERMISSIONS_ENABLED" to FALSE. The default value for this flag is TRUE.

You now need to configure the passkey links that will allow the automatically created ad hoc contacts to log in and download the files.

Under the "HTTP and FTP email link configuration" section of the MassTransitEngine.cfg file, set the "HTTP_DOMAIN" and/or the "FTP_DOMAIN" settings to the domain name (or the IP address) of your MassTransit server.

To determine how long the passkey link will be valid, enter a value for the "PASSKEY_DEFAULT_TTL_HOURS" setting.

You can also determine the number of minutes the passkey link will be valid for after the first successful use. In order to do that, change the "PASSKEY_DISABLED_AFTER_LOGIN_MINUTES" setting.

After setting up the desired configuration settings, save and close the MassTransitEngine.cfg file.

Note: Any time you make a change to the MassTransitEngine.cfg file you must restart the MassTransit service for the changes to take effect.

2. The next step of setting up the ad hoc addressing feature is to add an email action in MassTransit that will notify the ad hoc contacts that there are files ready for them to download.

Open the MassTransit Administrator and click on the "Setup" button from the navigation bar. In the "Actions" tab of the "Setup" window, click on the "Add..." button and enter a name for the action in the "Name" field (e.g. "Files ready for download email").

Then, choose "After Files Are Added" from the "When" drop-down menu. Choose the "Configure Email Action" button from the "Tasks" area (the first button on the left side of the window).

Make the following changes in the "Configure Email Action" window:

a. Check the "Include Contact Email Address When Available" check box.

b. In the "From" field, enter a sender's name for the emails that will be sent to the ad hoc contacts.

c. Enter a subject for the notification e-mails in the "Subject" field.

d. Enter the domain name or the IP address of your SMTP server in the "SMTP server" field.

e. Enter text for the email notification in the "Message" field. You can set email links which can either take the contact to the MassTransit Web (MTWeb) or FTP login page with the contacts user name already populated. If the link also contains a passkey, the contact is automatically logged in the MTWeb or FTP site without having to know their username and password.

There are 4 tokens that can be used to send email to a contact that will contain an FTP or HTTP link, allowing the contact to click the link and retrieve files from the MassTransit server. The specific token names are:


There are also 6 other tokens that can be used:

$${{ContactName}} – name of the person receiving the email
$${{OriginatingContactName}} - displays the contact name of the originating user who sent the files
$${{OriginatingEmailAddress}} - displays the email address of the originating user
$${{XferNumFiles}} - displays the count of the file(s) for download
$${{XferFileList}} – lists each file by name and size
$${{PasskeyTTLHours}} - displays the validity time of the passkey link set in the MassTransitEngine.cfg file

Here is example text for the email action Message area:

You have $${{XferNumFiles}} file(s) that were sent to you from $${{OriginatingContactName}}, ($${{OriginatingEmailAddress}}).
If you already have a MassTransit login, click here to pick up your files.
If not, click the link below to log in and download your files.
This automatic login link is good for $${{PasskeyTTLHours}} hours.

Note: Instead of the $${{XferFileList}} token, you can check the Include File List check box below the message area to show the file list in the email.

3. The last step for configuring the ad hoc addressing feature is to set the desired individual users who will be able to send files to arbitrary email addresses. To do this, edit an existing web contact or add a new one from the "Contacts" window of the MassTransit Administrator.

Click on the "Security" tab of the "Contact Information" window. Then, check the "Allow Sending Files To Arbitrary Email Addresses" check box in the "Web Privileges" section.

Now, the ad hoc addressing feature is configured and the chosen web contacts should be able to send files to arbitrary email addresses. In addition, ad hoc contacts, if given permission to send files, can send files back to the originating contact using MassTransit.

Security Considerations

There are four types of email links: FTPLink, HTTPLink , FTPLink_passkey, and HTTPLink_passkey. The FTPLink and HTTPLink have different security considerations than FTPLink_passkey and HTTPLink_passkey.

When the FTPLink or HTTPLink types are used, web client users receive emails that contain a web browser link. This link directs the user to the MTWeb login page with their login name field filled in. If the email is intercepted, a third party will know the web client user’s login name but NOT their password.

When the FTPLink_passkey or HTTPLink_passkey types are used, emails sent to web client users contain a link with a temporary passkey code. When this link is clicked, the user is automatically logged into MTWeb under their account and are able to transfer files. If the email is intercepted, a third party can log into MTWeb under the user’s account until the passkey expires. The only way to fully prevent a third party from gaining access is by ensuring that emails with passkey codes are not intercepted. Another preventative measure to take is to reduce the amount of time a passkey lives by modifying the passkey lifetime parameters in the MassTransitEngine.cfg file.