(Reference manual: IBM i Networking E-mail Version 7.2)

Click an item to expand it:

1. Trouble Shooting - 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
     GRTOBJAUT OBJ(QUSRSYS/QZMF) OBJTYPE(*JRN) USER(QTMHHTP1) AUT(*USE)
   • Then, in your WEB browser run the following URL:
     http://.../mmailp/DSPQZMFDTA.pgm
     (of course, you must have installed the MMAIL HTTP directives,
     use command WRKLNK '/mmail/conf/httpd.conf' to display/install them.)

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

2. Trouble Shooting - 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 MSF 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):

SNDDST TYPE(*LMSG)     TOINTNET((Charlie.Brown@gmail.com))     DSTD('Hello via SNDDST')     LONGMSG('Hi Charlie, you are receiving this message thanks to command SNDDST.')     CFMDEL(*YES) USRID(*CURRENT)     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 - 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:

• Recommendations and guidelines for using CCSIDs
• Language identifiers and associated default CCSIDs
• Default system values for national language versions

See also FAQ number 15.

4. Mail Server Config - How to configure TCP/SMTP/POP to send and to receive mail

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

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

Look at the following documents:

1. Configuring MSF/SMTP on the IBM i by IBM i Support
2. Change SMTP Attributes (CHGSMTPA) by IBM i Knowledge Center
3. Sending e-mail through a router or firewall or hub by IBM i Knowledge Center

About parameter MAILROUTER

Here is an excerpt from the 7.1 Memo to Users regarding this change.:
5.6.3 MAILROUTER feature changes

This feature can be used either by using the Change SMTP attributes (CHGSMTPA) command parameter MAILROUTER or through the IBM i Navigator SMTP server properties general tab under Mail router. The MAILROUTER feature before i 7.1 would in some instances, forward all mail to the mail router even if the e-mail address could be resolved. In i 7.1, MAILROUTER correctly forwards to the mail router only when the e-mail address does not resolve.

The FWDMAILHUB feature was added in i 6.1 that allowed the forwarding of e-mail to a single address. This feature can be used either by using the CHGSMTPA parameter FWDMAILHUB or through the IBM i Navigator SMTP server properties general tab under Forwarding mailhub domain. FWDMAILHUB always forwards the e-mail and does not attempt a resolve. MAILROUTER only supports A and AAAA records, while FWDMAILHUB supports MX, CNAME, AAAA, and A.

For those customers that expect all e-mail to be forwarded to their mail router then copy the value of MAILROUTER to FWDMAILHUB, and set MAILROUTER to *NONE as this is a mail hub. For those that expect only e-mail that cannot be resolved to be forwarded to their mail router leave the configuration as-is. Customers that want the SMTP server to resolve an address before forwarding to the mail hub, must use MAILROUTER, as FWDMAILHUB does not resolve the address. Changing these values may require a SMTP server restart.

6. Mail Server Config - 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 V7R1or subsequent, the IP address or the name of the mail server should not be specified in parameter MAILROUTER, it should instead be specified in parameter FWDMAILHUB. 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. Mail Server Config - Securing e-mail

Look at the following document:

1. Securing e-mail by IBM i Knowledge Center

8. Mail Server Config - 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

9. Mail Server Config - 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.

10. Mail Server Config - How can I have SMTP sending the outgoing mail from a port other than port 25?

Run command
ADDENVVAR ENVVAR(QIBM_SMTP_SERVER_PORT) VALUE('xxx') LEVEL(*SYS)
where xxx is the number of the port you want to use.
You may however need a PTF:

• For release 6.1 see this page.
• For release 7.1 see this page.

11. Mail Server Config - How can I implement E-Mail Authentication

IBMi documents on SMTP Client Authentication:

	April 6, 2009	Configuring SMTP Authentication
	November 15, 2017	Authenticating e-mail for local and relay
	September 26, 2018	How To Configure the SMTP Client To Use SMTP Authentication with a SMTP Relay

12. Mail Server Config - How to enablel SSL (Secure Socket Layer) on the SMTP server

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

13. Mail Filters - 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 challenge 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 JSmith@mydomain.com) where "mydomain.com" 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 rzkh.de) (178.249.3.47) by vivaldi29.register.it with SMTP; 7 Jan 2014 23:01:21 -0000
   Received-SPF: none (vivaldi10.register.it: domain at MYDOMAIN.COM does not designate permitted sender hosts)
   These messages tell that the message was sent from the mail server with IP 178.249.3.47 which is not designated as a permitted sender by domain "mydomain.com". 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 "mydomain.com" 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:178.249.3.47 ~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 rzkh.de) (178.249.3.47) by vivaldi25.register.it with SMTP; 7 Jan 2014 23:28:13 -0000
   Received-SPF: pass (vivaldi25.register.it: SPF record at MYDOMAIN.COM designates 178.249.3.47 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:

• Email spoofing - Wikipedia, the free encyclopedia
• Sender Policy Framework - Wikipedia, the free encyclopedia
• Sender Policy Framework - Project Overview
• Sender Policy Framework - SPF Record Syntax
• Sender Policy Framework (SPF) for Authorizing Use of Domains in E-Mail, Version 1

14. SMS - 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.

15. Spooled files - 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)

