SAP PI/XI Mail Adapter FAQ's
Q: My mail messages seem to be read by the adapter however not being processed and there is no message is visible in the message monitor.
A: Please check the adapter monitor in Runtime Workbench. You can find your mail sender channel under the Mail adapter. The detail text of the channel will ideally explain the entire issue.
Sender with XIALL
Q: I’m getting few exceptions and my mail message is not getting processed.
A: Please have a look at the status of your channel in the adapter monitor. The status of the adapter monitor is typically updated for each polling cycle. You should verify the status post a new message is picked up by your channel. You will be able to figure out the if the problem is due to some communication problem with the mail server or to some mail format problem, from this status message.
Sender with XIPAYLOAD
Q: How can the user get the original sender email address and subject, etc?
A: The user would be required to use the mail package option for getting mail transport specific information in the XI payload. In SP14, there will be a new mechanism for transport related information for all the adapters.
Q: How to use the MailPackage in Sender?
A: When a mail message is fetched by the sender adapter, generally the content of the mail is kept in the XI payload. This refers to that the mail header information such as "From", "To", "Subject" has not been imported into the XI payload. When the MailPackage mode is utilized, the adapter constructs an XML document comprising of these header entries and the content.
The mail package is a deprecated feature which is supported for the existing scenarios and the asma attribtues should be utilized for the new scenarios
Sender Asynchronous Calls
Q: What all is offered by a sender channel configured as ExactlyOnce or ExactlyOnceInOrder?
A: The quality of service setting in the sender channel does not relate to the fact that this quality of service is automatically provided between the mail server and the XI system. The setting only permits the adapter to call some XI asynchronous receiver and the specified quality of service is provided between the receiving component and the adapter engine. If some error takes place
Other Sender related Questions
Q: My mail messages are not picked up.
A: The mail sender channel with IMAP4 gets only the unread messages from the specified mail box in the order in which they have been stored. Hence, please ensure that you have some unread messages in the top of the list (incase ordered by most recent on top). Post a polling cycle, the user can look at the status of this channel at the adapter's monitor. This would display any error in case the messages are not being processed correctly. Once the messages have been read however processed incorrectly, they will remain in the mail box but are not being read in the subsequent polling cycle. The user has to rectify the problem and delete these messages by using his mail client program or can even reset them as unread so that these can be resent.
The channel with POP3 gets all messages from the specified mail box in the same order they have been stored. Post a polling cycle, the user can verify the status of this channel at the monitor of the adapter. This should display any error in case the messages are not processed appropriately. Once the messages have been read but not processed correctly, they will remain in the mail box and read again in the subsequent polling cycle. If the problem is permanent, user should correct the problem or delete these messages by utilizing his mail client program.
Q: My mail messages don’t look like being sent out.
A: Please check the adapter monitor in Runtime Workbench. You will be able to locate your mail receiver channel listed under the Mail adapter. Incase this status is fine, the please have a look into the message monitor and try locating the audit log entries for this message. The detail text of the audit log would explain the entire problem.
Receiver Asynchronous Calls
Q: Is it for sure that an XI message with quality of service ExactlyOnce will only result in one mail message to be sent?
A: No. in general, the mail gateways don’t really support quality of service. Hence, the adapter simply just sends the message. If an error occurs, then the message is resent.
Other Receiver related Questions
Q: Some characters such as ä,ö,ü appear as being are corrupted in my mail. How can I reserve such characters?
A: First, you need to ensure that the payload passed to the mail adapter comprises of the correct characters. When XIALL or XIPAYLOAD without the mail package is utilized, the mail message sent out from the mail adapter signifies each payload of the original XI message which is passed to the mail adapter. Therefore, the user can analyze the problem by capturing the mail message sent out form the mail adapter. When XIPAYLOAD with the mail package is utilized, the mail message is then produced from the mail package payload of the XI message. Therefore, the user should temporarily alter the mode to either of the other two and then capture the mail message. for capturing the mail message, user can use the TCPGateway described in this Question "Can I monitor what my mail adapter sends or receives from the mail server?" for capturing the mail message. This tool can be ideally placed between the mail adapter and the mail server for capturing the messages. The captured messages can be stored in a file.
The corrupted original payload or the incorrect character code setting in the payload is the main cause for the corrupted characters. Through analyzing the captured message, the cause of this problem can be identified easily.
Q: Can I select the name of an attachment in the mail?
A: Yes, mostly the mail clients use some heuristics which are generally based on some MIME headers for deriving the name of an attachment. The MIME headers which are involved in most heuristics are Content-Description, Content-Type and Content-Disposition. When the user creates an XI message, the XI payload name is set automatically in the Content-Description. If the user wishes to change or set all of these headers, then he can use the MessageTransformBean module in the adapter framework.
Q: How can the user set the file name of a mail attachment?
There are various MIME headers which play a role in how the client is able to retrieve the file name of an attachment. Sadly, this behavior also varies amongst the various mail clients. The reason for this inconsistent behavior is that this mechanism has been incrementally extended. The old way is using the name parameter in the Content-Type header as mentioned in RFC1341. For instance, user can set the content type of an XML attachment as:
Content-Type: application/xml; name="abc.xml"
RFC1521 does not encourage the use of this name parameter in anticipation of the new header Content-Disposition, which is listed in RFC1806.
With this Content-Disposition header, user can set the file name as:
Content-Disposition: attachment; filename="abc.xml"
Some clients can display the Content-Description value as the file name. The Content-Description header is generally used to associating some descriptive information to an attachment (RFC1341) as in
Content-Description: my xml file
To avoid potential interpretation problems, it is therefore suggested combining the use of these headers.
How to use MailPackage in the Receiver?
A: Normally the mail header information such as "From", "To", "Subject" are derived from the channel configuration, when a mail message is sent out by the receiver adapter. For dynamically setting these headers, user can can use the MailPackage mode. In this scenario, the XI payload should be formated in the Mail Package XML format. The format of this mail package XML document is listed in note 748024.
The mail package is a denounced feature which is all supported for the existing scenarios and the asma attribtues should be utilized used for the new scenarios.
- My mail subject in non-ascii characters is not displayed in my mail client. Does this look like an error?
A: The mail subject line containing non-ASCII characters is encoded in a special format which tags the encoded text with its character set name, which is utf-8. This refers to that incase the mail client cannot display utf-8 characters, these lines are shown incorrectly. This is one of the limitations of the mail client.
- Can the user set Cc and Bcc headers?
A: These headers are supported from SP17. For the previous versions, there is no direct way for setting these headers. The user can configure an external mail account for forwarding the mail message with these additional header properties.
Q: Which URL does the user need to specify for some IMAP4 folder?
A: The user can specify your folder as URL. For instance, if your server is called host and your folder is called MyInBox which is in another folder called path, your URL will look like
If your server runs on another port than the default IMAP4 port (143), your URL can be written as
//where port is the port number
Q: Which user authentication mechanism is supported by the sender adapter?
A: The plain authentication and the CRAM-MD5 are all based authentication are supported(CRAM-MD5 support from SP11). The client certificate based authentication is not supported.
Q: Can the user use SSL for the connection to my mail server?
A: Yes. The user can use URL imaps://... for IMAP4 over SSL, pops://... for POP3 over SSL, and smtps://... for SMTP over SSL. If the ports varies from the respective default ports (993, 995, 465, respectively), they should be provided in the URL.
Q: My sender adapter is not working. What shall I do?
A: User should open a problem report, explain the problem, and provide the necessary information. See question "Which information should be involved in a problem report?".
Q: What is the purpose of the XIALL mode?
A: This mode allows the transport of an XI message over some mail gateways. The user can configure a mail receiver adapter at one XI system and a mail sender adapter at another XI system to transport XI messages between these two systems. All the information contained in the original XI message at the first system is reconstructed at the second system.
Q: What is the purpose of the XIPAYLOAD mode with MailPackage?
A: The mail package format (Mail) permits some of the mail transport precise information which needs to be included in the XI payload.
Q: Should the user use MailPackage or ASMA?
A: SP14 introuced the Adapter Specific Message Attributes (ASMA) which can be used to import and export adapter/transport specific headers into and out of XI. This is a generic mechanism for all adapters and other components like mapping and routing can be directly access or manipulate these values. The functionality provided by MailPackage is available in ASMA. Therefore, it is advised that the new scenarios utilize ASMA instead of MailPackage.
Q: My receiver adapter is still not functioning. What can the user do?
A: the user should open a problem report and provide the information given in the answer to question "Which information must be included in a problem report?".
Q: Can the user monitor what his mail adapter sends or receives from the mail server?
A: The mail protocols such as IMAP4, POP3, and SMTP are TCP based protocols. The user can configure any TCP gateway or monitor tool for capturing the data. User can find the document explaining ways of setting up the how to setup TCPGateway tool for mail adapter in the attachment section.
Q: Which all information should be included in a problem report?
A: Listed below is the information which must be included:
- Adapter Version SP and patch numbers of SAPXIAFC and SAPXIAF
- Description (participating components and concrete problem)
- For receiver problems
The channel setting
- The message entry from the adapter's message monitor in Runtime Workbench.
- The XI message which is passed to the adapter
- The mail message which is posted to the mail server incase available
The vendor information of the mail server
- For all sender problems
The channel setting
- The message entry from the error message folder in Runtime Workbench or from the adapters' message monitor
- The mail message which is fetched by the adapter
- The XI message which is passed to the adapter engine incase available
- The vendor information of the mail server
Q: How can the user trace the entire message?
A: If the wants to trace the content of Mails whichare coming intoPI(Mail Adapter)or the content of Mails which are going out of PI(Mail Adapter), then he should use this tool (TCPGW) Typically, this is done by configuring a TCP gateway between the Mail Client and the Mail channels(sender or receiver).The user can find a tool called TCPGateway in the attachment section of this note (stored in tcpgw.zip). He should unpack this zip file and open index.htm for more details.
Q:does the PI Mail adapter provides an Alert mechanism?
A: In Mail adapter, the alert mechanism isn’t implemented,quite unlike the file adapter. Therefore, the user cannot view any alerts triggerring when the processing of mail messages fail(with improper configuration, processing error etc), this looks like a limitation in PI Mail adapter.