This article is meant to describe each IBM i email solution available from BVSTools, their use, their benefits as well as any other information that may be important.  We will continuously update this article with new and additional information when we can and try to keep this is up to date as possible.

You will find that this article is divided into different sections depending on your particular email requirements.  If you don't see an option that helps, contact us and we're happy to help:  

• Google/GMail/G Suite
• Microsoft Office 365 (O365)
• Generic section for everyone else that may be using either a different cloud host or internal mail server.
• Benefits of using MAILTOOL over SNDDST, SNDSMTPEMM or other 3rd party products that simply "wrap" the QtmmSendMail API

With each of these solutions we try to be as complete as possible in their use and setup.  There will be cases where you will need to import Certificate Authorities (CAs) in order for your IBM i to communicate with any of these servers over SSL or TLS.  Contact us for specific assistance with this as we have all of the CAs required as well as instructions on how to apply them using Digital Certificate Manager (DCM).

Google/GMail/G Suite

Sending emails from your IBM i when your email provider is GMail, whether for personal or business, was the first solution we created.  The main reason was that the IBM SMTP server/MSF simply couldn't communicate with the GMail servers since they required authentication at the very least.  The connection also required SSL or TLS communications.  This is where the MAILTOOL Plus Addon was born.

When sending emails from your IBM i you will need to send along authentication for the account that is sending the email.  If not that would obviously be a huge security hole as anyone could send an email that is "from" any address they choose.

When sending email using MAILTOOL Plus you can send along the authentication information along with the command, with the API, or using Configuration Files.  

This authentication information can be sent in one of two forms when using Google's email server: Standard Authentication or OAuth 2.0.

Google Using Standard Authentication

*NOTE: Google is dropping this type of authentication for @gmail.com addresses (but not yet Google Workspace accounts) on May 30th, 2022.  See this article for more information.

Requrirements:

• eMail Tool (MAILTOOL)
• MAILTOOL Plus - MAILTOOL Plus is built into MAILTOOL and while it doesn't require a separate download, it does require separate licensing.

The MAILTOOL command, along with the MAILTOOL API allows you to set the required Authentication and Secure Transport (ie, SSL or TLS) information right in the command, ILE function call or from a Configuration File.  Examples of each follows:

Using the command:

MAILTOOL TOADDR(MauriceMoss@Reyhnholm.com) FROMADDR(bvstone@bvstools.com) 
SUBJECT('Info for Weekend') 
MESSAGE('Hi, are you and Roy making it this weekend?') 
SENDWITH(*MAILTOOL) MAILRTR(SMTP.GMAIL.COM) USERTR(*ONLY)  
SSL(*TLS) PORT(587) 
AUTHUSER(bvstone@bvstools.com) AUTHPW(<password>) DEBUG(*YES)         

As you can see, the User and Password associated with the account (that is for the From address) is entered on the command.  The password itself in the command is set up as a password and will not show up in the job log, and if you use F9 to restore the command keep in mind you will need to re-enter the password on the command.

The second option is using a Configuration File to store the information specific to an account.  This makes the command much smaller and also makes updating any parameters easier as you only will need to update the configuration file, not all of the commands or programs using MAILTOOL.

MAILTOOL TOADDR(MauriceMoss@Reyhnholm.com) SUBJECT('Info for Weekend') 
MESSAGE('Hi, are you and Roy making it this weekend?') 
CONFIG('/bvstools/bvstools_test2.json')                                                                             

The contents of the configuration file are as follows:

{
	"variables": [
	{
		"name":"from_email",
		"default":"bvstone@bvstools.com"
	},
	{
		"name":"send_with_server_type",
		"default":"*MAILTOOL"
	},
	{
		"name":"mail_router",
		"default":"smtp.gmail.com"
	},
	{
		"name":"use_mail_router",
		"default":"*ONLY"
	},
	{
		"name":"use_ssl",
		"default":"*TLS"
	},
	{
		"name":"smtp_port",
		"default":"587"
	},
	{
		"name":"smtp_auth_user",
		"default":"bvstone@bvstools.com"
	},
	{
		"name":"smtp_auth_password",
		"default":"passsword"
	}	
  ]
}

