Skip to Content

XI: Sender mail adapter – PayloadSwapBean – Step by step

In some of our integration projects we may be asked to receive messages by e-mail.
It can be a simple XML message or even a large XML-IDOC. However in most cases
our message will not be a part of the e-mail’s payload but will be sent as a file attachment.
Can XI’s mail adapter handle such scenarios? Sure it can but with a little help
from the PayloadSwapBean adapter module. In this weblog I’ll demonstrate how to configure it.



We’d like to receive an XML message which will be sent as the e-mail attachment
and we’d like to process the message later on (mapping, etc).

At first we have to configure/create out mail communication channel.

Step 1

Configure your mail communication channel:

– Transport protocol: POP3

– Message Protocol: XIPAYLOAD

– since we want to use our attachment we have to receive it first:


– change the QoS from Best effort to an asynchronus one:


– don’t forget to specify Default Parameters:


Step 2

Now when the e-mail message comes to our account
we should see that it was picked up by our mail adapter:


If the message was picked up we can proceed further on.

Step 3

– let’s open Messaging system:


– Display message bytes



to see how our e-mail message looks like:



We can see some attributes from the MIME header such
as Content-Disposition or Content-Description.

We can use them to tell our mail adapter to treat them as the main message and not the original payload.

With those values we can go back to our mail adapter and use them in the






When you configure the rest of the data inside Integration Directory and do some more tests
we should be able to see that the message which goes to our interface mapping

is actually the attachment and not the main payload itself.




