Email Poller

The Oracle Communications Unified Assurance Event Email Poller is a generic email integration. It collects messages from a POP3/IMAP email account, formats them in the normalized JSON format expected by the FCOM Processor, publishes them to the FCOM Processor collection topic, and then deletes the email from the server.

This microservice is the recommended alternative to the Event Email Aggregator service.

This microservice is an optional part of the Event microservice pipeline. See Understanding the Event Pipeline in Unified Assurance Concepts for conceptual information.

You can configure redundancy settings for this microservice when you deploy it. See Configuring Microservice Redundancy for general information.

This microservice provides additional Prometheus monitoring metrics. See Email Poller Self-Monitoring Metrics.

Email Poller Security Configurations

The Email Poller supports a range of configuration methods to integrate securely with various email server setups:

Email Poller Prerequisites

Before deploying the microservice, complete the following prerequisite tasks:

  1. Confirm that a microservice cluster is set up. See Microservice Cluster Setup.

  2. Deploy the following microservices:

  3. Create either a client or certificate Kubernetes secret, depending on your needs. See Email Poller Secrets.

Email Poller Secrets

The Email Poller microservice supports two types of Kubernetes secrets, which are mapped to different security and authentication requirements.

Certificate Secret

The certificate secret consists of one or more files for certificates and truststores for TLS. The secret name is of the format:

<microservice-release-name>-cert-secret

To create a certificate secret, use the following command:

a1k create secret generic <microservice-release-name>-cert-secret --from-file=<path-to>/<email_server_CA> -n <namespace>

where:

Credential Secret

The credential secret is a text-type secret, and it consists of key-value pairs. The secret name is of the format:

<microservice-release-name>-cred-secret

The supported keys for a credential secret are:

To create a credential secret, use the following commands:

In the commands:

Deploying Email Poller

To deploy the microservice, run the following commands:

su - assure1
export NAMESPACE=<namespace>
export WEBFQDN=<WebFQDN> 
a1helm install <microservice-release-name> assure1/email-poller -n $NAMESPACE --set global.imageRegistry=$WEBFQDN --set configData.STREAM_INPUT="<email_server_URI>" --set configData.<tlsConfigPrefix>_CA="<email_server_CA>"

In the commands:

You can also use the Unified Assurance UI to deploy microservices. See Deploying a Microservice by Using the UI for more information.

Changing Email Poller Configuration Parameters

When running the install command, you can optionally change default configuration parameter values by including them in the command with additional --set arguments. You can add as many additional --set arguments as you need.

For example, set a parameter described in Default Email Poller Configuration by adding --set configData.<parameter_name>=<parameter_value>. For example, --set configData.LOG_LEVEL=DEBUG.

Default Email Poller Configuration

The following table describes the default configuration parameters found in the Helm chart under configData for the microservice.

Name Default Value Possible Values Notes
LOG_LEVEL INFO FATAL, ERROR, WARN, INFO, DEBUG The logging level used by the Email Poller.
STREAM_INPUT "" Text, 255 characters The path to the email server to get data from.
See STREAM_INPUT Format for details.
STREAM_OUTPUT persistent://assure1/event/collection Text, 255 characters The path to the Pulsar topic to send data to. The topic at end of path may be any text value.
PROXY_URL "" Text, 255 characters The proxy server URL for network traffic.
EMAIL_POLL_INTERVAL "60" Integer The frequency, in seconds, with which to poll the email server for new messages or events.
PARALLEL_PROCESSING_BATCH_SIZE "100" Integer The number of events (emails) to process in a single thread.
PARALLEL_PROCESSING_THREADS "10" Integer The number of threads to use for concurrent processing.
AUTH_MECHANISM LOGIN LOGIN, XOAUTH2 The authentication mechanism to use.
IMAP_FOLDER INBOX Text, 255 characters The email folder to monitor, for example, INBOX or DRAFT. Only applies to email servers using IMAP protocol.
START_TLS "false" True or False Whether to initiate TLS encryption with STARTTLS. You can also append the startTls=true in STREAM_INPUT to enable this. If either is set to true, STARTTLS is enabled.
See STREAM_INPUT Format for details.
IGNORE_SIZE_ERRORS "true" True or False Whether to suppress errors caused by size limitations or mismatches. Only applies to email servers using IMAP protocol.
OAUTH_AUTH_TYPE client_credentials Text, 255 characters The type of OAuth authentication method, for example, client_credentials or authorization_code.
OAUTH_AUTH_CODE "" Text, 255 characters The OAuth authorization code (used only for certain OAuth types.)
OAUTH_CLIENT_ID "" Text, 255 characters The OAuth client ID registered with the Oauth server.
OAUTH_REDIRECT_URI "" Text, 255 characters The redirect URI for OAuth responses.
OAUTH_SCOPE "" Text, 255 characters The OAuth scopes (permissions) requested.
OAUTH_TOKEN_URL "" Text, 255 characters The OAuth token endpoint.
OAUTH_AUDIENCE "" Text, 255 characters The intended audience for the OAuth token
OAUTH_AUTH_TWO_LINE_FORMAT "true" True or False Whether to enable two-line OAuth format (required by some servers).
REDUNDANCY_FAILOVER_THRESHOLD "4" Integer The number of times the primary microservice must fail checks before the secondary microservice becomes active.
REDUNDANCY_FALLBACK_THRESHOLD "1" Integer The number of times the primary microservice must succeed checks before the secondary microservice becomes inactive.
REDUNDANCY_POLL_PERIOD "5" Integer The number of seconds between status checks from the secondary microservice to the primary microservice.

