Skip to Content
Author's profile photo Eng Swee Yeoh

Stop using Mail Package! © – Simplify your mail receiver adapter scenarios

Update 16 Mar 2016: Include additional case for Scenario 1 if main payload needs to be renamed dynamically

Update 11 Mar 2016: Enhance Scenario 3 with Java mapping to dynamically set ASMA values


PI (in its various names and forms) has evolved and changed in over the decade or so it has been around. New functionality and enhancements are introduced at every SP, EHP and version. However, despite all these changes, some of the techniques and functionalities that are obsolete, outdated, deprecated or no longer relevant are still widely used today. One such feature is the Mail Package feature used in the Mail adapter. As stated in SAP Note 856599, it is a deprecated feature and should not be used for new scenarios. Following are the excerpts from the note itself:

The mail package is a deprecated feature that is supported for the existing scenarios and the asma attribtues should be used for new scenarios

Q: Should I use MailPackage or ASMA?

A: SP14 introuced the Adapter Specific Message Attributes (ASMA) that 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 such as mapping and routing can directly access or manipulate these values. The functionality provided by MailPackage is available in ASMA. Therefore, it is recommended that new scenarios use ASMA instead of MailPackage.

Usage of Mail Package increases the complexity of the development, especially when an email with body and attachments need to be generated by the mail receiver adapter. This requires manual construction of the MIME stream using Java mapping or UDFs.

In the past, even without Mail Package, it is recommended to construct the MIME stream for the above mentioned scenario as detailed in Stefan Grube‘s blog Create email with body and attachments for binary payload with Java mapping. I have repeatedly point to that blog whenever a thread arises in the forum with such a requirement.

Recently, with the availability of the functionality to debug PI’s application as detailed in Vadim Klimov‘s blog Let’s Debug! Debugging and Decompilation on-the-fly in SAP Application Server Java, I have managed to understand further the behavior of the mail adapter. Apparently, my previous understanding is incorrect and it is possible to significantly simplify mail receiver adapter scenarios when Mail Package is not used.

In this article, I will share the design and configuration required when using the mail receiver adapter without Mail Package, for the most commonly used scenarios. All these scenarios use XIPAYLOAD as the Message Protocol.

Scenario 1 – Mail with Attachment Only

The first scenario is the simplest scenario, where the main payload is sent as an attachment in the mail. There will be no content in the email body. This is the default behavior of the mail adapter.

The scenario is an SFTP to Mail iFlow. For the sake of simplicity, the configuration of the SFTP channel is not included.

a) Retain original file name of the main payload as an attachment

The mail receiver channel is configured as follows:-

i) Use Mail Package – unchecked

ii) Keep Attachments – checked

Value of Content Encoding is optional, so it is left as the default of base64.


The following is the test file that is picked up by the SFTP sender channel.


The email received has the file as an attachment.


The attachment’s name is dynamically determined based on the input file name. This is true even when ASMA is not set on the SFTP sender channel. This is because the file name is stored in the MIME header (Content-Disposition and Content-Description) of the SOAP envelope’s attachment as shown below.


b) Fixed naming of the main payload as an attachment

If the attachment name needs to be statically fixed to a certain value, this can be achieved by setting the following MIME headers using MessageTransformBean as shown below.

  • Content-Type
  • Content-Disposition
  • Content-Description

The reason all three headers need to be set is due to differing behavior of different mail clients. This is further explained in the question “How can I set the file name of a mail attachment?” of the SAP Note mentioned in the Introduction section.



c) Dynamic renaming of the main payload as an attachment

Additionally, if the main payload needs to be renamed dynamically, the above approach can be extended as detailed in the following article

SetMailAttachmentNameBean – Setting dynamic attachment name for main payload

Scenario 2 – Mail with Body Only

For this scenario, the main payload is to be used as the email body. There will be no attachment in the email.

To accomplish this, the channel setting is similar to the above.


In order to set the main payload as the body, we need to change the MIME header’s Content-Type and Content-Disposition. This can be accomplished using MessageTransformBean with the following configuration.

Parameter Value
Transform.ContentType text/plain; charset=”UTF-8″
Transform.ContentDisposition inline

