> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IMAP Observability

> GermainUX monitors IMAP mailbox availability, connectivity, authentication, folder status, message counts, and selected email-driven business processes.

Components
[`Engine`](https://docs.germainux.com/main/germain-ux-engine)
[`JS Profiler`](https://docs.germainux.com/main/germain-ux-js-profiler)
[`Mobile`](https://docs.germainux.com/main/germain-ux-mobile-app)
[`RPA Bot Recorder`](https://docs.germainux.com/main/germain-ux-rpa-bot-recorder)
[`RUM JS`](https://docs.germainux.com/main/germain-ux-rum-js)
[`RUM Extension`](https://docs.germainux.com/main/germain-ux-rum-extension)

Availability
2017.1 or later

> [card] [Business outcomes](#business-outcomes)
>
> Results for mail operations

> [card] [Backlog and aging detection](#backlog-and-aging-detection)
>
> Find stuck mailbox queues

> [card] [SLAs, alerts, and automation](#slas-alerts-and-automation)
>
> Set mail SLA thresholds

> [card] [Deployment and configuration](#deployment-and-configuration)
>
> Setup steps for mail monitoring

## Overview

GermainUX monitors IMAP mailbox availability, connectivity, authentication, folder status, message counts, and selected email-driven business processes.

The [GermainUX Engine](https://docs.germainux.com/main/germain-ux-engine.md) connects to the configured IMAP server on a schedule, evaluates the selected folders, and sends the resulting metrics and events to GermainUX for analytics, SLA evaluation, alerts, reports, and approved automated actions.

## Business outcomes

IMAP monitoring helps organizations:

* Detect unavailable or unresponsive IMAP services.
* Identify connection, TLS, or authentication failures.
* Confirm that operational mailboxes can be accessed.
* Detect unread-message or backlog growth.
* Find messages that have remained unprocessed beyond an acceptable period.
* Monitor email-driven integrations and business workflows.

> [accordion] Show all 9
>
> * Alert teams when an expected message does not arrive.
> * Detect messages indicating an application, integration, or business failure.
> * Reduce the time required to identify stalled mailbox-based processes.

## Server connectivity and authentication

GermainUX can test:

| Test | Details |
| - | - |
| IMAP server reachability | IMAP server reachability |

* Connection establishment
* TLS negotiation
* Authentication
* Mailbox access
* Folder access
* IMAP response time
* Connection and protocol errors

Common IMAP ports are:

| Connection | Default port |
| - | - |
| IMAP with explicit TLS where supported | 143 |
| IMAP over TLS | 993 |

![IMAP Observability: Server connectivity and authentication](https://mintcdn.com/germain-ux/S6CZjLTFu68xyZFG/images/main/imap-monitoring/image-20200602-221421.png?fit=max\&auto=format\&n=S6CZjLTFu68xyZFG\&q=85\&s=9a443c82da72aacf546079a5cb19c57b)

Use the port and security settings required by the mail provider. Production monitoring should use encrypted connections.

Authentication capabilities depend on the IMAP server, its security policy, and the GermainUX connector version. Confirm compatibility before disabling or changing an organization’s existing authentication controls.

## Mailbox and folder monitoring

GermainUX can monitor selected folders such as:

* Inbox
* Unread
* Processing
* Completed
* Failed
* Rejected
* Application-specific folders

Depending on the configured monitor and rule, collected measurements can include:

* Total message count
* Unread-message count
* New messages detected
* Oldest message age
* Messages matching configured criteria
* Folder accessibility
* Folder check duration
* Errors encountered while reading the folder

Only configure folders required for the monitoring objective. Monitoring every folder in a large mailbox can create unnecessary load and data.

## Email-driven process monitoring

Many applications and integrations use email as an input, output, notification, or processing queue. GermainUX can monitor these workflows by detecting relevant messages and evaluating their timing or status.

Examples include:

* Orders received by email
* Support requests
* Batch-processing notifications
* Integration success or failure messages
* File-delivery notifications
* Report delivery

> [accordion] Show all 9
>
> * Security or infrastructure alerts
> * Approval requests
> * Messages waiting for manual processing

A configured rule can create an event or KPI when a message matching approved conditions appears.

Possible matching attributes include:

* Folder
* Sender
* Recipient
* Subject
* Received timestamp
* Read or unread state

> [accordion] Show all 9
>
> * Message age
> * Approved header values
> * Configured text patterns

Message-body and attachment analysis should be enabled only when required and authorized.

## Expected-message monitoring

GermainUX can detect when an expected message does not arrive within a configured period.

Examples include:

* A daily report was not delivered.
* A batch-completion message is late.
* An integration confirmation is missing.
* A monitored system stopped sending health notifications.
* An order-processing acknowledgement was not received.

This requires a defined expectation, including the message criteria, schedule, time window, and acceptable delay. GermainUX cannot infer an expected delivery schedule solely from the IMAP protocol.

## Backlog and aging detection

Mailbox folders can function as operational queues. GermainUX can identify:

* Increasing unread-message counts
* Messages remaining unprocessed beyond an SLA
* Sudden changes in incoming volume
* No new messages during an expected activity period
* Repeated failure messages
* A growing processing or rejection folder
* Differences between received and completed message counts

These insights depend on the folder structure and message lifecycle implemented by the monitored process.

## Performance monitoring

The IMAP monitor can measure operations performed by GermainUX, such as:

* Connection duration
* Authentication duration
* Folder-access duration
* Message-query or retrieval duration
* Complete monitor execution time

These measurements represent the configured monitoring transaction. They do not automatically provide the IMAP server’s internal CPU, memory, disk, queue, or network utilization.

Monitor those resources separately through the appropriate operating-system, infrastructure, cloud, or mail-server integration.

## Errors

GermainUX can detect:

* Connection timeouts
* DNS or network failures
* TLS errors
* Authentication failures
* Mailbox or folder access failures
* Permission errors

> [accordion] Show all 9
>
> * IMAP protocol errors
> * Message-query failures
> * Monitor execution errors

The error information available depends on what the IMAP server returns to the monitoring connection.

## Configure IMAP monitoring

### Prerequisites

Before configuration, confirm that:

* A GermainUX Engine can reach the IMAP server.
* The required hostname and port are available.
* Firewall and proxy rules permit the connection.
* The monitoring account can access the required mailbox and folders.
* The server’s TLS certificate is trusted.
* The authentication method is supported.
* Mailbox monitoring has been approved by the appropriate security and compliance teams.
* The monitoring account uses the minimum required permissions.

### Run the IMAP wizard

1. Sign in to GermainUX Workspace.
2. Go to **Wizards**.
3. Open **IMAP**.
4. Select **IMAP Monitor** as the component type.

   ![IMAP Observability: Run the IMAP wizard](https://mintcdn.com/germain-ux/S6CZjLTFu68xyZFG/images/main/imap-monitoring/image-20200602-221346.png?fit=max\&auto=format\&n=S6CZjLTFu68xyZFG\&q=85\&s=f7243cdda5fba2a98487a8786ef157ea)
5. Select or create the monitored server.
6. Select or create the monitored application.
7. Select the approved monitoring credentials.

   ![IMAP Observability: Run the IMAP wizard, image 2](https://mintcdn.com/germain-ux/S6CZjLTFu68xyZFG/images/main/imap-monitoring/image-20200602-221404.png?fit=max\&auto=format\&n=S6CZjLTFu68xyZFG\&q=85\&s=f2a7c2267170fd9312ed1957b4fc685e)
8. Select **Next**.
9. Add the folders that GermainUX should inspect.

   ![IMAP Observability: Run the IMAP wizard, image 3](https://mintcdn.com/germain-ux/S6CZjLTFu68xyZFG/images/main/imap-monitoring/image-20200602-221416.png?fit=max\&auto=format\&n=S6CZjLTFu68xyZFG\&q=85\&s=048a2b0e671310b3a977074c227ac413)
10. Enter the IMAP port.
11. Enable the secure-connection option required by the server.

    ![IMAP Observability: Run the IMAP wizard, image 4](https://mintcdn.com/germain-ux/S6CZjLTFu68xyZFG/images/main/imap-monitoring/image-20200602-221410.png?fit=max\&auto=format\&n=S6CZjLTFu68xyZFG\&q=85\&s=056f4503637212633ea2d341904c85d5)
12. Enter a descriptive monitor name.
13. Select the monitoring node.
14. Select the GermainUX Engine.
15. Set the monitoring interval.
16. Review the configuration and select **Finish**.

Use a monitor name that identifies the mailbox, environment, and purpose, for example:

```text theme={null}
Order Processing Mailbox – Production
```

Do not include passwords, tokens, email content, or other secrets in the monitor name.

## Custom IMAP rules

The standard IMAP monitor can be customized when additional message analysis is required.

A custom rule can:

* Create a KPI from a folder or message count.
* Detect a message matching approved criteria.
* Categorize selected messages.
* Measure message age.
* Identify a missing expected message.
* Associate a message with an application or business process.
* Trigger an alert or approved action.

> [accordion] SAMPLE: imap-default.drl
>
> ```go theme={null}
> //
> // Sample IMAP monitoring rules.
> //
> package com.germainsoftware.apm;
>
> dialect "mvel"
>
> import javax.mail.*;
> import com.germainsoftware.apm.config.data.*;
> import com.germainsoftware.apm.converter.*;
> import com.germainsoftware.apm.data.*;
> import com.germainsoftware.apm.data.model.*;
> import com.germainsoftware.apm.message.*;
> import com.germainsoftware.apm.router.*;
>
> global org.slf4j.Logger logger;
> global com.germainsoftware.apm.converter.DatamartConverter datamart;
> global com.germainsoftware.apm.router.RouterContext context;
>
> rule "Unread folder count"
> when 
>     $m : IMGermainessage( )
> then
>     logger.info("Received message for: {}", $m.name);
>
>     GenericMetric m = new GenericMetric();
>     m.type = "IMAP:Unread Count";
>     m.name = $m.name;
>     m.timestamp = $m.timestamp;
>     m.value = (double)$m.folder.getUnreadMessageCount();
>     datamart.insert(m, context);
>
>     retract($m);
> end
> ```

Use the standard monitor wherever possible. Create a custom rule only when the required condition is not already provided, and validate it against representative messages before production deployment.

## SLAs, alerts, and automation

Configure [SLAs](https://docs.germainux.com/main/slas.md) for conditions such as:

* IMAP server unavailable
* Authentication failed
* Folder inaccessible
* Connection or folder check too slow
* Unread-message count above the accepted threshold
* Message older than the processing SLA

> [accordion] Show all 9
>
> * Expected message missing
> * Failure message detected
> * Monitoring data no longer received

Detected conditions can trigger:

* Email or SMS alerts
* Watches for interested GermainUX users
* Incident creation or enrichment
* Webhooks or approved HTTP actions
* Diagnostic scripts
* Authorized remediation workflows
* Scheduled reports

See [Automation](https://docs.germainux.com/main/automation.md).

Avoid sending an IMAP alert exclusively through the same impaired email infrastructure being monitored. Use an independent notification channel for critical availability alerts.

## Analytics and correlation

GermainUX can analyze IMAP activity by:

* Mailbox and folder
* Application and environment
* Server
* Message category
* Sender domain or another approved attribute
* Time period

> [accordion] Show all 9
>
> * Success or failure condition
> * Message age
> * Processing outcome

When compatible identifiers and timestamps are available, IMAP events can be [correlated](https://docs.germainux.com/main/correlation-and-tracing.md) with:

* Application logs
* Integration transactions
* Batch processes
* Support cases
* Orders or business records
* Infrastructure conditions
* Related API or database activity

Correlation requires the relevant identifier to be available in both sources.

## Security and privacy

Mailbox content can contain personal information, credentials, confidential business data, attachments, and regulated information.

* Use a dedicated least-privilege monitoring account.
* Grant access only to required mailboxes and folders.
* Use encrypted IMAP connections.
* Protect credentials using the approved GermainUX credential mechanism.
* Avoid collecting message bodies or attachments unless required.
* Mask, anonymize, or exclude sensitive fields.

> [accordion] Show all 10
>
> * Restrict access to collected message information.
> * Configure appropriate retention.
> * Do not store passwords or access tokens in rules, labels, or dashboards.
> * Review sender, subject, recipient, and message content for privacy implications.

See [Data Privacy](https://docs.germainux.com/main/data-privacy.md).

## Validate monitoring

After configuration:

**1. Confirm that the GermainUX Engine can reach the IMAP server**

**2. Verify successful TLS negotiation and authentication**

**3. Confirm access to each configured folder**

**4. Send an approved test message**

**5. Verify that the folder and unread counts change as expected**

**6. Confirm that the corresponding KPI or event appears in GermainUX**

**7. Test an approved matching rule**

**8. Validate any missing-message or aging condition**

**9. Confirm that SLAs and alerts operate as expected**

**10. Verify that unauthorized message content is not collected**

## Deployment and configuration

* Deploy or select a [GermainUX Engine](https://docs.germainux.com/main/germain-ux-engine.md) with secure access to the IMAP server.
* Run the **IMAP** wizard in GermainUX Workspace.
* Configure the mailbox, folders, secure connection, credentials, and monitoring interval.
* Create custom message rules only for application-specific requirements.
* Configure KPIs, pivots, and measures when additional analytics are required.
* Configure [SLAs](https://docs.germainux.com/main/slas.md) and alerts for operationally significant conditions.

> [accordion] Show all 10
>
> * Configure [correlation and tracing](https://docs.germainux.com/main/correlation-and-tracing.md) with related applications and business processes where supported.
> * Configure approved [automated actions](https://docs.germainux.com/main/automation.md) when required.
> * Create or customize a [dashboard](https://docs.germainux.com/main/management-dashboards.md).
> * Configure scheduled [reports](https://docs.germainux.com/main/reporting-automatic.md).

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

> [card] Can't find what you need?
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.