60.3 Service Mode and Headless Mode
60.3.1 Overview ¶
For productive setups there are two operating modes without UI: the service mode (Windows service, managed by the Service Control Manager) and the headless mode (console process without UI dependency). Both modes use the same program AEPProcessor.exe - the difference lies in the command-line parameters.
The UI (AutomaticEmailProcessor.exe) is only started in parallel for configuration and monitoring - it communicates with the running processor via IPC files, not via direct function calls.
60.3.2 Modes compared ¶
| Aspect |
Application mode |
Service mode |
Headless mode |
| Program |
AutomaticEmailProcessor.exe |
AEPProcessor.exe --service |
AEPProcessor.exe --headless |
| Visibility |
UI window |
Background service, no UI |
Console process, no UI |
| Management |
Manual or autostart |
Service Control Manager (sc.exe) |
NSSM, Task Scheduler, scripts |
| Login required? |
Yes |
No |
Depends on the caller |
| Recommended for |
Configuration, testing |
Server, continuous operation |
Scheduled tasks, containers |
In most production setups, the service mode is the right choice. Headless mode is suitable when the processor is to be started by an external process manager (NSSM, Windows Task Scheduler).
60.3.3 Command-line parameters ¶
AEPProcessor.exe supports the following parameters:
| Parameter |
Short form |
Description |
--service |
-s |
Windows service mode (Service Control Manager) |
--headless |
-h |
Console mode, autonomous processing without UI |
--run_once |
-r |
Single-run processing, then exit |
--quit |
-q |
Signal all running instances to terminate |
--profile <Name> |
-p <Name> |
Restrict to one profile; can be used multiple times for several profiles |
--profiles [A,B,C] |
-ps [A,B,C] |
Specify multiple profiles in a bracketed list |
--help |
/? |
Print short help |
Examples:
AEPProcessor.exe --service
AEPProcessor.exe --headless
AEPProcessor.exe --headless --run_once
AEPProcessor.exe --headless --run_once --profile "Incoming Invoices"
AEPProcessor.exe --headless --run_once --profile "Incoming Invoices" --profile "Orders"
AEPProcessor.exe --headless --run_once --profiles [Incoming Invoices,Orders,Archive]
AEPProcessor.exe --quit
Profile names with comma: Within the bracketed list, individual names can be put in quotes if they contain a comma themselves - both double and single quotes are supported:
AEPProcessor.exe -h -r --profiles ["Invoices, Incoming",Orders,"Archive, Old"]
Note: Profile names are not case-sensitive. Inactive or non-existent profiles are skipped. Without a profile specification, all active profiles are processed.
60.3.4 Exit codes ¶
The processor terminates with the following exit codes - useful for scripts and the Task Scheduler:
| Code |
Meaning |
| 0 |
Successfully terminated |
| 1 |
Unhandled exception |
| 2 |
License expired or invalid |
| 3 |
Configuration error (e.g. AppData directory not reachable) |
| 4 |
Another instance is already running |
60.3.5 Install service ¶
With sc.exe (standard method)
sc.exe create "AEP4Service" binPath= "C:\Program Files\AutomaticEmailProcessor\AEPProcessor.exe --service"
sc.exe config "AEP4Service" obj= ".\ServiceUser" password= "***"
sc.exe config "AEP4Service" start= auto
sc.exe start "AEP4Service"
With NSSM (Non-Sucking Service Manager)
NSSM manages the process externally and therefore requires headless mode:
nssm install AEP4Service "C:\Program Files\AutomaticEmailProcessor\AEPProcessor.exe" --headless
nssm set AEP4Service ObjectName ".\ServiceUser" "***"
nssm start AEP4Service
Service account
Important: The service must run under a Windows user account - typically a dedicated user or domain account. The account “Local System” is unsuitable because:
- Microsoft 365 OAuth tokens are bound to a Windows user - Local System has no meaningful token cache
- Passwords in the Windows Credential Manager mode are bound to the Windows user - Local System cannot read them
- Printer permissions are set per user - Local System often has no access to network printers
- The heartbeat and IPC data between UI and service are stored in the user registry (
HKEY_CURRENT_USER) - if the service runs under a different account, the UI reports “External processor not active” even though the service is working correctly
Recommendation: Set up a service-account user, log in once with this account, start the UI there and configure accounts/license, then reconfigure the service to use this account.
60.3.6 UI option “External processor” ¶
So that the UI does not get in the service’s way, enable the checkbox “Use external processor (e.g. Windows service)” in Program Options -> Processing under External processor.
Effect: The UI does not start, monitor or terminate the processor itself - it assumes that the service is running independently, and communicates only via the IPC files. Without this option, the UI would try to start its own processor process at every launch and kill it again on exit.
60.3.7 Scheduled task ¶
For regular one-off processing runs without continuous operation, you can set up a scheduled task. The task calls AEPProcessor.exe with --headless --run_once, processes once and exits.
schtasks /create /sc daily /tn "AEP4 Night Run" ^
/tr "\"C:\Program Files\AutomaticEmailProcessor\AEPProcessor.exe\" -h -r" ^
/st 02:00
schtasks /create /sc hourly /tn "AEP4 Invoices" ^
/tr "\"C:\Program Files\AutomaticEmailProcessor\AEPProcessor.exe\" -h -r -p \"Incoming Invoices\"" ^
/mo 1
With different tasks for different profiles, flexible processing times can be set up - e.g. invoices hourly during the day, archiving once a night.
60.3.8 Diagnostics ¶
For problems with the service, the file ServiceDiagnostics.log, which is created in the same directory as AEPProcessor.exe, helps. It contains startup messages, the detected operating mode and errors from the initialization phase - often the only trace when the service exits immediately on startup.
The regular processing and error logs are stored, as in application mode, in the log database in the AppData folder.
60.3.9 Use case ¶
Production setup on server hardware
Service account: company\AEP-Service. Execution mode: service. Autostart at system boot. The UI is occasionally started on a workstation to check logs - the service runs undisturbed.
60.3.10 Tips ¶
- Do not use “Local System” for the service - token caches, Credential Manager passwords and the UI heartbeat are all bound to a Windows user
- In service mode, the UI display of application notifications (see Chapter 40.21) has no effect - use email notifications instead for critical messages