How to Configure an SMTP Send Port

You can configure an SMTP send port either programmatically or by using the BizTalk Server Administration console.

How to Configure an SMTP Send Port Programmatically

The SMTP adapter stores its configuration information in the BizTalk Management database (also known as the Configuration database). Configuration information is stored in a custom XML property bag. During initialization of the SMTP adapter and during its run time, the server passes the configuration to the adapter as follows:

For the SMTP send handler, configuration information passes to the adapter by calling the Load method of the IPersistPropertyBag interface.
For the SMTP send adapters, configuration information passes to the adapter as a set of properties on a message context. The SMTP namespace groups these properties together.

The BizTalk Explorer object model exposes the ITransportInfo adapter configuration interface for send ports, which contains the TransportTypeData read/write property. This property accepts the SMTP send port configuration property bag as a name/value pair XML string. Note that to set this property in the BizTalk Explorer object model, it must first be set on the Address property of the ITransportInfo interface.

Setting the TransportTypeData property of the ITransportInfo interface is not required. If it is not set, the SMTP send port uses the default values for the SMTP send handler. SMTP send port-specific properties are defined in SMTP send adapter property schema bts_smtp_properties.xsd.

If you do not define properties that duplicate the send handler configuration properties, configuration properties for the handler are used. If you do not define required properties, default values are used. If you do not define default values, the SMTP send handler logs an error in the event log and moves the message to the backup adapter.

You can set these properties programmatically on a message context. You can set these properties in a BizTalk orchestration schedule or in a custom pipeline component. The following rules apply when using these properties:

If the property is set in an orchestration or in a custom pipeline component in a receive pipeline, then:
- If the message is sent to a static send port, the property value will be overwritten with the value configured for that send port.
- If the message is sent to a dynamic send port, the property value will not be overwritten.
If the property is set in a custom pipeline component in a send pipeline, then:
- The value will not be overwritten regardless of whether the message is sent to a static or dynamic send port.

The following table lists the configuration properties that you can set in the BizTalk Explorer object model for the SMTP send location.

Property name	Type	Description	Restrictions	Comments
SMTPHost	xs:string	SMTP server used to send messages.	Maximum length: 256	Default value: Empty. The default value indicates that the SMTP send port will use the configuration values for the handler.
From	xs:string	The e-mail address that the SMTP send port places on the SMTP From header.	Maximum length: 256	Default value: Empty. The default value indicates that the SMTP send port will use the configuration values for the handler.
CC	xs:string	E-mail address where a copy of the message will be sent.	Maximum length: 1024	Default value: Empty You can list several e-mail addresses.
Subject	xs:string	Subject header for the messages.	Minimum length: 0 Maximum length: 256	Default value: %MessageID%.
SMTPAuthenticate	xs:int	Type of authentication to use.	None	Valid values: 0 - No authentication 1- Basic authentication 2 - Process account (NTLM) The default value indicates that the SMTP send port will use the configuration values for the handler. To apply the default value, omit this property from the property bag when setting the TransportTypeData property.
UserName	xs:string	User name to use for authentication with the SMTP server.	Minimum length: 0 Maximum length: 256	Default value: Empty Requires a value if SMTPAuthenticate is equal to 1 (Basic authentication).
Password	xs:string	User password for authentication with the SMTP server.	Minimum length: 0 Maximum length: 256	Default value: Empty Requires a value if SMTPAuthenticate is equal to 1 (Basic authentication).
ReadReceipt	xs:boolean	Requests a read receipt for the messages from this send port.	None	Default value: False
DeliveryReceipt	xs:boolean	Requests a delivery receipt for the messages from this send port.	None	Default value: False
EmailBodyText	xs:string	Specify text to be used for the body of the e-mail being sent.	Maximum length: 64 kb	Default value: Empty
EmailBodyTextCharset	xs:string	Specify the character set to use for encoding the body of the e-mail being sent when the EmailBodyText option is used. The SMTP adapter will convert the EmailBodyText to the character set specified by EmailBodyTextCharset.	None	Default value: None. You must explicitly set the value, for example, to UTF-8. If you don't set a value, you may see the error shown at the end of this topic.
EmailBodyFile	xs:string	Specifies that the contents of a file will be used for the body of the e-mail being sent and the full path to the file. This path must be accessible to the host for the SMTP adapter at run time.	Maximum path length: 256 characters	Default value: Empty
EmailBodyFileCharset	xs:string	Specify the character set to use for encoding the body of the e-mail being sent if the EmailBodyFile property is set. The SMTP adapter will not perform any conversion on the file; the file must already be encoded in this character set. If the file has a Byte-Order-Mark (BOM), the SMTP adapter will remove it.	None	Default value: UTF-8 (65001)
Attachments	xs:string	Specifies that a file or files will be attached to the e-mail message and the full path to the file or files. The specified path or paths must be accessible to the host for the SMTP adapter at run time.	Maximum path length: 256 characters	Default value: Empty
MessagePartsAttachments	xs:int	Specify how BizTalk message parts are attached to the e-mail message	None	Valid values: 0 - No BizTalk message parts will be used as attachments. 1- The BizTalk message body part is sent as an e-mail attachment. In this case, the EmailBodyFile or EmailBodyText properties should be specified. If neither of these properties are specified, the BizTalk message body part is sent as the e-mail body instead of as an attachment. 2 - All parts are sent as attachments. However, if EmailBodyText or EmailBodyFile are not specified, then the BizTalk message body part is sent as the e-mail body and other parts are sent as attachments. Default value: 0
ReplyBy	xs:dateTime	Populates the Reply-By header field in the outgoing message with the specified value.	This property cannot be set on the send port property page. This property can be set from a pipeline or an orchestration.	Default value: Empty

