Skip to content

Running EmailRequest

Manually

In its simplest form, EmailRequest can be executed like this:

1
PS C:\Users\me> & PathTo/java.exe -Xmx512m -jar PathTo/email-request-x.x.x.jar PathTo/configurationFile.xml

1
C:\Users\me> PathTo/java.exe -Xmx512m -jar PathTo/email-request-x.x.x.jar PathTo/configurationFile.xml

1
exec PathTo\java -Xmx512m -jar PathTo\email-request-x.x.x.jar PathTo\configurationFile.xml

This will start EmailRequest (email-request-x.x.x.jar) with a memory allocation (Xmx) of 512 Mb and a configuration file (configurationFile.xml). This is especially useful when troubleshooting or testing a configuration before adding it to a scheduled task / job.

This command is often written in a run.cmd or run.sh that is then used in a scheduled task or job in cron. EmailRequest does not in itself handle any scheduling.

Scheduled

This is the recommended way to run EmailRequest consistently and a good starting principle is to import 10 e-mail of max size of 20 Mb each 5 minutes.

This is a basic example of how a script file used to run EmailRequest as a scheduled task / job can look like.

1
2
3
4
5
6
7
8
$javaExec = "PathTo\java.exe"
$client = "PathTo\email-request-x.x.x.jar"
$configFile = 'PathTo\configurationFile.xml'
try {
    & $javaExec -Xmx512m -jar $client $configFile
} catch {
    throw $_
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@echo off
SETLOCAL
Title Easit EmailRequest 4
cd /d "%~dp0"

set client=email-request-x.x.x.jar
set java=jre\bin\java.exe

"%java%" -Xmx512m -jar %client% configurationFile.xml

:end
set client=
set java=

1
2
3
4
5
#! /bin/bash

client=email-request-x.x.x.jar
java=jre\bin\java.exe
exec $java -Xmx512m -jar $client configurationFile.xml

Windows Scheduled Task template

Feel free to save this example to a XML file and then import it to Windows Task Scheduler. If you do so, you need to replace the string ${EmailRequestRoot} in Command and WorkingDirectory with the full path to the folder where you script and emailrequest client lives.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
  <?xml version="1.0" encoding="UTF-16"?>
  <Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
    <RegistrationInfo>
      <Date>2022-12-13T15:09:49</Date>
      <Author>Easit</Author>
    </RegistrationInfo>
    <Triggers>
      <CalendarTrigger>
        <Repetition>
          <Interval>PT5M</Interval>
          <Duration>P1D</Duration>
          <StopAtDurationEnd>false</StopAtDurationEnd>
        </Repetition>
        <StartBoundary>2022-12-13T00:00:00</StartBoundary>
        <Enabled>true</Enabled>
        <ScheduleByDay>
          <DaysInterval>1</DaysInterval>
        </ScheduleByDay>
      </CalendarTrigger>
    </Triggers>
    <Principals>
      <Principal id="Author">
        <UserId>S-1-5-19</UserId>
        <RunLevel>LeastPrivilege</RunLevel>
      </Principal>
    </Principals>
    <Settings>
      <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
      <DisallowStartIfOnBatteries>true</DisallowStartIfOnBatteries>
      <StopIfGoingOnBatteries>true</StopIfGoingOnBatteries>
      <AllowHardTerminate>true</AllowHardTerminate>
      <StartWhenAvailable>false</StartWhenAvailable>
      <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
      <IdleSettings>
        <StopOnIdleEnd>true</StopOnIdleEnd>
        <RestartOnIdle>false</RestartOnIdle>
      </IdleSettings>
      <AllowStartOnDemand>true</AllowStartOnDemand>
      <Enabled>false</Enabled>
      <Hidden>false</Hidden>
      <RunOnlyIfIdle>false</RunOnlyIfIdle>
      <DisallowStartOnRemoteAppSession>false</DisallowStartOnRemoteAppSession>
      <UseUnifiedSchedulingEngine>false</UseUnifiedSchedulingEngine>
      <WakeToRun>false</WakeToRun>
      <ExecutionTimeLimit>PT1H</ExecutionTimeLimit>
      <Priority>7</Priority>
    </Settings>
    <Actions Context="Author">
      <Exec>
        <Command>${EmailRequestRoot}\run.cmd</Command>
        <WorkingDirectory>${EmailRequestRoot}</WorkingDirectory>
      </Exec>
    </Actions>
  </Task>

Considerations

Consideration - Long running task / prioritize mailboxes

As EmailRequest reads and acts on each entry in the configuration file in sequence, not in parallel, you should not schedule a task to run more often than the time it takes to complete. If the scheduled task takes longer to complete than the interval for which the EmailRequest runs is set issues can arise. An example, depending on how the task i configured, can be that effective interval is actually 10 minutes. Lets say we have a task running each 5 minutes (00:00, 00:05, 00:10 and so on) and the task actually takes 6 minutes to complete, then the first entry will run every 9-10 minute and the last one every 5 minute.

One way to mitigate this issue is by break up the configuration file in multiple files. This also opens up for more scheduling customization.

Pretend we have 3 high valued mailboxes that we would like to import mail from every 5 minutes. We add this to highValuedMailboxes.xml. We also have 5 mailboxes that does not of as high value as the previous 3. We add this to regularValuedMailboxes.xml. We also create two scripts for each configuration file, see example below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@echo off
SETLOCAL
Title Easit EmailRequest 4
cd /d "%~dp0"

set client=email-request-x.x.x.jar
set java=jre\bin\java.exe

"%java%" -Xmx512m -jar %client% highValuedMailboxes.xml

:end
set client=
set java=

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@echo off
SETLOCAL
Title Easit EmailRequest 4
cd /d "%~dp0"

set client=email-request-x.x.x.jar
set java=jre\bin\java.exe

"%java%" -Xmx512m -jar %client% regularValuedMailboxes.xml

:end
set client=
set java=

We can now schedule 2 separate task running on different intervals. However, this requires us to customize the logging. If we don´t the tasks logging will be mixed on the log file. Therefore we need to copy log4j2.xml, rename the copy to log4j2_highValuedMailboxes.xml and then do the same again but rename it to log4j2_regularValuedMailboxes.xml. In each new log4j2.xml we update the value for default-log-name (or replace emailrequest.log with emailrequest_highValuedMailboxes.log) with emailrequest_highValuedMailboxes and emailrequest_regularValuedMailboxes respectively.

More on logging

1
2
3
4
5
6
7
8
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="INFO">
    <Properties>
        <Property name="log-path">Logs</Property>
        <Property name="default-log-pattern">%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level - %m [%c]%n</Property>
        <Property name="default-max-log-files">30</Property>
        <Property name="default-log-name">emailrequest_highValuedMailboxes</Property>
    </Properties>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<Appenders>
  <Console name="STDOUT" target="SYSTEM_OUT">
  <PatternLayout pattern="${default-log-pattern}"/>
  </Console>
<RollingFile name="FILE" fileName="${log-path}/emailrequest.log"
  filePattern="${log-path}/emailrequest-%d{yyyy-MM-dd}.log">
  <PatternLayout>
    <pattern>${default-log-pattern}</pattern>
  </PatternLayout>
  <Policies>
    <TimeBasedTriggeringPolicy interval="1" modulate="true"/>
  </Policies>
  <DefaultRolloverStrategy>
    <Delete basePath="${log-path}" maxDepth="1">
      <IfFileName glob="emailrequest-2*.log" />
      <IfAccumulatedFileCount exceeds="${default-max-log-files}" />
    </Delete>
  </DefaultRolloverStrategy>
</RollingFile>
<RollingFile name="FILETRACE" fileName="${log-path}/emailrequest-trace.log"
  filePattern="${log-path}/emailrequest-trace-%d{yyyy-MM-dd}.log">
  <PatternLayout>
    <pattern>${default-log-pattern}</pattern>
  </PatternLayout>
  <Policies>
    <TimeBasedTriggeringPolicy interval="1" modulate="true"/>
  </Policies>
  <Filters>
    <!-- Deny DEBUG and above & allow TRACE -->
    <ThresholdFilter level="DEBUG" onMatch="DENY" onMismatch="NEUTRAL"/>
    <ThresholdFilter level="TRACE" onMatch="ACCEPT" onMismatch="DENY"/> 
  </Filters>
  <DefaultRolloverStrategy>
    <Delete basePath="${log-path}" maxDepth="1">
      <IfFileName glob="emailrequest-trace-2*.log" />
      <IfAccumulatedFileCount exceeds="${default-max-log-files}" />
    </Delete>
  </DefaultRolloverStrategy>
</RollingFile>

Lastly we update or scripts as shown below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@echo off
SETLOCAL
Title Easit EmailRequest 4
cd /d "%~dp0"

set client=email-request-x.x.x.jar
set java=jre\bin\java.exe

"%java%" -Dlog4j.configurationFile="log4j2_highValuedMailboxes.xml" -Xmx512m -jar %client% highValuedMailboxes.xml

:end
set client=
set java=

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@echo off
SETLOCAL
Title Easit EmailRequest 4
cd /d "%~dp0"

set client=email-request-x.x.x.jar
set java=jre\bin\java.exe

"%java%" -Dlog4j.configurationFile="log4j2_regularValuedMailboxes.xml" -Xmx512m -jar %client% regularValuedMailboxes.xml

:end
set client=
set java=

Consideration - Importing large e-mails

EmailRequest needs a certain amount of memory to be able to read mail and send them to Easit GO. The memory used is based on how large the incoming mail is when it is read from the mail server and stored in memory. The property "maxMessageSize" specifies in bytes or MB how large a message can be maximum for EmailRequest to read it from the e-mail server and forward it to Easit GO. Below is described how the size of a message affects the memory consumption for ER and "maxMessageSize" can then give the maximum amount of memory needed to read an email with EmailRequest.

ATTENTION! Make sure the server has enough memory to do the expansion.

Max e-mail size (Mb) Xmx in script Mb to add to Tomcat Heap maxMessageSize in configuration file (IMAP4) maxMessageSize in configuration file (POP3)
20 768 512 23900 23933333
25 1024 768 25600 25600000
30 1024 768 32466 32466666
35 1280 1024 36000 36000000
40 1280 1024 41000 41000000
45 1280 1024 46080 46080000
50 1536 1280 51200 51200000