Introduction

The JITL MailInboxJob template can be used to read mail by job from a JS7 Agentcreate a job that reads a mail inbox.

• The job template makes use of the IMAP or POP3 protocol to read mail.
• The job template can be used to specify settings from different sources:
  • Connection Settings
    • This includes These include settings such as the IMAP/POP3 host, port etc.
    • It is recommended to use that the JS7 - Job Resources is used for this purpose as such settings tend to suggest the use of the same values for any mail inbox that should be read from the same mail server.
  • Mail Settings
    • Such These settings are specific for individual mail inboxes and include e.g. , for example, the folder of the mail inbox.
• The job template can be used with a JS7 - Credential Store.

• Display feature availability
  StartingFromRelease 2.1.1

Usage

When defining the job considereither:

• to invoke the Wizard that is available from the job properties Job Properties tab in the Configuration view and to select the JITL MailInboxJob and respective relevant arguments from the Wizard

or

• to specify the JITL job class and com.sos.jitl.jobs.mail.MailInboxJob Java class name , then and add arguments specifying what to send and where to send mail should be sent as explained from in the documentation below documentation.

Example

Download: jitlMailInboxJob_sample.workflow.json

You can use the job wizard like thisas shown here:

Explanation:

• Add an empty job from the instruction panel.
• Specify a name and a label for the job.
• Select an Agent.

In a next step invoke the job wizard that you find in the upper right corner of the job property Job Property editor. The wizard brings will bring up the following popup window:

...

Then hit the "Next" button to make the job wizard display the available arguments:

Explanation:

• Required arguments include the to argument to specify the recipient of mail. mail.store.protocol which specifies whether imap or pop3 should be used.
• All Any other arguments are optional provided that a job resource Job Resource is used that which specifies the connection details to your the mail server, see below. Otherwise individual settings such as the IMAP/POP3 host, IMAP/POP3 port etc. can have to be specified from arguments.
• When using a secure SSL connection consider that:
  • to use TLS, the mail.imap.starttls.enable argument has to be specified with the value true, to use with SSL, the mail.imap.ssl.enable argument has to be specified with the value true.
  • different ports might be in use: for unencrypted connections and for TLS connections port 143 is frequently used, for SSL connections port 993 is frequently used.
  • optionally use the mail.imap.ssl.protocols argument with a value such as TLSv1.2 or TLSv1.1,TLSv1.2 to specify one or more protocol versions that limit handshake with the mail server to the protocol versions specified. Depending on the Java version in use and possible modifications of the java.security file a number of protocols could be enabled that might not match the mail server's capabilities. Typically SSL handshaking starts from the highest protocol version accepted by both parties. However, it is not guaranteed that protocol negotiation will work perfectly. In such a situation it is recommended that the protocol version is specified using this argument.
• Select the check box provided with each argument if you want this argument to be added to the arguments of the mail inbox job MailInboxJob.

When hitting Hitting the "Submit" button the wizard adds the required arguments to your job that which should then look like this:

The job arguments can be specified:

• from individual variables as offered by configured using the job wizard.
• by use of job resourcesusing Job Resources.

Use of Job

...

Resources for Mail Settings

A number of settings for reading mail inboxes most probably carry the same values when used for different mail inbox jobs. This includes e.g. , for example, the use of the IMAP/POP3 host, port etc.

• You can specify such settings individually from variables that are assigned the job's arguments, see as described above.
• You can specify such settings from JS7 - Job Resources that can be re-used for any number of mail inbox jobs.

Setting up a Job Resource for Mail Settings

You can create a job resource Job Resource that includes any settings required to read mail inboxes.

• For details how to set up a job resourceJob Resource, follow instructions from the JS7 - Job Resources article.
• Find the below example The example shown below is available for download: eMailIMAPDefault.jobresource.json

A job resource Job Resource has two partssides, one being the variables that can be are specified like this from the "Arguments" sub-tab :and the second is about "Environment Variables" that are available for Shell Jobs. For use with the MailInboxJob it is sufficient to specify variables from the "Arguments" tab.

Explanation:

• The variable names specified are selected to match use should match arguments available with the JITL MailInboxJob template.
• Consider the use of variable names that start with mail.store., mail.imap., mail.pop3, etc.
  • The variable names Names of variables correspond to Java properties available with the JavaMail API. Any of the JavaMail properties can be specified.
  • Find You will find a full list of available
    • general mail settings from https://javaee.github.io/javamail/docs/api/javax/mail/package-summary.html
    • mail.imap. properties from https://javaee.github.io/javamail/docs/api/com/sun/mail/imap/package-summary.html
    • mail.pop3. properties from https://javaee.github.io/javamail/docs/api/com/sun/mail/pop3/package-summary.html 
  • Required properties include (but are not limited to):
    • mail.store.protocol
    • mail.imap.host
    • mail.imap.port

Assigning a Job Resource for Mail Settings

...

Image Removed

Documentation

Job Documentation: https://www.sos-berlin.com/doc/JS7-JITL/MailInboxJob.xml

The MailInboxJob class accepts the following arguments:

...

from

...

e-mail address used for sending mail

...

from_name

...

the free-text name of the account that sends mail

...

reply_to

...

if no replies should be accepted then typically use an e-mail address such as no-reply@example.com is used for the respective domain

...

cc

...

e-mail address of carbon copy recipient, multiple e-mail addresses are separated by comma

...

• • • mail.imap.user
    • mail.imap.password
  • Optional properties include (but are not limited to):
    • For authentication the following settings are used:
      • the mail.imap.user setting is assigned the IMAP user account.
      • the mail.imap.password setting is assigned the password.
    • When using OAuth2 authentication then the following settings are used:
      • the mail.imap.auth setting is assigned the value true.
      • the mail.imap.auth.mechanisms setting is assigned the value XOAUTH2.
      • the mail.imap.user setting is assigned the OAuth2 user account.
      • the mail.imap.password setting is assigned the OAuth2 access token.
      • Some mail servers such as smtp.office365.com might require the older SASL mechanism to be used:
        • the mail.imap.sasl.mechanisms.oauth2.oauthToken setting is assigned the OAuth2 access token.
        • the mail.imap.password setting is not specified.

Assigning a Job Resource for Mail Settings

A Job Resource can be created, deployed and assigned the MailInboxJob to populate the job's arguments from the Job Resource as shown in this screenshot:

Image Added

Documentation

The Job Documentation including the full list of arguments can be found under: https://www.sos-berlin.com/doc/JS7-JITL/MailInboxJob.xml

The MailInboxJob can be used with a credential store to hold sensitive arguments.

...

For use of the credential_store_* arguments see JS7 - Use of Credential Store with JITL Jobs.

Further Resources

Links

• JS7 - JITL Common Variables
• JS7 - Job Resources
• JS7 - Use of Credential Store with JITL Jobs

References