The following code shows the format of the XML string to use to set these properties:

<CustomProps>
   <DeliveryReceipt vt="11">-1</DeliveryReceipt
   <SMTPHost vt="8">sfdsadf</SMTPHost>
   <Subject vt="8">Some subject</Subject>
   <From vt="8">username@domain.com</From>
   <SMTPAuthenticate vt="19">2</SMTPAuthenticate>
   <ReadReceipt vt="11">-1</ReadReceipt>
</CustomProps>

How to Configure an SMTP Send Port with the BizTalk Server Administration Console

You can set SMTP send port adapter variables in the BizTalk Server Administration Console. If properties are not set for the send port, the default send handler values set in the BizTalk Server Administration Console are used.

To configure an SMTP send port with the BizTalk Server Administration console, use the following procedure.

To configure variables for an SMTP send port

In the BizTalk Server Administration Console, create a new send port or double-click an existing send port to modify it. For more information, see How to Create a Send Port. Configure all of the send port options and specify SMTP for the Type option in the Transport section of the General tab.
On the General tab, in the Transport section, next to Type, click Configure.

In the SMTP Transport Properties dialog box, on the General tab, do the following:

Use this	To do this
To	Required. Specify the e-mail address for where to send messages. You can specify more than one address. Maximum length: 256 For more information about this property, see Restrictions on the SMTP To Property.
CC	Specify the e-mail address to send the carbon copy of the message. You can specify more than one address. Maximum length: 1024
Subject	Specify the subject header for the message. Minimum length: 0 Maximum length: 256
Notification	Specify the type of notification receipt. You can select one or both types of receipts. Notification receipt types are: Read Receipt. Confirmation e-mail message is sent when the message is read. Delivery Receipt. Confirmation e-mail message is sent when the message is delivered.

In the SMTP Transport Properties dialog box, on the Compose tab, do the following:

Use this	To do this
BizTalk message body part	Specify to use the BizTalk message body part for the body of the e-mail being sent.
Text	Specify text to be used for the body of the e-mail being sent. After the Text option is selected you can enter the text for the e-mail body into the text box. Maximum Length: 64Kb
Charset for the text	Specify the character set to use for encoding the body of the e-mail being sent. This option is only available if the Text option is selected. Default value: UTF-8 (65001)
File	Specify that the contents of a file will be used for the body of the e-mail being sent and specify the path to the file. After the File option is selected you can click the Ellipsis (…) button to browse to the file. Maximum path length: 256 characters Note It is a recommended best practice to specify a path on a file share that is accessible from all BizTalk servers in the BizTalk Server group to be used in production.
Charset of the file	Specify the character set encoding of the file being sent. Note The SMTP adapter does not apply the specified encoding to the file. This option is only for specifying how the file being sent is already encoded. This option is only available if the File option is selected. Default value: UTF-8 (65001)

In the SMTP Transport Properties dialog box, on the Attachments tab, do the following:

Use this	To do this
Remaining BizTalk message parts	Specify how BizTalk message parts are attached to the e-mail message. Options: Do not attach parts Attach only body part Attach all parts Default value: Do not attach parts.
Add	Specify a file or files to attach to the e-mail message. After clicking Add you can browse to select a file and add it to the list of files to be attached. Maximum path length: 256 characters Note It is a recommended best practice to specify a path on a file share that is accessible from all BizTalk servers in the BizTalk Server group to be used in production.
Remove	Removes the selected file from the list of files to be attached to the e-mail message.

Use this

To do this

Remaining BizTalk message parts

Specify how BizTalk message parts are attached to the e-mail message.

Options:

Do not attach parts
Attach only body part
Attach all parts

Default value: Do not attach parts.

Add

Specify a file or files to attach to the e-mail message. After clicking Add you can browse to select a file and add it to the list of files to be attached.

Maximum path length: 256 characters

Note

It is a recommended best practice to specify a path on a file share that is accessible from all BizTalk servers in the BizTalk Server group to be used in production.

Remove

Removes the selected file from the list of files to be attached to the e-mail message.

In the SMTP Transport Properties dialog box, on the Handler Override tab, do the following:

Use this	To do this
SMTP server name	Specify the name of the SMTP server to use when sending messages. Maximum length: 256 Note The URI for a send port or receive location cannot exceed 256 characters.
From (e-mail address)	Specify the e-mail address to place on the SMTP From header. Maximum length: 256
Authentication type	Specify the type of authentication to use with the SMTP server. Options: (Default) No authentication Basic authentication Process account (NTLM) The default value indicates that the SMTP send port will use the configuration values specified in the send handler.
User name	Specify the user name to use for authentication with the SMTP server. This property requires a value if Authentication type is Basic authentication. Minimum length: 0 Maximum length: 256
Password	Specify the password to use for authentication with the SMTP server. This property requires a value if Authentication type is Basic authentication. Minimum length: 0 Maximum length: 256

Click OK and OK again to save settings.

Other Resources

Configuring the SMTP Adapter