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_OAUTH2_BASE_SERVER_URLBase URL of the OAuth2/OIDC server-
SECURITY_OAUTH2_REALMOAuth2 realm name-
SECURITY_OAUTH2_CLIENT_CLIENT_IDOAuth2 client ID for the Email Gateway-
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETOAuth2 client secret-
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETService account client secret for admin operations-
The Email Gateway requires a dedicated Keycloak service account. This service account will be provisioned automatically as part of the SaaS organization/auth service, which handles realm creation for services.

​
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 Value
SPRING_REDIS_HOSTRedis server hostnamelocalhost
SPRING_REDIS_PORTRedis server port6379
SPRING_REDIS_PASSWORDRedis authentication passwordyourpassword
For complete Redis configuration including Sentinel mode, Cluster mode, and SSL/TLS setup, see the Redis Configuration guide.

​
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

​
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-

​
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
SECURITY_OAUTH2_CLIENT_CLIENT_SECRETKeycloak client secret
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRETKeycloak service account admin 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
  SECURITY_OAUTH2_REALM: flowx
  SECURITY_OAUTH2_CLIENT_CLIENT_ID: email-gateway
  
  # 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:
      SECURITY_OAUTH2_CLIENT_CLIENT_SECRET: keycloakPlatformAuthorizeClientSecret
      SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET: 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
Last modified on February 2, 2026