16. CCSID - 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.

17. IMAGES - 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="http://www.easy400.net/mmail/image/0002378.gif" > .

18. Addressees 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.

19. Character set - 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.

20. Spooled Files - 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.

21. CGIDEV2 & MMAIL - 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 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.

22. Trouble Shooting - 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 unsupported character(s).

1. 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.
2. For a more drastic decision, execute command MMAIL/VLDEMLADDR VALIDATE(*NO) to disable e-mail address validation.

23. Message log - How can I maintain a log of MMAIL outbound e-mail messages?

You have two ways:

1. Provide a setup that would send a blank copy of all messages to a given "secret" e-mail address. See this page.
2. Write a user exit program receiving - for each outgoing message - information that can be used to maintain a log. See "service program Exit points" at this page.

MMAIL provides a default user exit program and a log display facility, see this page.

24. Mail Server Config - How do I change the SMTP port 25 to another port number?

Read the following IBM Support document:

• Binding the IBM i SMTP Server to a Different Port

25. Mail Server Config - My IBM i SMTP relays its outgoing mail to another mail server, which is listening on a port other than port 25 (example: port 465). How do I tell my IBM i SMTP that the mail server is listening on this other port?

Read the following IBM Support document:

• How to Configure SMTP to Send Mail to a Mail Router that Listens on a Port Other Than Port 25 (V7R2 and V7R3).

26. Mail Server Config - Example of relaying authenticated mail to a service provider mail server (Italian language!)

See Roberto Bizzozero's blog document Un tunnel per la posta.

27. Trouble shooting - How to test MMAIL-generated outgoing messages

A solution to the email testing problem that is both elegant and practical is offered by so-called echo mailers.
A message sent to an echo mailer will be bounced or echoed back to where it originated.
After some system information, you will find your complete original email with all header lines in the body, making it easy to spot possible errors or oddities.
Vienna University provides a nice echo mailer at echo@univie.ac.at . Answers are limited to one every two minutes to prevent abuse.

This is how you test a MMAIL message. Assume that

• the domain name of your IBM i is MYCOMPANY.COM
• you own a mail box named JSMITH@MYCOMPANY.COM

We suggest that your IBM i sends the MMAIL message to be tested as follow:

Subject  . . . . . . . . . . . .  'Test MMAIL message'
Sender's name  . . . . . . . . .  'John Smith'
Sender's e-mail address  . . . .  'JSMITH@MYCOMPANY.COM'
Recipients . . . . . . . . . . .   *TO
   name  . . . . . . . . . . . .    'Vienna Echo'
   e-mail address  . . . . . . .    'echo@univie.ac.at'
... ... ...

As soon as your message is received, you will get a feedback message in mailbox JSMITH@MYCOMPANY.COM .

28. Trouble shooting - What to do if MMAIL messages are discarded by the receiver's mailer

If the receiver's mail-box is on ...

1. GMAIL - The receiver should add the sender to his contacts
2. OUTLOOK - The receiver should add the sender domain (or e-mail address) to the Safe senders (View full settings->Junk email->Safe senderds)

29. Spooled Files -

I have a spooled file containing some URL's (example: https://www.easy400.net ). I want to send an e-mail message attaching a PDF converted from that spooled file, and I need WEB links be generated for those URL's in the PDF.
My question is: Which of the spooled file-to-PDF conversion tools available in MMAIL (see command MMAIL/CVTTOPDF) can provide those URL links?

Answer: Providing such link is not a conversion tool job, that is usually done by the client PDF reader (example: Adobe). In Adobe such links are set at document load time and are available as soon as the document completes its loading. They are not underlined, but they do work when you click them.

30. How to have your MMAIL messages received by GMAIL -

You do not need to do anything with MMAIL, nor your need to enable your IBM i SMTP server for outgoing messages authentication.
The solution is provided in link https://support.google.com/a/answer/10685031#more-senders .

This is what I did to have GMAIL accepting mail messages sent from my domain easy400.eu :

1. I entered the site of the Service provider (in my case, Register.it) where my domain easy400.eu is registered
2. I selected DNS CONFIGURATION for that domain, then I selected "Advanced Management"
3. I added a TXT record for my domain easy400.eu specifying the following (double quotes included)
      "v=spf1 include:_spf.google.com ~all"

It worked!!!

31. What if you have problems connecting with a remote POP3 -

Because of increasing security needs, about all mail servers add more and more controls on accessing mail received by their accounts. So, it very common that when you try to connect to a remote mail account via POP3, your request is rejected.
A simple way to bypass this problem is to define an internet user on your IBM i and ask the remote mail server account to forward its incoming mail to this IBM i mail account.
See this link for detailed instructions.