Please take a moment to read, to help share the message and support the initiative to tell our leaders to focus on addressing the global world problems, instead of complaining about the effects of their lack of leadership. Be a leader yourself, and share this with as many people as possible. #demandglobalchange //

Please consider donating:

6,695 views | This page as PDF

Exchange 2007/2010 : Renaming attachments ‘on the fly’ – custom transport agent

It may sound a bit extraordinary, but I needed to have the ability to change attachment filenames while they were being processed by the transport service on Exchange. I can’t really tell you why I needed this functionality, but I guess there could be many reasons to do so. (e.g. zip files should be renamed to .zip.renamed  so they need to be saved to disk first, renamed and then opened, and so on).  Anyways, I could not find a way to do this with the Exchange built-in features, so I had to write my own custom transport agent to do this.

The agent is written in C#, uses .Net Framework 3.5, uses the native MS Exchange API’s and works fine with Exchange 2007 (I’ve only tested SP1) and 2010 (beta 1). The dll has been compiled for x64 (64bit) systems only.

Putting the files in place

You can download the dll file from the link below. (As usual, you need to be logged in to download the file)

Please log in to download pveAttachmentRenameTptAgent (8.6 KiB)

This transport agent needs to be installed on all HUB transport servers in the organization, so the following procedure needs to be executed on all HUB transport servers :

1. Create folder structure

Create a folder called “pveattachrename” on drive C: (yes, it needs to be drive C:, and yes the folder needs to have this name)

In this ‘”pveattachrename” folder, create the following subfolders :

  • bin
  • config
  • rules
  • log
  • temp


(The 2 last folders : ‘log’ and ‘temp’ are the only folders that could grow in size (well, in fact, the log folder could grow, the temp folder is used to temporarily save attachments, but all temp files should get cleaned after processing an email). You will be able to move these 2 folders to another location. I’ll explain you how to do this later on).

Extract the downloaded dll file in the bin folder.

2. Set security on folder structure

The Exchange transport agent will run with “Network Service” permissions and needs to be able to read from the bin/config/rules folders, and write into the pveattachrename, the log and the temp folders. The easiest way to set the permissions is by allowing Network Service to read and write in the entire “pveattachrename” folder (and subfolders of course)


Transport agent configuration

1. Set application configuration parameters

In the config folder, create a file called config.cfg

This file can contain 3 configuration entries :

  • verbose=true  ( or  verbose=false)
  • workingfolder=
  • logfolder=

The “workingfolder” and “logfolder” entries are optional. If you don’t specifiy anything, the logfiles will be written to c:\pveattachrename\log and the temp folder will be c:\pveattachrename\temp.  If you decide to move the log and/or temp folders, make sure to grant the “Network Service” account read/write permissions to these folders. If you do specify a workingfolder or logfolder entry, don’t set a slash at the end of the path.

If you set verbose to true, you will be able to see – in detail – what happens when the transport agent functions are called.  This is a good way to troubleshoot issues, but the logfiles can grow quite large.  The log files will rotate every week, and log files older than 6 months should get removed automatically.  If you set verbose to false, only application errors will be written into the log files.

(Note : keep everything in lowercase, and don’t use spaces before and after the = symbol)

Example :


2. Create rules

In the rules folder, you can create as many rule files as you want.  A rule file is a file that has extension .rule, and contains the following entries :

  • extension=
  • renameaction=
  • from=

(The ‘from’ parameter is optional. If you don’t want to use it, just leave it out of the file)

Extension : here you can specify the attachment extension you want to apply the rename action to. You can only specify one attachment filename extension.  I recommend to include the . (dot) in the extension. So suppose you want to rename zip files, you need to specify

Renameaction : With this parameter, you can specify how the renamed attachment should look like. There are a couple of variable that can be used :

%filename% : will be replaced the original filename, without extension

%random% : will be replaced by a 8 character random string

%timestamp% : will be replaced by a date- & timestring that looks like this :   YYYYMMDD_HHMMSS

%date% : will be replaced by a datestring that looks like this : YYYYMMDD

%time% : will be replaced by a timestring that looks like this : HHMMSS

So suppose you want to rename zip files to, rename the filename and add some random characters to the filename, you need to set the renameaction parameter to :

