Skip to main content  
  Easy400   |       IBM System i home   |   RSS feed
Main utilities
5250 utility
Windows utility
Service program
Sample code
CGI support

MIME & Mail
Frequently Asked Questions

Click an item to expand it:

1. General considerations on trouble shooting

As a rule, one should not expect everything running smoothly from the very beginning. E-mail messages do not reach their destinations, but you do not why.
Unluckily there is no solid problem determination tool, and you must try to figure out by yourself what is going wrong.

  1. IBM iSeries Infocenter page Troubleshooting e-mail provides a simple scheme to address most common cases.
  2. To solve particular e-mail problems, you may use the MMAIL CGI program DSPQZMFDTA to display the current entries of the QZMF journal.
    • Before running this CGI program, make sure to execute command
    • Then, in your WEB browser run the following URL:
      (of course, you must have installed the MMAIL HTTP directives,
      use command WRKLNK '/mmail/conf/httpd.conf' to display/install them.)
  3. See also this page.

Never despare. Soon or later you will fix the trouble; then try to remember what you did.

2. The e-mail messages do not arrive to their destinations

All mailing troubles do result into this condition. The problem stays in isolating the error.
A first step in this direction is that of finding whether the mail message was able to leave the system.
You must first understand how things work.

MMAIL builds the MIME message as an IFS stream file /mmail/temp/Qnnn.txt .
Then MMAIL calls API QTMMSENDMAIL that submits the request to MSF.
MSF reads the stream file, deletes it from the IFS, and passes it to SMTP.
SMTP cares for sending the message out from port 25. To where, that depends on SMTP attributes (command CHGSMTPA).

One thing you can tell for sure, is whether SMF has taken the message or not. Just enter command wrklnk '/mmail/temp/*' and see whether your message is still there. If yes, then you have troubles with MSF, if not, the message was hopefully passed to SMTP for being kicked off the system (only the QZMF journal can tell if that was successful).

Let us take the case when the e-mail message is still in directory /mmail/temp . Of course the message may be still there because you forgot to start msf or smtp (you may as well display the joblogs of the QMSF jobs in sbs QSYSWRK, to see if any nasty message there). Usually however, this is because something is wrong with the e-mail message itself.
First you should look at the joblog of the job sending the message via MMAIL, and check if there is a message telling that the e-mail was submitted to MSF. Next, you must display the /mmail/temp/Qnnn.txt stream file, check that both the sender's and the receiver's e-mail addresses are there, and that all the e-mail addresses contain the @ character.
If any error in the e-mail addresses, you may just key in your changes, save the changes and enter command mmail/resend. It may work (but you have still to fix the problem of bad addressing, see the next FAQ).

If the e-mail message is no longer in directory /mmail/temp/, it means that it was successfully passed to SMTP, but still you do not know whether SMTP was able to send it out.
Some little help in this case may come by trying to send an e-mail message through command SNDDST. If it goes through and reaches its destination, at least you know that your SMTP is working all right and that the external path is also working. To be able to use command SNDDST, you must use an user profile enrolled in the system distribution directory (ADDDIRE, WRKDIRE). We suggest that you enter a command like the following (just change the destination address to one that comes to you):
    DSTD('Hello via SNDDST')
    LONGMSG('Hi Charlie, you are receiving this message thanks to command SNDDST.')
    SUBJECT('Hello (SNDDST)')

