If you’re creating NAB forms or custom apps that send emails using the VVMAIL service program module, as demonstrated in the “Send Email” utility nested inside the Examples app, you can set up a back-end routine to globally intercept all outbound messages using an exit program. The exit program you create can be used to override the mechanism through which emails are sent, or to store pertinent details in a custom “outbound email log” for auditing purposes.
To set up the exit program, start by making a copy of the RPG source member EXEXITPGMM in QRPGLESRC of your Valence library, renaming it to whatever name suits you (i.e., VXMAILEXIT). Once specified as an email exit program in Portal Admin > Settings, this program will be called just prior to each email sent from your apps via the back-end vvMail_send() procedure. For an example of this procedure call in action, have a look at the EXEMAIL example RPG source.
You’ll notice that the source code for the exit program is quite simple. You have two simple entry parameters to work with:
- The VVMAIL data structure with all the pertinent email values (vvMail.to, vvMail.from, vvMail.subject, vvMail.body, etc)
- A one-character BYPASS indicator that tells VVMAIL what to do after your exit program completes via one of the following three values:
- ‘1’ – Bypass the standard email send logic in VVMAIL. This means your exit program is handling the email using its own routine or external call. The program calling vvMail_send() will get back a success value of *ON.
- ‘E’ – Bypass the standard email send login VVMAIL and return a success value of *OFF as a signal to the program calling vvMail_send() that an error occurred. In such cases you may want to send a JSON response from your exit program directly to the app.
- ‘0’ – Continue processing as normal. VVMAIL will proceed with sending the email as normal, using the server settings specified in Portal Admin > Settings > IBM i Settings > Email, or via overrides passed via VVMAIL data structure fields (vvMail.host, vvMail.port, vvMail.authType, vvMail.authUser and vvMail.authPwd).
Some common uses of the VVMAIL exit routine include:
- Validating that all elements of the email meets requirements… The program should return a BYPASS value of ‘E’ if any exceptions are encountered.
- Supersede the standard Valence email send routine… In cases where you have your own email program, pull in the appropriate VVMAIL data structure fields (vvMail.to, vvMail.from, vvMail.subject, vvMail.body, etc) and pass them along to your routine. The program should return a BYPASS value of ‘1’ to skip the standard send.
- Log email data in a custom outbound email log file… Your program should take the pertinent appropriate VVMAIL data structure fields (vvMail.to, vvMail.from, vvMail.subject, vvMail.body, etc) and write them to your custom log file. The program should return a BYPASS value of ‘0’ to proceed with the email send, unless you’re also using your own email send routine as described in (2) above.
Once compiled, your exit program name should be specified in Portal Admin > Settings > Exit Programs > “VVMAIL, pre-processing”, as depicted here:
