Skip to main content
The Email Gateway is a FlowX.AI microservice that handles email communication workflows. It is available as a Docker image and requires specific infrastructure components to function properly.

​
Dependencies

Before setting up the Email Gateway, ensure you have the following dependencies in place:
  • PostgreSQL database for storing email gateway data
  • MongoDB connection to the app-runtime database for runtime data access
  • Kafka for event-driven communication with other FlowX.AI services
  • Redis for caching
  • Keycloak (or compatible OAuth2 provider) for authentication and authorization
The Email Gateway does not require an ingress configuration as it operates as an internal service communicating via Kafka.

​
Infrastructure prerequisites

ComponentDescription
PostgreSQLDedicated database named email_gateway
MongoDBShared connection to the app-runtime database
KafkaMessage broker for inter-service communication
RedisCaching layer for improved performance
KeycloakIdentity provider for service authentication

​
Configuration

​
Authorization configuration

Set the following environment variables to connect to your identity management platform:
Environment VariableDescriptionDefault Value
SECURITY_TYPESecurity typeoauth2
SECURITY_OAUTH2_BASE_SERVER_URLBase URL of the OAuth2/OIDC server
SECURITY_OAUTH2_REALMOAuth2 realm name
SECURITY_OAUTH2_CLIENT_CLIENT_IDClient ID for token introspection
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETClient secret for token introspection
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_IDService account client IDflowx-email-gateway-sa
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account client secret
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URIProvider token URI${SECURITY_OAUTH2_BASE_SERVER_URL}/realms/${SECURITY_OAUTH2_REALM}/protocol/openid-connect/token

​
PostgreSQL configuration

The Email Gateway uses its own dedicated PostgreSQL database for storing email-related data.
Environment VariableDescriptionDefault Value
SPRING_DATASOURCE_URLJDBC connection URL for PostgreSQLjdbc:postgresql://postgresql:5432/email_gateway
SPRING_DATASOURCE_USERNAMEDatabase usernameflowx
SPRING_DATASOURCE_PASSWORDDatabase password-
Ensure the email_gateway database is created before deploying the service. The Email Gateway will manage its own schema migrations.

​
MongoDB configuration (app-runtime)

The Email Gateway connects to the shared app-runtime MongoDB database for accessing runtime data.
Environment VariableDescriptionDefault Value
SPRING_DATA_MONGODB_RUNTIME_URIMongoDB connection URI for app-runtimemongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false
DB_USERNAMEMongoDB usernameapp-runtime
DB_PASSWORDMongoDB password-
The retryWrites=false parameter is required for compatibility with MongoDB replica set configurations that include arbiters.

​
Redis configuration

Email Gateway uses Redis for caching. Configure Redis connection using the standard Redis environment variables. Quick reference:
Environment VariableDescriptionExample ValueStatus
SPRING_DATA_REDIS_HOSTRedis server hostnamelocalhostRecommended
SPRING_DATA_REDIS_PORTRedis server port6379Recommended
SPRING_DATA_REDIS_PASSWORDRedis authentication password-Recommended
REDIS_TTLCache TTL in milliseconds5000000Optional
Both SPRING_DATA_REDIS_* and SPRING_REDIS_* variable prefixes are supported. The SPRING_DATA_REDIS_* prefix is the modern Spring Boot standard and is recommended for new deployments.
For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the Redis Configuration guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

​
Kafka configuration

​
Core Kafka settings

Environment VariableDescriptionDefault Value
SPRING_KAFKA_BOOTSTRAP_SERVERSAddress of the Kafka server(s)localhost:9092
SPRING_KAFKA_SECURITY_PROTOCOLSecurity protocol for Kafka connectionsPLAINTEXT
KAFKA_MESSAGE_MAX_BYTESMaximum message size (bytes)52428800 (50 MB)
KAFKA_AUTHEXCEPTIONRETRYINTERVALRetry interval after authorization exceptions (seconds)10

​
OAuth authentication (when using SASL_PLAINTEXT)

Environment VariableDescriptionDefault Value
KAFKA_OAUTH_CLIENT_IDOAuth client IDkafka
KAFKA_OAUTH_CLIENT_SECRETOAuth client secretkafka-secret
KAFKA_OAUTH_TOKEN_ENDPOINT_URIOAuth token endpointkafka.auth.localhost
When using the kafka-auth profile, the security protocol will automatically be set to SASL_PLAINTEXT and the SASL mechanism will be set to OAUTHBEARER.

​
Topic naming configuration

Environment VariableDescriptionDefault Value
KAFKA_TOPIC_NAMING_PACKAGEPackage prefix for topic namesai.flowx.
KAFKA_TOPIC_NAMING_ENVIRONMENTEnvironment segment for topic names
KAFKA_TOPIC_NAMING_VERSIONVersion suffix for topic names.v1
KAFKA_TOPIC_NAMING_SEPARATORPrimary separator for topic names.
KAFKA_TOPIC_NAMING_SEPARATOR2Secondary separator for topic names-

​
IMAP configuration

Configure the Email Gateway’s IMAP polling behavior for inbound email processing:
Environment VariableDescriptionDefault Value
EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUTIMAP server connection timeout in milliseconds10000
EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLSMaximum number of concurrent IMAP polling operations30
EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLLMaximum messages to fetch per polling cycle50
EMAIL_GATEWAY_IMAP_POLLING_INTERVALInterval between IMAP polling cycles in seconds30
EMAIL_GATEWAY_IMAP_READ_TIMEOUTIMAP read timeout in milliseconds30000

​
Microsoft Graph configuration