You must be Logged on to comment or reply to a post.
  • hi michal…. i must say its another nice contribution from u…. i’m very new to XI and learning from ur blogs… in this one i cant figure out the exact use of ‘Module Key’… is it to make the distinction between the parameters for the respective modules(as there r more than one modules used)?… thnx in advance
    • hi,

      yes that’s what they are for

      from SP15 you no longer have to use them to
      distingusih modules 🙂

      please ask questions on the XI forum


      • Hi

        This helps to understand the attachment handling in a good way. But i am strucked with a situation where i need to read mail with attachment in an mail box and forward it to another mail box. The mailbox is configured to send the mail to FAX which will print the attachment. But only the body is getting printed, but not the attachment. Any pointers on this will be helpful.


        • hi,

          all you have to do it to check how the message
          looks like in the second mailbox
          then you will know why the attachment is not getting printed

          you can change many things to the attachment
          in the adapter module in the mail channel


          • I am also trying the same scenario. I have configured exactly as itis mentioned in your blog. But my message after receiver determination is struck in a queue saying ‘ access to null object is not possible’. I guess, the payload structure is not recognized by interface mapping. Could you pls tell me what is the source interface structure for processing this message.

            Thanks, Sreekanth

          • hi michael,
                I have tried the mail adapter scenario on the receiver side it was working fine . but can u explain how i have to trigger an external mail coming from yahoo or gmail or any external account with attachments or without attachments.
            Is it enough by giving the URL of the server can i  access the e-mail or any additional configuration has to be done.
            I have used the PayloadSwapBean on the receiver side it was working fine, is it the same case on the sender side also if we have to trigger an external e-mail with attachment.
            please explain with an example.
            i have tried triggering e-mail with our internal microsoft exchange server it was picking all the mails in the inbox , but if i have to trigger particular mail from a person whta all configurations i need to be done.

            chaithanya vallem

  • Hello,

    I have used your weblog and configured my email sender adapter.

    What i cannot seem to do is convert the attachemtn to an xml.

    Can anyone help ??



    • Dimtris,
      You can use the PayloadSwapBean to swap the attachment and the main payload as shown by Michal.

      It is assumed that the attachment has to be a .XML file. In your case if the attachment is a non XML, I guess you would need to write a custom module to convert this non XML into XML or, use a Java Mapping or, consider if you can use MessaeTransform Bean after the PayloadSwapBean in the Sender Mail Adapter.

      PS: Please raise questions on XI forum.

  • Hi Michael

    This is a very helpful weblog. However I have got a question.

    If there were more than one attachments to the email and we wanted to process each attacment as a separate message, How can we achieve that?

    I am having a lot of trouble figuring this out and your help is very welcomed.

    Thanks in advance.


    • Hi,

      this module cannot handle multiple attachments
      but this can be handled in your own adapter module quite easily, I did it once at least


      • Hi Michal

        Thanks for your reply. I did have a go at coding the custom module for dealing with the multiple attachments in the Sender Mail adapter.

        I am still having some difficulties though. What I can not figure out at this point is how to pass each attachment one by one to the Integration Server for mapping.

        Once I get to the process part – see below (I am following the How To Document from SAP for developing Custom Module )

        public ModuleData process(ModuleContext   moduleContext,ModuleData inputModuleData)throws ModuleException {

        try {
          Message msg = (Message)


        I can see methods that would allow me to find out how many attachments there are. and I can loop to get each one of them.

        However, I am not sure how to pass each attachment as a Document to the Integration Server – one by one. for mapping.

        Could you please shed some light as to how you managed to achieve this.

        Many Thanks for your help.


      • Hi Michal

        I am facing the same problem.

        I cannot find a way of sending the attachments (one by one) to the Integration Server from within my custom adapter module.

        The sample adapter modules code doesn’t seem to deal with sending multiple messages. I have also searched the javadoc to no avail.

        Reading through the blog it would appear that you have done this before. It would be great if you could provide me with some sample code as to how to achieve this.

        Many thanks

    • Hi,

      you can send it one by one (in a loop) from adapter module just check sample adapter modules code from SAP and you will find how to do it
      it’s not very sophisticated


  • Hi Michael,
         I can read the PDF using Payload Swap Bean as you mentioned in this Blog,I have a converison Agent module to convert that PDF to XML.How can I make this Payoload Swap Bean OUTPUT to Custom Module INPUT.

    Thanks and Regds,

  • Hi Michal,

    great weblog. This has really been a big help.

    My problem is as follows: I need to get the content of the attachment AND the header-data of the e-mail (like sender/cc/subject/..) in 1 XML so I can process this further.

    Is there a way to do this? Can I use the PayloadSwapBean for this? Currently when I use the PayLoadSwapBean I obviously only get the attachment-content..

    Thanks in advance!


    • hi Jan,

      this would be fairly easy with a little adapter module added to the standard mail adapter

      if you need any help with that let me know by mail (my mail is the business card)


  • hi Michal,
      Congrats for this information riched Blog.
    I have one doubt regarding usage of PayloadswapBean module.
    Can we use same module for SOAP attachment to retrive the paylaod. If yes than please put some light in following problem.
    I am getting only one attchment as SOAP response at SOAP receiver channel.
    I want to retrive Payload(i.e xml file) from it So that i can further process it(map it to another datatype).
    When i used this module I got the error that “Object can not be look up by payloadswapbean”.
    Can u please tell the all parameter value along with name with respect to the attchment(i.e MainAttachment(text/xml)under Payload folder in SXMB_MONI)
    Jaideep Jain
  • Hi,
    I have a scenario where i have to recevie a zip file with password as the attachment from a mail server and open the files with the given password, unzip and upload all the files to SAP. can any body please help me in this scenario. Any helpful information is appreciated.
  • Hi Mic,
           Thanks for your excellent blog. It is very useful.I have a question here.

    Am getting the following error message on this:
    “exception caught during processing mail message; unexpected user response; read -ERR Command is not valid in this state”

    I am using PI 7.1, where the default XI parameters info is missing.

    Please help what can the reason for this error.
    Kindly help:-)

  • Hi Michal,

    If we want to process the non .XML file (Ex: CSV) as an attachment then shall we use filename=”MainAttachment-1.csv/doc/..”?


  • This article may be old and some of the images are broken… but it is still helpful relevant even today!

    For info, in our PI 7.11 case we needed to use

    swap.keyName => Payload-Name

    swap.keyValue => MailAttachment-1