If not even the SNDDST has success, the possibles causes could be:

  • the SMTP configuration is not correct (see FAQ number 7; if running Domino on the same system as MMAIL, see FAQ number 5)
  • if your system is sending the mail messages to a mail server other than your ISP mail server, maybe that your messages are simply rejected (see FAQ number 5).
  • the mailbox you are sending the message is inactive (in this case, you the sender's e-mail is yours, you should receive a non-delivery message)
  • your message is detected as a SPAM message at your ISP or at the ISP of the receiver (the receiver may use the webmail provided by his ISP and check if the message arrived and was routed to a SPAM directory or similar)
  • your system has been flagged as delinquent and enrolled in a Public Block List; as a consequence messages out of it are blocked in the network. To check out this, enter the IP address of your system at page SpamHouse inquiry.

3. Domain control characters ("@") not recognized as such by MSF

This issue is generally related to system value QCCSID 65535. Such a value inhibits page code conversion, and a result would transmit to MSF the wrong character istead of @. The problem is usually solved when one at last decides to replace the system value QCCSID with the appropriate value for the national language in use.
Check out the following IBM iSeries Infocenter pages:

See also FAQ number 15.

4. How to configure TCP/SMTP/POP to send and to receive mail

Click here to display a useful IBM document on this subject.

5. How to configure the Simple Mail Transfer Protocol (SMTP) server

See the following IBM Support document: Configuring MSF/SMTP on the IBM i.

5a. V7R1 SMTP change

See this page.

6. How to have outgoing mail from an iSeries be served by a mail server on another system

Suppose that your iSeries is not connected to Internet, and that you have another system connected to Internet and acting as a mail server.
To have the outgoing mail from your iSeries served by this mail server:

  1. suppose that the IP address of the mail server is "m1.m2.m3.m4' and that the IP address of your iSeries is i1.i2.i3.i4"
  2. on your iSeries enter the following command:
       chgsmtpa mailrouter('m1.m2.m3.m4') firewall(*yes)
    and re-start the SMTP server
  3. on the other system acting as a mail server, if a SPAM filter is active for SMTP, you must update the filter to allow mail requests from IP address "i1.i2.i3.i4".
    If the system acting as a mail server is an iSeries, V5R1 or later, enter the following command
       addsmtple type(*accept) intnetadr('i1.i2.i3.i4')
    and re-start the SMTP server.
    For more information about SPAM filters, see this page.
  4. If your system runs V7R1, the IP address or the name of the mail server should not be specified in parameter MAILROUTER, it should instead be specified in parameter MAILHUB. Starting with V7R1, parameter MAILROUTER tells the System i "Where should I send mail when I can't resolve the recipient?". Usual choice is MAILROUTER(*NONE).

7. How to have native SMTP working on a system where Lotus Domino is also running

Lotus Domino uses its own SMTP service on port 25, the same used by native OS/400 SMTP. Port 25 is locked by Domino, and the native SMTP is therefore inhibited.
To solve this conflict, you should use a function called "bind to specific IP address".
In the Domino environment, this is achieved using the CHGDOMSVR command to bind your Domino server to a specific address.
In the native environment, it is achieved through a function that allows the OS/400 SMTP server and OS/400 SMTP client to bind to a specific TCP/IP address.
In this way, even if you cannot change the SMTP port number, you can force the OS/400 SMTP service to use a specific TCP/IP address, different from the Domino one.
This technique is described in one of the IBM redbooks:
Lotus Domino for AS/400 R5: Implementation,
Chapter 5. One iSeries server and two SMTPs.
In this chapter you can find the instructions to setup the service up to V4R5. Starting from V5R1, you must use the Operations Navigator:
Network ---> Servers ---> TCP/IP ---> Select the SMTP service ---> Right button on it ---> Properties ---> Bindings

8. How to Configure a Relay Connector for Exchange Server 2010

See this page.
Also read the following note I received from a MMAIL user having intermittent problems in connecting with an EXCHANGE server:

  • We upgraded from 6.1 to 7.1 the weekend of 7/16/11. We had no issues with emailing using SNDDST or MMAIL. We upgraded our hardware to Power 7 the weekend of 7/29/11. Since then, we have been having intermittent issues sending email. My boss finally called IBM today and found out that in the CHGSMTPA command, a new parm was added back in 6.1. The new parm was FWDHUBSVR in which we loaded our IP Address for our Exchange Server. Once this was done all of our emails so far have been sent successfully.

9. How can I have SMTP sending the outgoing mail from a port other than port 25?

Run command
where xxx is the number of the port you want to use.
You may however need a PTF:

10. How can I implement E-Mail Authentication

See IBM Software Technical Document Configuring SMTP Authentication.

11. How to enablel SSL (Secure Socket Layer) on the SMTP server

See IBM i Information Center page Enabling SSL between the SMTP server and client on the sender system.

12. Using TXT SPF (Sender Policy Framework) records to overcome spoofing filters

Sender Policy Framework (SPF) is an email validation system designed to prevent email spam by detecting email spoofing, a common vulnerability, by verifying sender IP addresses (Wikipedia).
Alternate techniques to callenge email spoofing are: Sender ID, DKIM, and DMARC, see Wikipedia.

If a domain publishes an SPF record, spammers and phishers are less likely to forge e-mails pretending to be from that domain, because the forged e-mails are more likely to be caught in spam filters which check the SPF record. Therefore, an SPF-protected domain is less attractive to spammers and phishers. Because an SPF-protected domain is less attractive as a spoofed address, it is less likely to be blacklisted by spam filters and so ultimately the legitimate e-mail from the domain is more likely to get through.
SPF authentication is increasily implemented by major mail providers, like Hotmail, Comcast, Gmail, Verizon and many more.
Therefore, to increase the chances that your messages pass the receivers spam filters, it is highly recommended that you provide your domain name with an appropriate TXT SPF record.

How you do it.

  1. Send a MMAIL message to yourself (for instance to your Outlook account) using as a sender your email address (example where "" is the domain you generally use to send mail from your IBM System i.
  2. In Outlook, do not open the message, right click it and select "Message Options". At the bottom you would read the initial message headers. You should care for the "Received:" ones. As an example, you may read
    Received: from unknown (HELO ( by with SMTP; 7 Jan 2014 23:01:21 -0000
    Received-SPF: none ( domain at MYDOMAIN.COM does not designate permitted sender hosts)
    These messages tell that the message was sent from the mail server with IP which is not designated as a permitted sender by domain "". In other words, these messages tell that the incoming mail message could be a spoofy one and it should be no surprise if in some other environment the message is blocked by a spam filter.
    Note 1 - Different ISP's may report the message logging headers in different ways. For instance, if the TXT SPF record is not available, some ISP's may not report the logging header Received-SPF: none.
  3. What you have to do then, is to connect to your ISP site, where domain "" is defined, and add to the domain definition a TXT record with some contents that, in the simplest case, look like as follow:
    v=spf1 ip4: a -all
  4. Once you have done that, from your IBM System i send again the same MMAIL message to your Outlook account. If you added the appropriate TXT SPF record to your domain, this time in the initial message headers you would read Received: from unknown (HELO ( by with SMTP; 7 Jan 2014 23:28:13 -0000
    Received-SPF: pass ( SPF record at MYDOMAIN.COM designates as permitted sender)
    These messages now state that the IP address of the mail server was designated as permitted sender by domain MYDOMAIN.COM
In reality, the syntax of a TXT SPF record is more complex than it appears from the simple case above.
We suggest the following links:

13. Does MMAIL have any facility to send SMS messages to any mobile number and how can that be implemented?

You may send a specifically-customized e-mail message to a SMS gateway to have it converted to a SMS message and sent to the desired mobile(s). See this page.

14. How to support spool files with more than 132 characters per line

If you are using Spool-file-to-Pdf conversion tool CVTSPLSTMF (use command MMAIL/CVTTOPDF to check it out), then the maximum supported number of characters per line depends on the record length of file mmail/spools, which is delivered as 132.

To increase this limit to (say) 180, operate as follow:

  1. dltf mmail/spools
  2. crtpf file(mmail/spools) rcdlen(180) mbr(*none) maxmbrs(*nomax) size(*nomax) aut(*all)

15. How to run MMAIL on a system with system value QCCSID = 65535

Any job started on iSeries inherits its CCSID from system value QCCSID.

CCSID 65535 inhibits code page conversion (see this Infocenter page).

On the other side, the system API used by MMAIL, QtmmSendMail, requires the sender and the addressee data be in code page 500; moreover, the MIME file itself needs to support code page conversion. For this to occur, both the job using MMAIL commands or subprocedures, and the QMSF jobs must run with a CCSID other than 65535.

This can be implemented as follow:

  • In any interactive or batch job with CCSID 65535, before starting any MMAIL activity execute command MMAIL/FIXJOBCSID.
    This command sets an appropriate CCSID value for the current job and for the MSF jobs.

See also command MMAIL/SET65535 .

16. How to insert an image in the body of an EML... message

You may insert one (or more) image(s) in the body of your EML ... (EMLMSG, EMLSPL, etc.) message by simply specifying in any point(s) of your message text the < img > HTML tag(s) for the desired image(s). This is usually done to insert an image as a logo.
For instance, you could insert the image of a boat by inserting the following < img > HTML tag:
< img src="" > .

17. What is the maximum number of destination addresses for a MMAIL e-mail message?

MMAIL procedure SendMail allows for a maximum of 1,000 destination addresses.
Your RPG programs, however, can perform multiple calls to that procedure, thus implementing a higher number of destinations per shot.
For instance, both MMAIL programs EMLSPLF and EMLSPLF2 (commands STREMLSPLF and STREMLSPL2) can send a message to an unlimited number of addresses.

18. I realized that since July 2012 Unicode UTF-8 has become the MMAIL default character set, while before it used to be ISO-8859-1.
What was the reason for this change and how can I set the default MMAIL character set back to ISO-8859-1?

Unicode UTF-8 (CCSID 1208 on IBM System i) is a universal multilanguage character set, emcompassing all the other characters sets (like ISO-8859-1) available for MMAIL. By using UTF-8 you have no problems, for example, with both English and Czech alphabets. The only disadvantage is that UTF-8 texts, before been interpreted by a mailer, cannot be read by a human being, as a single original character may be represented by UTF-8 multiple characters.
The reason why UTF-8 has been elected as the MMAIL default character set, is that by doing this MMAIL setup is very easy also for Northern and Eastern and European countries, while it still works perfectly for the traditional Latin and English languages.
Should you like to set the MMAIL default character set to one of the other available character sets, this is how you do it:

  • run command MMAIL/CHARSET
  • remove the 1 in front of Unicode UTF-8
  • select with a 1 your desired default character set
  • press the Enter key to perform the update
  • press F3 or F12 to exit.

19. MMAIL commands for e-mailing spool files fail when referring to a spool file generated by another job. Why does that happen?

MMAIL commands referring to a spool file generated by another job may fail in retrieving such a spool file.
Possible reasons are:

  1. The user profile of the job issuing the MMAIL command has no authority on the output queue containing the desired spool file
  2. The output queue containing the desired spool file specifies AUTCHK(*OWNER) instead of AUTCHK(*DTAAUT)
  3. The job generating the desired spool file has ended and its spool files were detached from it. This occurs when
    • system value QSPLFACN specifies *DETACH, or
    • the user profile generating the spool file is related to a job description specifying QSPLFACN(*DETACH)
    • the job generating the spool file specifies QSPLFACN(*DETACH)
    In such a case, spool files generated by it can no longer be retrieved by specifying the qualified job name of their generating job.

20. Can I use CGIDEV2 to dynamically generate a text or a HTML to be sent as body of an e-mail message?

Of course you can.
The easiest way would be to

  • use CGIDEV2 procedure WrtHtmlToStmf() to generate a temporary IFS stream file containing the HTML or the TXT for the message body
  • if the stream file is HTML, use MMAIL command EMLHTML or command EMLHTML2 to e-mail the message
  • if the stream file is a TXT, use MMAIL command EMLTXTSTMF to e-mail the message
  • delete the temporary stream file
Should you instead decide to pick up in your program the CGIDEV2 generated output buffer - via CGIDEV2 procedure getHtmlBufferP() - in order to build and send your own e-mail message, you are recommended to specify in your WrtSection()'s the second optional parameter *on, not to generate a New Line x'15' EBCDIC character at the end of each line of your script. See this page.

21. I'm receiving error message ... address " ... " not valid when trying to run a MMAIL/EML... command. What could be the reason?

Usuallly the reason is that the email address contains some unsopported character(s).
Characters supported in an e-mail address are documented in file MMAILDATA/EMAILCHARS. This file contains a single record. The record contains the supported characters. Characters are NOT case sensitive.
You should add to that record the characters in your e-mail address that are missing.
For instance, is the e-mail address reported in error is "/fax=3172271175/BK@gpc.fax", the caracters to be added are / and = .
You may use command STRDFU (option 5) to update the record of file MMAILDATA/EMAILCHARS.
After doing that, signoff. Then sign on again and retry you MMAIL/EML... command.

22. Where can I find the example of a WEB CGI program sending an e-mail message?

There is an example in topic "Sample Code", go there!