There may be the need to process through local programs the incoming mail for a given user. Examples could be:

• purge a distribution list by getting back non-delivery messages
• getting feedback messages in a marketing survey
• receiving orders by mail
• etc.

In concepts, such developments should be very easy, as all the tools needed (database files, stream files, programming subprocedures) are already available within AMailer.

To make it feasible, it takes a sample program that you may easily understand and customize to your needs. This program is explained hereafter.

The sample program and the command to call it are available in library MMAIL. However, it must be understood that the customization of those two pieces must not be done in library MMAIL. In order to preserve your work from installing a future release of MMAIL, you should copy the source of the command and the source of the program in a library of yours, and create the command and the program in your library.

The command is called PRCUSRMAIL and shows as follow:

Figure 1 - Command PRCUSRMAIL

This command processes the incoming mail for a given user.
Incoming mail for the given user is received. During the receiving phase

1. Messages are saved as stream files
   /amailer/xxx/nnn
2. Message bodies are extracted and saved as stream files
   /amailer/xxx/Bodies/nnn
3. Message attachments are extracted and saved as stream files
   /amailer/xxx/Attachments/nnn

• xxx is a 10 char string that stays for the username.
  Relationships between usernames and such strings are found in file QGPL/AMUSERS.
• nnn is a 30 char string containing the same value as the name of the mother MIME stream file.

Meaning of command parameters:

• 'user ID' (parameter USERID)
  Identifier of the user whose incoming mail must be processed. Maximum length is 30 char. Case sensitive, use quotes (').
  The user must have already be defined to AMailer, see Define users.
• Receive new mail (parameter RECEIVE)
  Whether the latest incoming mail for this user should be received now. One of the following:
  • *NO - Do not receive the latest incoming mail for this user. Just process the incoming mail for this user already received by AMailer and not yet processed.
  • *YES - Receive the latest incoming mail for this user. Then process all the incoming mail of this user not yet processed.
• Purge after days (parameter PURGEAFTER)
  Number of days since mail was processed, before it is purged from local (IBM i) data. Enter *NO to avoid mail purging from local (IBM i) data.
  NOTE. Messages received with PRCUSRMAIL are removed from the POP server before they are purged from local (IBM i) data. This is done to make sure that no incoming message can be processed twice by PRCUSRMAIL.
• Display mail messages (parameter DSPMSG)
  Whether the stream files of the new mail messages should be displayed. Stream file display is performed via command DSPF (no message editing performed) only if the command runs in interactive mode.
• Pgm to process mail messages (parameter PRCMSG)
  You may specify the qualified name of an user program intended to read and process each new mail message stream file.
  This user program receives a single input parameter, char 512, containing the path and the name of the mail message stream file.
• Display msg bodies (parameter DSPBDY)
  Whether the bodies of the new mail messages should be displayed. Stream file display is performed via command DSPF (no body editing performed) only if the command runs in interactive mode.
• Pgm to process msg bodies (parameter PRCBDY)
  You may specify the qualified name of an user program intended to read and process the body of each new mail message.
  This user program receives a single input parameter, char 512, containing the path and the name of a message-body stream file.
• Message body format (parameter BDYFMT)
  The message body format that your message-body-processing program is expecting. Select one of the fo9llowing:
  • *HTML to process the message body in its original HTML format.
  • *TXT to process a temporary version of the message body converted to plain text.
    Processing plain text is usually easier than processing a HTML script.
• Display msg attachments (parameter DSPATC)
  Whether the attachments of the new mail messages should be displayed. Stream file display is performed via command DSPF (no attachment editing performed) only if the command runs in interactive mode.
• Pgm to process msg attachments (parameter PRCATC)
  You may specify the qualified name of an user program intended to read and process each attachment of each new mail message.
  This user program receives a single input parameter, char 512, containing the path and the name of an attachment stream file.

Command PRCUSRMAIL invokes program PRCUSRMAIL which does the following:

1. Mark as deleted the messages to be purged (only if PURGEDAYS is other than *NO)
   This is done in order to tell the POP server that these messages do not have to be retained any longer at the POP server site. This type of cleanup is performed in the next step.
2. Receive the new incoming messages addressed to this user (only if RECEIVE(*YES))
3. Process all the messages that have not yet been processed
   The process, to be locally customized, has control over the MIME file and the attachments of the message.
   Access to database file AMMAIL (mail control records) provides summary info about mail messages, such as
   • name of the MIME stream file
   • directory holding the message
   • timestamp when sent
   • sender's name and e-mail address
   • main recipient's name and e-mail address
   • subject
4. Purge all processed and expired messages (only if PURGEDAYS is other than *NO)
5. Extract and save as separate stream files the bodies and the attachments of the new messages received.
6. Display and/or process through user programs
   • the entire mail messages
   • the message bodies
   • the attachments of the messages

Suggested use of command PRCUSRMAIL

1. Copy the sources of command PRCUSRMAIL and RPG program PRCUSRMAIL ingto a library of yours
2. If needed, customize the command and/or the program to your needs
3. Write a small CL program that periodically calls command PRCUSRMAIL. Example:

   PGM DCL VAR(&MYLIB) TYPE(*CHAR) LEN(10) VALUE('MYLIB') MONMSG MSGID(CPF0000) LOOP: MMAIL/PRCUSRMAIL USERID('JSmith') RECEIVE(*YES) + PURGEAFTER(3) PRCMSG(*NONE) + PRCBDY(&MYLIB/MYPGM1) BDYFMT(*TXT) + PRCATC(&MYLIB/MYPGM2) DLYJOB DLY(1800) /* wait half an hour */ GOTO CMDLBL(LOOP) ENDPGM

4. Run a batch job calling this CL program

POP Trace
AMailer features a POP Trace facility.
This facility unveils the dialogs between AMailer and POP servers and may be useful to find out if anything goes wrong.

• The following POP Trace commands are available:

  POPTRC_STR	Start POP trace
  POPTRC_END	End POP trace
  POPTRC_CLR	Clear POP trace
  POPTRC_DSP	Display POP trace

Errors in retrieving POP3 e-mail messages
Should an e-mail messages available in a mail-box fail to be retrieved from POP3 MMAIL-message-retrieve-procedures POP3RtvMsg() or SSLPOP3RtvMsg,

• a warning message is sent both to user profile QSYSOPR and to the user profile running the POP3 message retrieve job
• a log record is written to file MMAILDATA/MSGRCVFAIL
• the retrieving job skips the retrieval of this message and goes on retrieving the next ones.