Note : If the new filename becomes longer than 150 characters, only the first 140 characters will be used, and a new random string will be added (to make it unique again). So if you really want to have the original filename at the beginning of the filename, make sure to put %filename% at the beginning of the renameaction

From : You can specify one keyword (a domain name or email address). Only emails originating from this domain name or email address will be processed by the rule. If you have multiple email addresses or domain names, you’ll have to create multiple rule files.  (I may change this in the future, but this is how it works today). If you don’t want to filter on “From” email address/domain name, then don’t set the “from” keyword.

Save the file. I usually give the .rule file a filename that reflects the attachment extension inside the .rule file, but if you want to name them 01.rule, 02.rule, or something else…. feel free.


(By the way, make sure to verify that the .rule file is not saved as .rule.txt (and ‘hide extension for known filetypes’ is turned on). Everything may look ok, but the rules would not be used if they don’t have the .rule extension.

Every time an email is processed by the agent, a new Header is stamped onto the message. This will ensure that an email that is sent across multiple Transport servers will not get processed twice.  This header is called X-PVEAttachRename and contains a GUID-alike string.  If you have verbose logging enabled, you can use this GUID string to look up what happened to the email in the log file by searching for this string.

Installing & enabling the agent

Open MS Exchange Management Shell (Powershell) and run the following cmdlet : (pay attention, case sensitive !)

   -name "PVE Attachment Rename"
   -TransportAgentFactory "pveAttachRenameTptAgent.PVEAttachRenameTptAgentFactory"
   -AssemblyPath C:\pveattachrename\bin\pveAttachRenameTptAgent.dll

(put everything on one line !)

The output should look like this :


Close Powershell (This is required to make the agent work). Open Powershell again and restart the Transport service :

Restart-Service MSExchangeTransport

When the service has restarted, enable the Transport Agent, and restart the MS Exchange Transport Service again :

Enable-TransportAgent -id "PVE Attachment Rename"
Restart-Service MSExchangeTransport


The agent is now active.


Please use the forum at to post your support questions, file bugs or just provide some feedback about the agent.

Thanks for dropping by (again).

2009 – 2010, Corelan Team (corelanc0d3r). All rights reserved.

Related Posts:

5 Responses to Exchange 2007/2010 : Renaming attachments ‘on the fly’ – custom transport agent

  • agodin says:

    Fantastic – did exactly what is was meant to do with no fuss. We needed a quick and simple way to rename some reports so they could be automated and this did the trick.


  • Exchadmin says:

    Thank you so much, this is a life saver and it does work with Exch2007 SP2. We are using a voicemail system that forwards messages to e-mail whereas each voicemail attachement has the same name – message.mp3. When you open the voicemail on Blackberry you can “Download and Play” which works great only the first time, next time voicemail you listen to says: “file already exist, rename?”. Users are foced to come up with random names just to download their voicemails! Your workaround works great, now all MP3 voicemail files have unique name with timestamp and no more Blackberry headaches!!! Thank you!

  • JNandhi says:

    Hi Peter,

    This looks fantastic! What I need to do is convert any attachments on the fly which are being delivered to a particular inbox. We need to convert all documents (PDF, DOC, DOCX) into RTF. Could you provide me with some insight into how to achieve this using your method above?

    I have previously used a batch file and a variety of software to run the convert the attachments and populate a folder on our network. unfortunately the requirements have changed now and they need the orginal email in Outlook with an RTF attached to it.

    Kind Regards,

Corelan Live training

Since 2011, Corelan GCV has been teaching live win32 exploit dev classes at various security cons and private companies & organizations.

You can read more about the training and schedules here

Demand Global Change

The world needs your help !

Please take a few moments to read the "Demand Global Change Call For Action" document at
Read the full document at and share the message with as many people as possible.

Like the Facebook page, and SHARE it with everyone you know.


Want to support the Corelan Team community ? Click here to go to our donations page.

Want to donate BTC to Corelan Team?

Your donation will help funding server hosting.

Protected by Copyscape Web Plagiarism Tool

Corelan Team Merchandise

You can support Corelan Team by donating or purchasing items from the official Corelan Team merchandising store.

Corelan on IRC

You can chat with us and our friends on #corelan (freenode IRC)