Available starting with FlowX.AI 5.5.0These settings apply when using Microsoft Outlook as an email trigger data source. The Email Gateway uses the MS Graph API to poll Outlook mailboxes.
Environment VariableDescriptionDefault Value
EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLLMaximum messages to fetch per MS Graph polling cycle50
EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTLTTL for cached MS Graph client instances1d
The client cache TTL controls how long authenticated MS Graph client instances are kept in memory before being refreshed. Increase this value in stable environments to reduce token refresh overhead.

​
Master election configuration

The Email Gateway uses a master election mechanism to coordinate work across multiple replicas:
Environment VariableDescriptionDefault Value
EMAIL_GATEWAY_MASTER_ELECTION_CRONCron expression for master election checks*/5 * * * * *
EMAIL_GATEWAY_MASTER_ELECTION_TTLMaster election TTL in seconds15

​
Rebalancing configuration

Configure how email accounts are distributed across service instances:
Environment VariableDescriptionDefault Value
EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCEMaximum email accounts per service instance100
EMAIL_GATEWAY_REBALANCING_CRONCron expression for email account rebalancing*/30 * * * * *
EMAIL_GATEWAY_STALE_TIMEOUT_SECONDSTimeout in seconds before marking an instance as stale90

​
Kafka topics

The Email Gateway publishes to the following Kafka topics:
Environment VariableDescriptionDefault Value
KAFKA_TOPIC_AUDIT_OUTTopic for audit event loggingai.flowx.core.trigger.save.audit.v1
KAFKA_TOPIC_PROCESS_START_OUTTopic for triggering process starts from email eventsai.flowx.core.trigger.start-for-event.process.v1

​
Logging configuration

Control logging levels for different components:
Environment VariableDescriptionDefault Value
LOGGING_LEVEL_ROOTRoot logging levelINFO
LOGGING_LEVEL_APPApplication-specific log levelDEBUG
LOGGING_CONFIG_FILEPath to external logging config file-

​
Secrets management

The Email Gateway requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.
Secret NameDescription
SPRING_DATASOURCE_PASSWORDPostgreSQL database password
DB_PASSWORDMongoDB password for app-runtime access
SPRING_REDIS_PASSWORDRedis authentication password
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRETKeycloak service account secret
KAFKA_OAUTH_CLIENT_SECRETKafka OAuth client secret (if using OAuth)

​
Deployment

​
Helm values example

Below is an example Helm values configuration for deploying the Email Gateway: 
fullnameOverride: email-gateway

image:
  repository: <your-registry>/email-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production
  
  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/email_gateway
  SPRING_DATASOURCE_USERNAME: flowx
  
  # MongoDB (app-runtime)
  SPRING_DATA_MONGODB_RUNTIME_URI: "mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false"
  DB_USERNAME: app-runtime
  
  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092
  KAFKA_OAUTH_CLIENT_ID: kafka-client
  KAFKA_OAUTH_TOKEN_ENDPOINT_URI: https://keycloak.example.com/auth/realms/kafka-authz/protocol/openid-connect/token
  
  # OAuth2
  SECURITY_OAUTH2_BASE_SERVER_URL: https://keycloak.example.com/auth
  SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID: flowx-email-gateway-sa
  
  # Redis
  SPRING_REDIS_HOST: redis-master

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: mongodb-generic
    secrets:
      DB_PASSWORD: mongodb-password
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakEmailGatewayClientSecret

rbac:
  create: true

# Email Gateway does not expose HTTP endpoints externally
ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/egress-s-mongodb: "true"
  flowx.ai/routing-name: "email-gateway"
  flowx.ai/prometheus-scrape: "email-gateway"

​
Network policies

The Email Gateway requires network access to the following services:
ServicePurposePod Label
KafkaMessage broker communicationflowx.ai/egress-s-kafka
PostgreSQLPrimary data storageflowx.ai/egress-s-postgresql
MongoDBApp-runtime data accessflowx.ai/egress-s-mongodb

​
Monitoring

The Email Gateway exposes Prometheus metrics for monitoring. Enable scraping by setting the pod label: 
podLabels:
  flowx.ai/prometheus-scrape: "email-gateway"

​
Health endpoints

EndpointDescription
/actuator/healthHealth check endpoint
/actuator/metricsPrometheus metrics endpoint
/actuator/infoApplication info endpoint

​
Troubleshooting

​
Common issues

Symptoms: Service fails to start with database connection errors.Solutions:
  1. Verify the email_gateway database exists in PostgreSQL
  2. Check that the database user has appropriate permissions
  3. Ensure network connectivity between the pod and PostgreSQL service
  4. Verify the JDBC URL format is correct
Symptoms: Errors accessing app-runtime data.Solutions:
  1. Verify MongoDB replica set is healthy
  2. Check that retryWrites=false is set in the connection URI
  3. Ensure the MongoDB user has read access to the app-runtime database
  4. Verify network policies allow MongoDB traffic
Symptoms: Kafka consumer/producer fails to connect.Solutions:
  1. Verify OAuth token endpoint is accessible
  2. Check Kafka OAuth client credentials
  3. Ensure the kafka-authz realm exists in Keycloak
  4. Verify network connectivity to both Kafka and Keycloak
Symptoms: 401/403 errors when calling other FlowX services.Solutions:
  1. Verify the Keycloak service account is properly configured
  2. Check that client secrets match between configuration and Keycloak
  3. Ensure the service account has required roles assigned

Email Trigger

Configure IMAP connections to trigger processes from incoming emails

Email Sender

Configure SMTP connections to send emails from processes

Microsoft Outlook

Connect to Outlook via MS Graph API for reading and sending emails

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Kafka Authentication

Configure Kafka security and authentication

IAM Configuration

Identity and access management setup
Last modified on March 20, 2026