STREAM_INPUT Format

The format for your STREAM_INPUT setting depends on the type of authentication your email server uses:

Note the following:

This example for deploying the microservice uses the following values:

a1helm install email-poller assure1/email-poller -n a1-zone1-pri --set global.imageRegistry=$WEBFQDN --set configData.STREAM_INPUT="imaps://user%40example.com@example.com:993?tlsConfigPrefix=EMAIL_POLLER_TLS&startTls=true" --set configData.EMAIL_POLLER_TLS_CA="Email_server_CA.crt"

Email Poller Self-Monitoring Metrics

The Email Poller microservice exposes the self-monitoring metrics described in the following table to Prometheus.

Metric Name Type Description
processing_time_per_event Gauge The processing time, per event, from receiving it, to sending it, to acknowledging it.
total_emails_received Counter The total number of emails received by the Email Poller.
total_payloads_sent Counter The total number of payloads sent by the Email Poller to Pulsar.
total_errors_occurred Counter The total number of errors that occurred in the Email Poller

Note:

Metric names in the database include a prefix that indicates the service that inserted them. The prefix is prom_ for metrics inserted by Prometheus. For example, total_payloads_sent is stored as prom_total_payloads_sent in the database.

Email Poller Output

The Email Poller wraps the email payload in the normalized JSON format expected by the FCOM Processor. For example:

{
    "@timestamp": "2025-12-11T09:04:47.000423Z",
    "_domain": "fault",
    "_agents": [
        {
            "id": "email-poller-76b9c9f5c7-74ddz",
            "@timestamp": "2025-12-11T09:04:47.000423Z",
            "host": "email-poller-76b9c9f5c7-74ddz",
            "app": "email-poller",
            "version": "5.0.0-1",
            "input": "pop3s://userD%40example.com@example.com",
            "output": "persistent://assure1/event/collection",
            "cluster": "cluster-1",
            "node": "example.com"
        }
    ],
    "_type": "email",
    "_version": "5.0.0",
    "email": {
        "subjectOfMessage": "Hello from Us!",
        "fromEmailAddress": "sender@example.com",
        "toEmailAddress": "recipient@example.com",
        "ccEmailAddress": "ccperson@example.com",
        "bodyOfMessage": "Thank you for signing up!\r\n",
        "rawEmail": "<raw email body>",
        "contentType": "text/plain; charset=us-ascii",
        "headers": [
            "<header1>",
            "<header2>",
            "<header3>"
        ],
        "plainBody": "Thank you for signing up!\r\n",
        "htmlBody": "<p>Thank you for signing up!</p>",
        "count": 9,
        "received": "1765443887.000"
    }
}

The following table describes the fields in the email object in the output payload:

Field Example Value Description
subjectOfMessage Hello from Us! The subject line of the email message.
fromEmailAddress sender@example.com The sender's email address.
toEmailAddress recipient@example.com The recipient's email address.
ccEmailAddress ccperson@example.com The carbon copy (CC) recipient's email address. This may be an empty string.
bodyOfMessage Thank you for signing up!\r\n The body of the email message, which may include line breaks and formatting.
rawEmail [Full raw email data including headers and body as a single string] The complete raw email message data, including headers and body, as a single string.
contentType text/plain; charset=us-ascii The content type and character encoding of the email.
headers [Array of email header strings containing routing and technical metadata] An array of specific email header entries detailing the email's path and handling.
plainBody Thank you for signing up!\r\n The plain text version of the email's body content.
htmlBody

Thank you for signing up!

 The HTML version of the email's body content. This may be an empty string.
count 9 A custom or system-added field that typically denotes a count of emails or attachments.
received 1765443887.000 A custom value, possibly a Unix timestamp or system reference for when the email was handled.

Email Poller FCOM Rules

The Email Poller adds the normalized messages to the assure1/event/collection Pulsar topic. The FCOM Processor picks up the messages and applies rules to create Unified Assurance events. You can see the default rule for Email Poller events in Rules UI at the following location:

Core Rules (core)/Default read-write branch (default)/processing/event/fcom/_objects/email