This article explains how to use the inbuilt SMTP adapter in BizTalk 2006r2 within an orchestration to send SMTP email via a dynamic send port. Step by step you will be shown how to create a new SMTP host and Send adapter, build the BizTalk solution containing the orchestration and create the send pipeline that will send your SMTP email to the recipient of your choice.

Sending SMTP email from BizTalk orchestration using a dynamic send port

This article explains how to use the inbuilt SMTP adapter in BizTalk 2006r2 within an orchestration to send SMTP email via a dynamic send port. Step by step you will be shown how to create a new SMTP host and Send adapter, build the BizTalk solution containing the orchestration and create the send pipeline that will send your SMTP email to the recipient of your choice. By building and deploying this example BizTalk application you will be able to configure and send email messages simply by dropping a text file into a directory. The contents of the text file will be sent as the email body.

This article assumes that you have at least a working knowledge of BizTalk Server 2006 r2 and that you have access to a system where you have privileges to create, deploy and configure BizTalk applications.

Create SMTP Host in BizTalk Admin Console

Open up the BizTalk Admin console and in the left pane expand Platform settings->Hosts.

Right click in the right pane and select New->Host. With General selected in the left pane configure the values as in the following screenshot.



Click OK to save the new host.

Create a Host Instance
In the Admin Console expand Platform settings->Host instances. Right click in the right hand pane and select New->Host instance.



In the dialog box that appears configure the values as follows:

The Host name dropdown should be changed to display the name of the new host you just created.

The Server dropdown should be changed to display the name of your BizTalk server.

To configure the Login property click the Configure button. In the dialog box that appears you should supply the username and password for a suitable user with the relevant permissions who is also a member of the BizTalk Server Windows Group. This user also accesses the BizTalk Management DB so it needs SQL permissions also.

Note: The creation of this user is beyond the scope of this article.



Once you have created and configured a new Host instance you need to create a new Send adapter to use the new host.

Creating the SMTP Send Adapter

In the BizTalk admin Console expand Platform settings->Adapters->SMTP.

Right click in the right hand pane and select New->Send handler.



In the dialog box change the Host name dropdown to display the name of the new host you just created. Click OK to save the changes.

That’s all you need to do to create the SMTP adapter host and host instance. Now we can get on creating the application itself.


Now we open Visual Studio and creating an empty BizTalk project.

I prefer to group similar artifacts together in separate folders so I add two new folders to the project. One called Orchestrations and one called Pipelines. This is simply the way I like to work but if you don’t, it will not affect the solution.

Create the Send Pipeline

Right click the Pipelines folder (or the Project if you didn’t create it) and select Add->New item. In the dialog box select Pipeline files in the left pane and Send Pipeline in the right pane. A blank pipeline should appear in Visual studio. From the BizTalk toolbox pane click and drag the MIME\SMIME encoder onto the pipeline and drop it under the Encode section.



Right click your newly dropped MIME\SMIME encoder and select Properties. Configure the values to be as they are in the following screenshot:



The greyed out values are auto generated so ignore those. That’s all that you have to do for the pipeline so save the file and close it.


Create the Orchestration

Next we add an orchestration containing the following artifacts: One send and one receive port, a Receive shape a Construct message shape containing a Message assignment shape, an expression shape and a send shape. We will also create two message types. One for the input message and one for the multipart output message.

By following these steps you should end up with an orchestration looking something like this.



Create the message types

Create the Multi-part message
In the Orchestration view window right click the Multi-part Message Types folder and select New Multi-part Message Type. A new Multi-part message will be created with the default name of MultipartType_1. Expand this to reveal the MessagePart_1 element. Right click the MessagePart_1 element and select Properties.

In the Type section of the Properties window there will be a red exclamation mark within a circle. This means you have yet to define what type of the message. We need this value to be System.Xml.XmlDocument. Click the red exclamation mark and from the dropdown options select .Net classes -> Select from referenced assembly.



In the dialog box that appears select System.Xml in the left hand window. In the right hand window select XmlDocument.



Click OK to select XmlDocument and close the dialog.

You have just created the multi part message, which is the one that will be emailed from the orchestration. You now have to create the input message. This is the one the orchestration will expect and will use to create the output message.

To create the input message open the Orchestration View window and right click on the Messages folder and select the New Message option. A new message with the default name of Message_1 will appear with another red exclamation mark icon. Select the new message and adjust its properties until they are as in the screenshot below.



Now you have your two message types you can go on to add the rest of the required artifacts to complete the orchestration.

Add the Receive Port

Right click on the left hand Port surface and select the New configured port… option.
Port Properties screen
Click Next on the splash screen and then on the Port properties screen enter a name in the Name field and click the Next button.



Select a Port Type screen
Select Create a new Port Type and enter a suitable name



Ensure that One-Way is selected in Communication Pattern and that Internal – limited to this project option is selected for Access Restrictions.

Port Binding screen
Change the Port direction… drop down so that it specifies I’ll always be receiving messages on this port. Select Specify Now in the Port binding drop down. In the URI text box, type in the location where you will be dropping the input file and make sure the Transport dropdown shows FILE. (Note: The file drop location does not have to exist at this stage. You can create it after you finish building the BizTalk solution but before you deploy the application). In the Receive pipeline dropdown, select the DefaultPipelines.PassThruReceive option. Click Next.



The final screen allows you to review the settings of the port you have just created. Click Finish to exit the wizard.

Add the Send Port

Right click on the right hand Port surface and select the New configured port… option.
Use the wizard screens to configure the send port with the values shown in the screenshot below.



On the Select a Port Type screen create a new port type and call it Snd_Smtp_PortType_1.