The content of the previous test file is slightly modified as follows.


Following is the received email.


Scenario 3 – Mail with Body and Attachment(s)

Finally, we will construct an email with both body and attachments. In the past, this is the most complex scenario which requires MIME construction whether Mail Package is used or not. Additionally, if the content is binary, it needs to be encoded in Base64.

However, this can now be easily achieved with the exact same configuration in scenario 2. Additionally for this scenario, a Java mapping will be included to dynamically set the Email To and Subject ASMA values via Dynamic Configuration. As such, dummy values are configured in the channel.



In order to simulate a message with attachments, the SFTP sender channel is enhanced to pick up additional files, a PDF file and an Excel file.


The following logic is included using the Write Java Mapping directly in ESR! technique. In summary, it just performs a passthrough for the main payload content, and updates dynamically the THeaderTO and THeaderSUBJECT values.

public void transform(TransformationInput input, TransformationOutput output) throws StreamTransformationException {
  InputStream inStream = input.getInputPayload().getInputStream();
  OutputStream outStream = output.getOutputPayload().getOutputStream();
  try {
   // Transfer main payload content from input to output
   byte[] content = getInputStreamBytes(inStream);
   // Update dynamic configuration attributes
   DynamicConfiguration dynConfig = input.getDynamicConfiguration();
   // (1) Email To
   DynamicConfigurationKey emailToKey = DynamicConfigurationKey.create("", "THeaderTO");
   dynConfig.put(emailToKey, ";");
   // (2) Email Subject
   DynamicConfigurationKey subjectKey = DynamicConfigurationKey.create("", "THeaderSUBJECT");
   dynConfig.put(subjectKey, "Dynamically updated email subject");
  } catch (Exception e) {
   throw new StreamTransformationException("Exception: " + e.getMessage(), e);
private byte[] getInputStreamBytes(InputStream inStream) throws IOException {
  ByteArrayOutputStream baos = new ByteArrayOutputStream();
  byte[] buffer = new byte[8192];
  int read = 0;
  while ((read =, 0, buffer.length)) != -1) {
   baos.write(buffer, 0, read);
  return baos.toByteArray();

The files are uploaded to the SFTP server to be picked up.


In the message monitor, we can see that the message contains the main payload and the two attachments.



After the Java mapping is executed, the Message Attributes are updated accordingly.


And finally we received the email with the body and attachments (and their names) intact. Additionally, the email to and subject are populated with the dynamically determined values.



As shown above, we no longer need to resort to custom Java logic to generate email content for the various scenarios. By avoiding usage of the deprecated Mail Package, it is now possible (at least as of PO 7.4 SP08) to achieve the various mail scenarios with just configuration as well as the aid of the standard MessageTransformBean module. This will significantly reduce development effort for such scenarios.

Please note that for the purpose of this article, the mail headers (To, From, Subject, etc) have been configured as static values in the channel. It is also possible that these are dynamically determined during runtime by using ASMA and setting the corresponding Dynamic Configuration attributes prior to the execution of the mail adapter.


As a comparision, following are references for the other existing approaches for using the mail adapter:-

Constructing MIME stream for Mail Package with Java mapping

XI Mail Adapter: An approach for sending emails with attachment with help of Java mapping

Multiples content Email – File Attached and body text

Constructing MIME stream without Mail Package with Java mapping

Create email with body and attachments for binary payload with Java mapping

Dynamically setting the filename of the attachment using UDF

Dynamic filename in mail receiver adapter made easier

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Vikas Kumar Singh
      Vikas Kumar Singh

      Hey Eng,

      Awesome work. Even if I don't praise the blog I have to praise the way you picked up the queried of mail adapter frequently appearing and solved in 1 shot with the blog.

      I still wish more ASMA elements are allowed and one specific requirement which I have seen a lot is filtering the mails based on subject or some other parameter i.e., the channel doesn't pick up what we intend not to. Hope SAP considers that.

      Great work



      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Vikas

      Thanks for your comment 🙂 Coincidentally I was working on a similar requirement and wanted to nail down the behavior of the adapter before coming up with the solution.

      Yes, I say the few queries on filtering by subject. Maybe you can try submitting an idea for it at Ideas Place or wait for the next round of the Customer Influence project.


      Eng Swee

      Author's profile photo Raffael Herrmann
      Raffael Herrmann

      Hi Eng,

      thanks for the well written article. I've got one more question. Will the SetMailAttachmentNameBean replace the MessageTransformBean in scenario 1 or does it have it's own different purpose?



      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Raffael

      You are very perceptive! 😉

      I was prepping up the GitHub repo for a new release, and SetMailAttachmentBean is a new module for it. It is an extension of the approach written here. You can read more about it below:-

      SetMailAttachmentNameBean - Setting dynamic attachment name for main payload


      Eng Swee

      Author's profile photo Raffael Herrmann
      Raffael Herrmann

      Hi Eng,

      I was just sending a commit to one of my open source projects, when I saw your SetMailAttachmentBean commit on Github. So I was curious about it's functionalty. 😉



      Author's profile photo Prabhat Singh
      Prabhat Singh

      Hi Eng,

      I am working for a outbound Scenario (PROXY to SFTP). As per the requirement whenever data successfully sent from SAP PI to Third Party SFTP server at that time we need to send a notification "ABC Interface- Data Successfully sent from SAP PI to XYZ Server".

      In my case we don't want to send any attachment , we just need to send a notification only.
      I tried all above scenario but I am unable to get desired result.


      Thanks in advance.



      However i implement the SAP Note 748024 , and with the help of Mail Package , i got the desired result.
      Can you please guide me how i can avoid Mail package to get the desired result at channel level itself.


      Author's profile photo Michael Hall
      Michael Hall

      Eng, thank you for the descriptive blog.  Scenario 2 was an exact requirement of mine.  My first couple of searches did not turn up the link to your blog, nor a useful solution.  That surprised me because this blog contains recent and very relative information about the email adapter, which we are using for the first time.  Thanks again!


      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Michael

      Thanks for the feedback and I'm pleased to know that this has been helpful for your requirement.

      Searching is always a tricky bit - using the right search tool as well as the right search term. I personally use the Google Custom search as mentioned in the blog below:-

      Custom Google Search for the New SCN

      If you use the above search tool, this post would appear in the results with either of the following search terms:-

      - mail receiver without mail package - 1st result

      - mail adapter with body only - 5th result


      Eng Swee

      Author's profile photo Former Member
      Former Member

      Hello Eng,

      Hope you are doing good!

      I have a little similar requirement wherein PI Rest Adapter will pass on the attachment (may have different extension like jpg, pdf, xlsx, txt, docx and etc) content in bytearray and PI have to send a mail to the recipient with attachment.

      I have posted a question too for seeking help on this. Link:

      Could you please help or suggest me in this regard.


      Best Regards,

      Sachin Jangir



      Author's profile photo Nagesh Chepuri
      Nagesh Chepuri

      Hello Sachin,

      Hope you are doing good!

      I have the requirement read mail form exchange server using REST adapter. How you are using REST adapter in SAP PI. Can you please provide screen shots what parameters need to pass. So I will create sender and receiver communication channels.

      Thanks in advance

      Best Regards,


      Author's profile photo Former Member
      Former Member

      Hi there , nice article and I am working on scenario #3 and let me explain it and until now achieved via xslt mapping and I am in the process of enhancing.

      1.scenario# 1 is built already where 2 OM's  work to update the ASMA variables and then to generate a crisp formatting of source into xhtml format.

      2.receiver mail adapter has a customer adapter module (pdfwrite) which renders PDF before the adapter sends it out.

      current requirement where I am stuck.

      1. Add a body which is static disclaimer text which matches scenario#3
      2. Add a logo to the existing scenario while rendering a PDF .

      any thoughts on this ? Your advice is appreciated in advance

      Author's profile photo Fellipe Vicalvi Mendes
      Fellipe Vicalvi Mendes

      Hello Eng Swee Yeoh!
      You have made a nice blog. Please, do you have any blog or tips to not use mail package in Mail Sender Scenario?

      Thank you very much!

      Author's profile photo Former Member
      Former Member

      Thanks Eng.. 🙂 i followed the same Document of yours and tried scenario 1.

      But after all configurations i am getting the below error.

      Pls help..




      Author's profile photo Sonal Mangla
      Sonal Mangla

      Hi Eng

      Wonderful blog!! Helped me with couple of mail scenarios. Worked like a charm 🙂 Thanks.

      Just a quick question. In order to set the ASMA values, we write java mapping. Because we are setting all email properties dynamically via ASMA, Does that means the target message doesn't have to be necessarily the standard Mail message that's provided by SAP?





      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Sonal

      Yes, the exact intent of this blog is to prevent usage of the standard Mail package since it is deprecated.



      Eng Swee

      Author's profile photo Sonal Mangla
      Sonal Mangla

      Thanks Eng for your response. So what do we use in the target operation? My requirement is to send an email based on a condition. For which I have also posted a question. Your valuable inputs will be highly appreciated

      Author's profile photo Former Member
      Former Member


      Hello Eng,

      Goes without saying, it's very interesting.

      I am trying to implement the third scenario, email body + attachment in your way.

      The email body has some constant text with dynamic values like company code+ month etc.  and the entire input workbook as an attachment.

      I have received email with attachment by setting the MIME headers using MessageTransformBean:
      •Content-Type                : application/msexcel
      •Content-Disposition      : attachment;filename="Report.xls"
      •Content-Description      : Report.xls

      But I am still not clear from your blog as how to add email body to it.

      Can you guide?

      Thank You.


      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Indu


      The email body will consist of the main payload on the PI message. If you want to have a plain text email body, then you will need to construct the main payload using Java mapping.



      Eng Swee

      Author's profile photo Ambrish Mishra
      Ambrish Mishra

      Hi Eng Swee,

      I have a scenario similar to Scenario 1 - Mail attachment only; and I am unable to retain the source file name in the email attachment in a pass through scenario. I am on PO7.5. Is there any configuration in NWA required for the file name to be retained in the email?



      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Ambrish


      It very much depends on what is the adapter type on the sender side. Only certain adapters will set the file name in the MIME envelope.  See my screenshots above to see how you can check that out. If the MIME headers for file name is not available, then you need to build some form of custom logic to populate it.



      Eng Swee

      Author's profile photo Ambrish Mishra
      Ambrish Mishra

      Thanks Eng Swee!

      That means the MIME headers for file name are not provisioned by the file adapter.

      Author's profile photo Former Member
      Former Member

      Hi Eng ,

      We have a requirement where client will send a xml file to SAP PI via webservice (SOAP sender)
      We dont have any ESR or mapping object involved here .
      We have to send the received xml file as-is to the business user via email.
      I have created an ICO with dummy sender and receiver Service interfaces.
      When i click on 'Display WSDL' in ICO , it throws an error 'Software component version not defined; select an appropriate software component version'
      Since I have not created any ESR object and hence no SI , software component version is greyed out.

      So that raises below queries -
      1. Is outbound SI mandatory for SOAP sender ? Because then only we can specify the SCV and provide the wsdl url to the client.
      2. If I ask for the wsdl structure from the client and import it as an external definition in PI , in that case how do i perform the message mapping for email? I need to send the xml file as an attachment in email . Is it possible ?


      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Vaibhav


      If you are sending the XML payload as is, then you don't need to specify the SWCV or generate a WSDL out of it. Just provide the sender system with the endpoint URL in the following format

      http:// <host name> : <port name> /XISOAPAdapter/MessageServlet?senderParty= <name of the sender party> &senderService= <name of the sender service> &interface= <name of the interface> &receiverParty= <name of the receiver party> &receiverService= <name of the receiver service> &interfaceNamespace= <name of the interface namespace>



      For use case 1, you don't need to map anything, whatever is in the main payload is sent as the attachment of the email.



      Eng Swee

      Author's profile photo Sandra Hagmann
      Sandra Hagmann

      Hi Eng,

      Thanks a lot for the interesting blog. But unfortunately I am not able to implement my request because it is a Little bit different to your example.

      I need a Mail with Body and Attachment. I get a payload (IDoc from SAP System). With a Java mapping I create an Excel file including the IDoc data. This Excel should send per email as attachment. This works.

      But I also need a little text as mail Body. This is for each mail a standard text which I will create at the mapping, only the recipient is another like "Dear Partner, please find attached our purchase order as Excel file. With best regards..."

      At your third example the body text and the csv are both at a file which you get from a ftp Server.
      I don't have any idea how I should get the body text in the main payload and the excel as second payload as attachment.

      Thanks for any help

      Best regards Sandra


      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Sandra


      To achieve "Mail with Body and Attachment", your Java mapping needs to create the mail text as the main payload (replacing the IDoc content as main payload), and convert the IDoc to Excel into the attachment.

      To set the text as the main payload, you basically change the content written into the output stream.



      Eng Swee

      Author's profile photo Mudassir Mahmood Naqvi Syed
      Mudassir Mahmood Naqvi Syed

      Hello Eng,

      First of all thank you for your extensive and very informative blogs.

      With respect to the third scenario in this blog, I have tried to emulate your findings in our current requirement, to send the Mail body with attachment.

      I have successfully implemented the same scenario in PO 7.4 SP12.  However with PO 7.5 SP 07 I have tried with everything possible and have had no luck. I have reached a conclusion that it could be due to an unsupported Service pack.

      I was wondering if you are aware of any supported Service packs in PO 7.5 for this scenario to work?  I will be very obliged if you could get back to me with any information you have.


      Many Thanks,



      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      I don't have a PO 7.5 system to try this out, so I can't comment on why it would not be working there.

      Author's profile photo Former Member
      Former Member

      Hi Eng,


      Excellent blog, and excellent work!.  Im replacing mail pck now!!



      Author's profile photo Claudio Palladino
      Claudio Palladino

      Hi Eng swee,

      I m working on mail to mail scenario asynch.

      I m using two channels : sender pop3  and receiver SMTP.

      All looks fine but when i looks on monitoring channel the message remain in to bè deliivered status, how is It possibile? And how i can solve?


      Author's profile photo Sirisha Kairamkonda
      Sirisha Kairamkonda

      Hi Eng swee,

      I followed your blog to create File(NFS) to Mail with multiple attachments. However I cannot get the attachments with same name and content type. can you please guide me ?




      Author's profile photo Javier Villarreal N
      Javier Villarreal N

      Hello Eng,

      Thanks for the very informative blog.

      I'm working on scenario #1.  I'm reading files from a folder and want to send them as attachments keeping their file names.  So my scenario is File to Mail.

      I was able to assign a fix name using the MessageTransformBean parameters but how can i include a variable to this parameters.

      File adapter's ASMA sets the FileName and it should be available, i'm picking it up on another file to sFTP scenario with %FileName%.

      How can i specify a variable on MessageTransformBean's Descrition, Disposition and Content type parameters,  could i just to the %FileName% as i do on the sFTP receiver channel?.

      or am i forced into creating ESR design objects and write a UDF?.

      thank you so much in advance.


      Author's profile photo Faisal Jamal
      Faisal Jamal

      Hi Javier,


      I am facing similar issue. I have File to Mail scenario and just need to have attachment with same name as input file. But the attachment name comes as "MainDocument.xml". And thats what is shows in content-Disposition in SOAP Envelope.

      Were you able to resolve this?




      Author's profile photo Flavio Gulacsi Philippi
      Flavio Gulacsi Philippi


      I've been trying to configure this scenario using SAP PI 7.5 SP17, but the file name comes always as "MainDocument.xml" even though I am using the AF_Modules/MessageTransformBean :

      And it doesn't matter if I send it with or without mail package, although the XML says it should be as an attachment and as an XML file :


      The mail application (it can be Google, Outlook, iCloud, UOL, many others) ALWAYS show it as BODY / Plain Text, never as an ATTACHMENT:




      Any ideas what could be wrong?


      Flavio G. Philippi


      Author's profile photo Praveen Abby Thomas
      Praveen Abby Thomas

      I was trying to use scenario 1 for a pass through file to mail scenario. I see that when I use SFTP sender, the filename is coming as the source filename. But while using File sender the attachment name is coming as MainDocument.xml. Is there any additional configuration to be done for File sender?

      Thank you