When using a Configuration File, specify the full path and file name of a configuration file to use when sending this email.   *DFT will use the default configuration file (which starts with /bvstools/mailtool/config/<userid>/defaults.json, and if that file doesn't exist  /bvstools/mailtool/config/defaults.json will be used).  

As you can see, setting up configuration files makes things much cleaner and easier.

MAILTOOL also has ILE Functions that you can call from any ILE program.  This is a nice feature as using QCMDEXC isn't always the cleanest.  

And example program follow:

     H DFTACTGRP(*NO) BNDDIR('BVSTOOLS')
      ****************************************************************
      * Prototypes                                                   *
      ****************************************************************
      /COPY QCOPYSRC,P.MAILTOOL
      ****************************************************************
     D ErrMsg          S            256    INZ
     D rc              S             10i 0
      ****************************************************************
      /free

       if (mailtool_init() >= 0);
         rc = mailtool_addTORecipient('MauriceMoss@Reyhnholm.com');
         rc = mailtool_setValue('from_email':'bvstone@bvstools.com');
         rc = mailtool_setValue('subject':'Info for Weekend');
         rc = mailtool_setValue('message':
                                 'Hi, are you and Roy making it this weekend?');
         rc = mailtool_setValue('send_with_server_type':'*MAILTOOL');
         rc = mailtool_setValue('use_mail_router':'*ONLY');
         rc = mailtool_setValue('mail_router':'smtp.gmail.com');
         rc = mailtool_setValue('use_ssl':'*YES');
         rc = mailtool_setValue('smtp_port':'465');
         rc = mailtool_setValue('smtp_auth_user':'bvstone@bvstools.com');
         rc = mailtool_setValue('smtp_auth_password':'password');
         rc = mailtool_sendMail(errMsg);
       endif;

       *INLR = *ON; 

We can also clean this program up a lot by using a configuration file:

H DFTACTGRP(*NO) BNDDIR('BVSTOOLS')
 ****************************************************************
 * Prototypes                                                   *
 ****************************************************************
 /COPY QCOPYSRC,P.MAILTOOL
 ****************************************************************
D ErrMsg          S            256    INZ
D rc              S             10i 0
 ****************************************************************
 /free

  if (mailtool_init() >= 0);
    rc = mailtool_setValue('configuration_file':
                            '/bvstools/bvstools_test2.json');
    rc = mailtool_loadDefaults();
    rc = mailtool_addTORecipient('MauriceMoss@Reyhnholm.com ');
    rc = mailtool_setValue('subject':'Info for Weekend');
    rc = mailtool_setValue('message':
                            'Hi, are you and Roy making it this weekend?');
    rc = mailtool_sendMail(errMsg);
  endif;

  *INLR = *ON;

Google Using OAuth 2.0

Requrirements:

• eMail Tool (MAILTOOL)
• MAILTOOL Plus - MAILTOOL Plus is built into MAILTOOL and while it doesn't require a separate download, it does require separate licensing.
• GreenTools for GSuite (Google Apps) Send EMail Addon (G4GSMAIL) - the G4GSMAIL addon as well as the Base G4G License Required
• Get URI (GETURI) - GETURI is bundled with G4G , so while this isn't a separate download and install, it will be a separate license.  GETURI is used for the background communications between your IBM i and the Google  Servers.

If you like to keep security tighter in your shop then this option is most likely for you.  Google's email servers allow the use of OAuth 2.0 authentication which means that after a quick setup you can start sending emails using this method and not have to worry about passing along the user and password with every call, either in the command, function or using Configuration Files

The first step you will need to perform once MAILTOOL is installed is to download and install GreenTools for GSuite (Google Apps).  Next, you will need to use the G4G Register Service (G4GREGSVC) command using the service option of *G4GSMAIL to register each account you will be sending email with.  This setup is required before sending email as well as any time the user of the account changes their password.  What this command does is set up the initial OAuth 2.0 configuration.

Once that is done your MAILTOOL command will need to use the value *G4G_XOAUTH2 as the Authentication User (AUTHUSER) parameter:

MAILTOOL TOADDR(MauriceMoss@Reyhnholm.com) 
FROMADDR(bvstone@bvstools.com) 
SUBJECT('Info for Weekend') 
MESSAGE('Hi, are you and Roy making it this weekend?') 
MSGID(*NONE) SENDWITH(*G4GSMAIL)

This option can also be used when using the MAILTOOL ILE Functions.  Finally, these options can be used in a configuration file as well.  The following would be an example configuration file you can use to send email using OAuth 2.0 and Gmail from your IBM i:

{
	"variables": [
	{
		"name":"from_email",
		"default":"bvstone@bvstools.com"
	},  
	{
		"name":"send_with_server_type",
		"default":"*G4GSMAIL"
	}
	]
}

The program that would use this configuration file and the MAILTOOL ILE Functions would be exactly the same as the previous example.

Microsoft Office 365

Sending emails from your IBM i when your email provider is Microsoft Office 365 gives you three options on sending email:

• Using Microsoft's SMTP Server
• Using Microsoft's SMTP Server and OAuth 2.0 (XOAUTH2)
• Using Microsoft's eMail API using OAuth 2.0

These two options have different requirements and different security options.  For example, Microsoft's SMTP server doesn't allow OAuth 2.0 connections like Google does.  But, their API requires the use of OAuth 2.0.  Because of that, we created a separate add on that can be either incorporated with MAILTOOL, or used on it's own.

So lets take a look at both of the options.

Microsoft's SMTP Server

Requirements:

• eMail Tool (MAILTOOL) 
• MAILTOOL Plus - MAILTOOL Plus is built into MAILTOOL and while it doesn't require a separate download, it does require separate licensing.

The MAILTOOL command allows you to set the required authentication, secure transport method (ie, SSL or TLS), as well as other settings required when using Microsoft's SMTP server in the MAILTOOL command, in the ILE function, or using Configuration Files.

An example of using the MAILTOOL command along with MAILTOOL Plus is as follows:

MAILTOOL TOADDR(MauriceMoss@Reyhnholm.com) 
FROMADDR(bvstone@bvstools.onmicrosoft.com) 
SUBJECT('Info for Weekend') 
MESSAGE('Hi, are you and Roy making it this weekend?') 
SENDWITH(*MAILTOOL) MAILRTR(SMTP.OFFICE365.COM) 
USERTR(*ONLY) MXLOOKUP(*NO) SSL(*TLS) PORT(587) 
AUTHUSER(bvstone@bvstools.onmicrosoft.com) 
AUTHPW(<password>)                                                             

As you can see, this example uses port 587 of Microsoft's email server which requires TLS.  Also, the AUTHUSER and AUTHPW parameters specified should match the From Address that is used on the email.  Again, this is for security so others can't user your account.  It is possible to set up an authorization list in Office 365 email to specify which "From" addresses can use your account.

If we were instead to use a Configuration File to send the email, the command would be shortened to the following example:

MAILTOOL TOADDR(MauriceMoss@Reyhnholm.com) 
SUBJECT('Info for Weekend') 
MESSAGE('Hi, are you and Roy making it this weekend?') CONFIG('/bvstools/bvstone_office365_smtp.json')                          

The contents of the Configuration File that we are using is as follows:

{
	"variables": [
  {
		"name":"from_email",
		"default":"bvstone@bvstools.onmicrosoft.com"
	},
	{
		"name":"from_name",
		"default":"Brad Stone @ Office 365"
	},
	{
		"name":"send_with_server_type",
		"default":"*MAILTOOL"
	},
	{
		"name":"mail_router",
		"default":"smtp.office365.com"
	},
	{
		"name":"use_mail_router",
		"default":"*ONLY"
	},
	{
		"name":"perform_mx_lookup",
		"default":"*NO"
	},
	{
		"name":"use_ssl",
		"default":"*TLS"
	},
	{
		"name":"smtp_port",
		"default":"587"
	},
	{
		"name":"smtp_auth_user",
		"default":"bvstone@bvstools.onmicrosoft.com"
	},
	{
		"name":"smtp_auth_password",
		"default":"<password>"
	}	
  ]
}

So, as you can see, using a Configuration File not only cleans up the command or ILE calls, but if this information ever changes, such as your password, you will only need to change it in one place.

You can also use the ILE Functions included in MAILTOOL to send emails directly from an ILE program.

An example of that program is as follows:

H DFTACTGRP(*NO) BNDDIR('BVSTOOLS')
 ****************************************************************
 * Prototypes                                                   *
 ****************************************************************
 /COPY QCOPYSRC,P.MAILTOOL
 ****************************************************************
D ErrMsg          S            256    INZ
D rc              S             10i 0
 ****************************************************************
 /free

  if (mailtool_init() >= 0);
    rc = mailtool_addTORecipient('MauriceMoss@Reyhnholm.com');
    rc = mailtool_setValue('from_email':
                            'bvstone@bvstools.onmicrosoft.com');
    rc = mailtool_setValue('subject':'Info for Weekend');
    rc = mailtool_setValue('message':
                            'Hi, are you and Roy making it this weekend?');
    rc = mailtool_setValue('send_with_server_type':'*MAILTOOL');
    rc = mailtool_setValue('use_mail_router':'*ONLY');
    rc = mailtool_setValue('mail_router':'smtp.office365.com');
    rc = mailtool_setValue('use_ssl':'*TLS');
    rc = mailtool_setValue('smtp_port':'587');
    rc = mailtool_setValue('smtp_auth_user':
                            'bvstone@bvstools.onmicrosoft.com');
    rc = mailtool_setValue('smtp_auth_password':'<password>');
    rc = mailtool_sendMail(errMsg);
  endif;

  *INLR = *ON;

And finally, if we wish to use the Configuration File with our program, it would be modified to the following:

H DFTACTGRP(*NO) BNDDIR('BVSTOOLS')
 ****************************************************************
 * Prototypes                                                   *
 ****************************************************************
 /COPY QCOPYSRC,P.MAILTOOL
 ****************************************************************
D ErrMsg          S            256    INZ
D rc              S             10i 0
 ****************************************************************
 /free

  if (mailtool_init() >= 0);
    rc = mailtool_setValue('configuration_file':
                            '/bvstools/bvstone_office365_smtp.json');
    rc = mailtool_loadDefaults();
    rc = mailtool_addTORecipient('MauriceMoss@Reyhnholm.com');
    rc = mailtool_setValue('subject':'Info for Weekend');
    rc = mailtool_setValue('message':
                            'Hi, are you and Roy making it this weekend?');
    rc = mailtool_sendMail(errMsg);
  endif;

  *INLR = *ON;

The only downside that I have found using Microsoft's SMTP server is that when the email is sent, a copy is not placed into your "sent" folder (like it is when using Google).  But, if you choose to go the route of the Microsoft Email API, that problem is solved.

Microsoft's eMail Server Using OAuth 2.0 (XOUATH2)

Requirements:

• eMail Tool (MAILTOOL) - MAILTOOL is required to send emails using this method. 
• MAILTOOL Plus - MAILTOOL Plus is built into MAILTOOL and while it doesn't require a separate download, it does require separate licensing.
• GreenTools for Microsoft Apps (G4MS) - The base G4MS product and G4MSMAIL addon is required for communication with Microsoft's Email API.
• Get URI (GETURI) - GETURI is bundled with G4MS, so while this isn't a separate download and install, it will be a separate license.  GETURI is used for the background communications between your IBM i and the Microsoft eMail API.

Recently Microsoft has added the XOAUTH2 method to their SMTP servers (took long enough).  

This method is similar to use MAILTOOL Plus, except that for the AUTHUSER parameter you will specify *G4MS_XOAUTH2.

For each email account you wish to send from you need to use the G4MSREGSVC command to register the *OUTLOOKSMTP service.  What this does is set up the OAuth 2.0 settings for the account.  Once this is done you won't have to worry about it until the user changes their password.  In that case you'll need to run it again to reset the account on your IBM i.  We have even set up a YouTube video showing how easy this process is.

MAILTOOL TOADDR(MauriceMoss@Reyhnholm.com) 
FROMADDR(bvstone@bvstools.onmicrosoft.com) 
SUBJECT('Info for Weekend') 
MESSAGE('Hi, are you and Roy making it this weekend?') 
SENDWITH(*MAILTOOL) MAILRTR(OFFICE.OFFICE365.COM) 
USERTR(*ONLY) MXLOOKUP(*NO) SSL(*TLS) PORT(587) 
AUTHUSER(*G4MS_XOAUTH2)                                      

Examples using the ILE functions and config files will be similar to the previous MAILTOOL Plus examples.

Microsoft's eMail API Using OAuth 2.0

Requirements:

• eMail Tool (MAILTOOL) - Optional 
• GreenTools for Microsoft Apps (G4MS) G4MSMAIL Addon - The base G4MS product and G4MSMAIL addon is required for communication with Microsoft's Email API.
• Get URI (GETURI) - GETURI is bundled with G4MS, so while this isn't a separate download and install, it will be a separate license.  GETURI is used for the background communications between your IBM i and the Microsoft eMail API.

When we heard the Microsoft's SMTP server didn't support OAuth 2.0 like Google we knew there had to be another way.  So, we asked around and were told by Microsoft themselves that they had no plan on updating their SMTP servers to use OAuth 2.0 and that instead we should use the eMail API they offer.  *UPDATE, they have just added this option.  See the above example.

Because we already had our GreenTools for Microsoft Apps, as well as plugins for OneDrive, we decided to add an option to send email using their API.

The G4MSMAIL addon was created for this very purpose.  This addon includes ILE functions similar to those of the MAILTOOL Plus ILE functions you can use to send emails from ILE programs.

For each email account you wish to send from you need to use the G4MSREGSVC command to register the *OFFICE365SMTP service.  What this does is set up the OAuth 2.0 settings.  Once this is done you won't have to worry about it until the user changes their password.  In that case you'll need to run it again to reset the account on your IBM i.  We have even set up a YouTube video showing how easy this process is.

An example program is as follows:

H DFTACTGRP(*NO) ACTGRP('G4MS') BNDDIR('BVSTOOLS')
 ****************************************************************
 * Imports
 ****************************************************************
 /COPY QCOPYSRC,P.G4MSMAIL
 ****************************************************************
D rc              S             10i 0
D errorMsg        S            256
 ****************************************************************
 /free

  rc = g4msmail_setValue('id':'bvstone@bvstools.onmicrosoft.com');
  rc = g4msmail_setValue('subject':'Info for Weekend');
  rc = g4msmail_setValue('message':
                            'Hi, are you and Roy making it this weekend?');
  rc = g4msmail_addRecipient('MauriceMoss@Reyhnholm.com');
  rc = g4msmail_sendMail(g4ms_uniqueID:errorMsg);

  if (rc < 0);
    g4msmail_dumpSettings(); // This will make a json file with settings and values
  endif;

  *INLR = *ON;
 /end-free

As you can see, compared to using MAILTOOL Plus there are quite a few less settings that you need to use.  That is because the connection information for each account is taken care of in the background using OAuth 2.0.

A complete listing of the available ILE functions is available in the G4MSMAIL documenation.

Of course, as with MAILTOOL Plus you also can use configuration files with the G4MSMAIL addon as shown in the following example:

H DFTACTGRP(*NO) ACTGRP('G4MS') BNDDIR('G4MS')
 ****************************************************************
 * Imports
 ****************************************************************
 /COPY QCOPYSRC,P.G4MSMAIL
 ****************************************************************
D rc              S             10i 0
D errorMsg        S            256
 ****************************************************************
 /free

  rc = g4msmail_init();
  rc = g4msmail_setValue('configuration_file':'*DFT');
  rc = g4msmail_loadDefaults();

  if (rc < 0);
    g4msmail_dumpSettings(); // This will make a json file with settings and values
  else;

    rc = g4msmail_setValue('id':'bvstone@bvstools.onmicrosoft.com');
    rc = g4msmail_setValue('subject':'Info for Weekend');
    rc = g4msmail_setValue('message':
                            'Hi, are you and Roy making it this weekend?');
    rc = g4msmail_addRecipient('MauriceMoss@Reyhnholm.com');
    rc = g4msmail_sendMail(g4ms_uniqueID:errorMsg);

    if (rc < 0);
      g4msmail_dumpSettings(); // This will make a json file with settings and values
    endif;

  endif;

  *INLR = *ON;

The configuration file to use when the g4msmail_loadDefaults() function is called can be a fully qualified file name or the value of *DFT.  *DFT, as shown in this example will attempt to use a configuration file named /bvstools/g4ms/config/<userid>/defaults.json where <userid> is the user ID of the person running the command.  If that file is not found it will then look for a generic configuration file name in the IFS named /bvstools/g4ms/config/defaults.json.

The last option is using the MAILTOOL command interface to send emails using the Microsoft Office 365 eMail API.  This requires the licensing of MAILTOOL as well as the other requirements (note:  MAILTOOL Plus is not required for this).

Instead of *IBMSMTP or *MAILTOOL for the Send With (SENDWITH) parameter, we simply specify *G4MSMAIL as shown in this example:

MAILTOOL TOADDR(MauriceMoss@Reyhnholm.com) 
FROMADDR(bvstone@bvstools.onmicrosoft.com) 
SUBJECT('Info for Weekend') 
MESSAGE('Hi, are you and Roy making it this weekend?')
SENDWITH(*G4MSMAIL)

So, if your company is choosing to go with Office 365 for email you have many options to choose from.

Everyone Else

• eMail Tool (MAILTOOL) 
• MAILTOOL Plus - (Optional) MAILTOOL Plus is built into MAILTOOL and while it doesn't require a separate download, it does require separate licensing.

Sending emails using other in house or cloud based email systems will either require only MAILTOOL, or MAILTOOL and MAILTOOL Plus.  Please feel free to contact us with your specifications and we're more than happy to help figure out what will be needed in this case.

The benefits of using our MAILTOOL product over others are:

• Command and ILE Interfaces available which means easily sending email from your programs.
• The ability to specify a "From" and/or "Reply To" email address!
• No 400 byte or less message limit as with SNDDST or SNDSMTPEMM
• ​Easily add attachments of any type from the IFS to outgoing emails.
• Easy setup!  No confusing or obscure setup instructions, directory entries, SMTP users, aliases or host tables.  All you need is TCPIP, a connection to the internet and you're done!
• Easily send group emails with Distribution Lists
• The ability to completely bypass the IBM SMTP system all together (using MAILTOOL Plus or other Addons)
• Email Logging - Each email that is sent out is logged with a delivery status.  We also track each of the recipients for each email as well as the attachment(s) sent along with each email.
• Superior debugging (when using MAILTOOL Plus) - Bypassing the IBM SMTP server means that we can fully debug and track down sometimes hard to find problems.  Even the Trace TCP/IP Application (TRCTCPAPP) command won't be this detailed!
• Resend Emails - When emails are sent using MAILTOOL Plus or another addon, those emails are logged and you have the ability to resend them one by one, or as a batch (ie, all unsent emails at once).
• Save Emails - Save emails that are sent out at a global, user or individual email level.
• Both Text and HTML email support
• The ability to use an IFS stream file as the body of the email (either text or html).
• The ability to use Configuration Files at the system, User, or individual email Level.  This means that should any of the settings (such as your password) is changed you only need to update it in the configuration file that is used.
• The ability to add a Footer to each email sent using an IFS stream file.
• No external "helper" PC system required.  100% IBM i native!
• Compatible with Google/Gmail/G Suite, Outlook.com, Microsoft Office 365 as well as most other SMTP servers and relays. No tricks, gimmicks or relays needed.  MAILTOOL is set up just like a PC or mobile device with the appropriate outgoing mail router information and well as the proper authentication.
• Ability to use SSL, TLS or OAuth 2.0 authentication.  (OAuth 2.0 only available with Google or Microsoft Office 365).
• The ability to turn off "Strict SSL" settings.  This means no importing Certificate Authorities (CAs) unless you want to.
• The ability to specify multiple email routers/relays to make sure emails are sent when they need to be.
• Compatible with the IBM SMTP server and MSF
• Superior Product Support - BVSTools has proven over the past 20+ years and working with thousands of customers all over the world and many different SMTP servers to have superior support for our products.  We feel functionality is important, but just as important is making sure that emails and phone calls for support are answered as quickly as possible.  During working hours you'll often get a response in less than 30 minutes.

We do strongly recommend MAILTOOL Plus.  This is because it bypasses the IBM SMTP server (which is an IBM product) and puts all the support for sending email within our software.  

If you are using just the base MAILTOOL Product emails are sent using IBM's email system.  If you encounter issues with it, we can help, but can't promise we can figure things out since we don't technically support IBM's SMTP system.

Again, because things can vary, we are happy to help you decide what is needed on a case by base basis.  So, feel free to Contact Us at BVSTools with any questions.