On the Port Binding screen make sure you select the I’ll always be sending messages on this port option. In the Port binding dropdown select Dynamic.



In the Send pipeline dropdown select the SMTP.Pipelines.SendSMTPPipeline you created earlier.

Add the Receive shape to the Orchestration

From the toolbox window, drag a Receive shape onto the orchestration. Configure the Receive shape properties so that they are as in this screenshot.



Add the Construct Message and Message Assignment Shapes

Drag a Construct message shape onto the orchestration and position it below the Send shape.
Configure the Construct message shape properties as shown below.



Next, drag a Message assignment shape onto the orchestration and place it inside the Message construction shape. Double click the Message assignment shape and type the following code into the expression editor dialog box.



Where the line stating MultipartMsg(SMTP.SMTPHost) is you need to supply a valid SMTP server name instead of <your_smtp_server_address_here>.

Note: Most ISP’s who provide a web based email service will usually be able to be used here. For example if you have Outlook configured to synch with a web mail service you can look in the Tools->Email accounts menu option and then select View or change existing email accounts to find out the SMTP server name.

Click OK to commit the changes and close the dialog box.

Add the Expression Shape

Drag an Expression shape from the toolbox and place it beneath the Message construction shape. Double click the Expression shape and add the following code to the expression editor.

Snd_SMTP_Port_1(Microsoft.XLANGs.BaseTypes.Address)="mailto:xxx.yyy@zzz.com";

The underlined text is the name you gave to your Send port (it wont appear underlined in the expression editor - this is for clarity). The value within the parenthesis tells BizTalk that the Address property of the underlying XLANGs.BaseTypes is set to a mailto: (Don’t forget the Send port is configured to use your pipeline which in turn uses the MIME\SMIME encoder. BizTalk wires all this up under the hood).

The value of the mailto: needs to be set to an email address of your choice and replace the xxx.yyy@zzz.com placeholder.

We’re nearly there now. Just a few more steps…

Add the Send Shape

Drag a Send shape from the toolbox and put it under the Expression shape, at the very bottom of the orchestration. Configure the properties to reflect those in the screenshot below.



Once you have done this all that remains to do for the orchestration is to drag the green connector from the Receive port to the correlating connector on the Receive shape and to do the same for the Send shape and Send port.

If the connectors do not snap into place then there is most likely a difference between the message types of the port and the message types of the shape. Double check that the Receive port message is of type XmlDocument and that the Receive shapes InMsg is of the same type. The Send shape message should be a Multipart message of type SMTP.MultipartType_1 and the Send port should be expecting this.

Build and Deploy

Before building the solution a few properties have to be configured on the project itself. Right click the project in Solution explorer and select Properties.

In the dialog box that appears select Common properties->Assembly in the left hand window.



As the BizTalk assembly will be deployed to the GAC it needs to be strongly named. In the right hand pane, click next to the Assembly key file property and browse to a .snk file on your machine.

(For help on creating a ‘SNK file go here: http://msdn.microsoft.com/en-us/library/6f05ezxy%28VS.71%29.aspx)

Next select Configuration properties->Deployment in the left pane.



In the right hand pane enter the name of your BizTalk Server in the BizTalk Group->Server text box. Also in the BizTalk Group->Application Name textbox enter a name for your project. This value will appear in the BizTalk Admin console->Applications list with all your BizTalk artifacts present beneath it.

Now build and deploy the solution.

Configure BizTalk Application in BizTalk Server Admin Console

Once your application is deployed it needs to be configured to use the host instance you created earlier. To do this right click on your application and select Configure.



In the dialog box that appears select your orchestration in the left pane and then select your host from the dropdown in the right pane.



Now click OK to save and close the dialog and then right click the application again.

Configure Receive port

Select the Receive locations folder in your app and then double click the entry in the right hand pane. In the dialog box that appears configure the properties as follows:



The Type dropdown should display FILE.
The URI should read C:\Projects\BizTalk\SMTPAdapter\In (The directory you specified when you created the Receive port, on the Port binding screen). To configure this value click the Configure button. A new screen similar to the one below should appear.



In the Receive folder text box put in the directory you specified when you created the Receive port, on the Port binding screen (You should create this directory now if you haven’t already).

In the File mask text box enter .txt. This tells BizTalk that all .txt files should be consumed. Click OK to accept the changes.

The Receive pipeline dropdown should have the PassThruReceive pipeline selected. Click OK to accept the changes.

Start the application by right clicking it in the left pane of the BizTalk Admin Console and selecting Start. Your application is now configured and ready to accept incoming files and send them out as the body to an email. PHEW!

Drop the text file

Create a simple text file that contains something like the following.

Hello. This is the SMTP email body.

Save this somewhere on your hard drive. Copy the file and paste it into the directory you specified when you created the Receive port, on the Port binding screen (C:\Projects\BizTalk\SMTPAdapter\In).

If you watch the drop directory the file should disappear quite quickly. This means BizTalk has consumed it.

Now open up your email application. You should receive a new email from BizTalkSMTP@sample.com with the body saying Hello. This is the SMTP email body.



This is a straightforward and simple demonstration of how to create the necessary BizTalk artifacts (including a new SMTP host and Send adapter, building the BizTalk solution containing the orchestration and create the send pipeline) that will allow you to send SMTP email from within an Orchestration using a dynamic send port.

This demo uses out-of-the-box components without any custom coding. I hope it demonstrates how simple it is to get started but also the potential of what could be achieved. I may in future submit another article along similar lines which will show how to dynamically configure recipients, subject text and body text based upon values contained within the incoming message and context. In the meantime, Enjoy.

Didn't Find The Answer You Were Looking For?