SMTP

Introduction

Platform module for application outbound SMTP requests.

Multiple instances of the module can be configured to support outbound request with different properties, like timeouts, proxies or SSL/TLS settings.

Callers targets the requested instance by its name which must be configuration unique.

Messages can be sent in plain text or HTML format.

Configuration

Note

Module name: SmtpClient

Properties

Name	Description	Default value	Mandatory
name	Destination name. Unique identifier for a specific configuration/connection/service. This value must be unique for all smtpclient configurations.	"default"
host	SMTP server host.	N/A
port	SMTP server port.	N/A
from	Who is the message from.	"[email protected]"
user_name	User name when identifying against SMTP server.	N/A
password	Used when authenticating against SMTP server.	N/A
start_tls	Defines if communications must use TLS. Allowed values are : "OPTIONAL", "DISABLED" or "REQUIRED"	"OPTIONAL"
keep_alive	Should a pool be used keeping connections open.	true
reconnect_interval	value for reconnect interval in ms.	1000
keep_alive_timeout	This value determines how long a connection remains unused, in seconds, in the pool before being evicted and closed.	600
connect_timeout	How many milliseconds before a connect attempt fails.	5000
disable_esmtp	set if ESMTP should be tried as first command (EHLO), rfc 1896	true
idle_timeout	Timeout in seconds.	600
login	possible options for a login into a SMTP server either "DISABLED", "NONE", "REQUIRED" or "XOAUTH2"	"NONE"
reconnect_attempts	Number of reconnect attempts.	3
use_alpn	Whether to use or not Application-Layer Protocol Negotiation.	false
ssl_trust_all	Ignore SSL validation.	false
ssl_handshake_timeout	the SSL handshake timeout in ms.	10
use_ssl	is SSL/TLS enabled.	false
proxy_host	Host for proxying.	N/A
proxy_port	Port for proxying.	N/A
proxy_type	Proxy protocol supported by Vert.x, for example HTTP or SOCKS5.	"HTTP"
proxy_user		N/A
proxy_password		N/A
auth_methods	Authentication methods supported by the SMTP server. The following are supported: "XOAUTH2, DIGEST-MD5, CRAM-SHA256, CRAM-SHA1, CRAM-MD5, PLAIN, LOGIN". Use "" if you are unsure of which auth methods are supported.	"DIGEST-MD5, CRAM-SHA256, CRAM-SHA1, CRAM-MD5, PLAIN, LOGIN"
slow_mail_warning_ms	Logs a warning if SMTP send is still in progress after this many milliseconds. 0 or lower disables the warning timer.	5000
send_timeout_ms	Local timeout for the entire SMTP request, including attachment preparation. 0 means disabled	0
log_activity	Enables "low-level" mail activity logging.	false

Example

{
  "name": "SmtpClient",
  "enabled": true,
  "config": {
    "name": "smtp01",
    "host": "smtp.acme.org",
    "port": 25,
    "user_name": "smtp_user",
    "password": "smtp_password",
    "auth_methods": "DIGEST-MD5, CRAM-SHA256, LOGIN"
  }
}

OAuth 2.0

OAuth 2.0 allows an SMTP client to authenticate by using a short-lived access token instead of a static password. In practice, the client first obtains a token from an identity provider, such as Microsoft Entra ID, and then uses that token with the SMTP server, typically through XOAUTH2. This improves security by reducing reliance on long-lived credentials and allowing authentication to be controlled through modern identity and access policies.

To use OAuth 2.0 :

disable_esmtp and keep_alive must be false.

If auth_methods is set, its only value must be XOAUTH2. When omitted, the module selects XOAUTH2 automatically.

If login is set, it must allow SMTP authentication. When omitted, the module selects XOAUTH2 automatically.

password must not be set.

A separate oauth2 configuration block must be added.

oauth2 properties

Name	Description	Default value	Mandatory
http_destination	Name of the HttpClient module that should be used to fetch the token.
token_url	Full token endpoint URL, for example an Entra token endpoint.
token_parameters	Key/value parameters sent in the token request body. Typical examples: grant_type, client_id, client_secret, scope.
token_headers	Extra HTTP headers to include in the token request.
access_token_field	Name of the field in the token response that contains the access token.	"access_token"
expires_in_field	Name of the field in the token response that contains token lifetime in seconds.	"expires_in"
expires_at_field	Name of the field in the token response that contains an absolute expiry timestamp (epoch seconds). If configured and present, it takes precedence over expires_in_field.
refresh_skew_seconds	Safety margin before expiry. The token will be refreshed before its actual expiry time.	60
http_timeout_ms	Timeout for the token HTTP request.	5000

Example

{
  "name": "default",
  "host": "smtp.example.com",
  "port": 587,
  "start_tls": "REQUIRED",
  "user_name": "[email protected]",
  "disable_esmtp": false,
  "keep_alive": false,
  "oauth2": {
    "http_destination": "oauth-http",
    "token_url": "https://login.example.com/oauth2/token",
    "token_parameters": {
      "grant_type": "client_credentials",
      "client_id": "...",
      "client_secret": "...",
      "scope": "https://outlook.office365.com/.default"
    },
    "token_headers": {
      "Accept": "application/json"
    },
    "access_token_field": "access_token",
    "expires_at_field": "expires_at",
    "expires_in_field": "expires_in",
    "refresh_skew_seconds": 60,
    "http_timeout_ms": 5000
  }
}

Troubleshooting

To enable more information in logs use these loggers in the log4j2.xml file:

<AsyncLogger name="foss.platform.modules.smtp.SmtpRequestHandler" level="TRACE"/>

or for a broader scope use:

<AsyncLogger name="foss.platform.modules.smtp" level="TRACE"/>

For low-level logging with log_activity set to true, use this logger:

<AsyncLogger name="io.vertx.ext.mail.impl.SMTPConnection" level="TRACE"/>

Required level by message type:

• DEBUG
  • request received
  • request prepared
  • attachment preparation
  • attachment file read
  • SMTP send start
• INFO
  • SMTP send success
• WARN
  • slow send warning from slow_mail_warning_ms
  • late SMTP success ignored after timeout
  • late SMTP failure ignored after timeout
• ERROR
  • local SMTP timeout
  • SMTP send failure
  • request preparation failure
• TRACE
  • full Vert.x mail response payload

Practical guidance:

• use DEBUG for normal SMTP troubleshooting
• use WARN if the focus is only slow/hanging mail behavior
• use TRACE if response payload details are needed

Metrics

This module produces metrics for each request.

Naming

name	fortified.internal.smtpclient_<metric-name>
tags	name=<instance-name>

Metric

Name	Type	Description
pending	gauge	Number of pending requests
success	counter	Number of successful request
failure	counter	Number of failed request
request	timer	Request time in ms

JMX example

/ JMX name for HttpClient request failure counter on

// module instance "smtp01"

metrics:name=fortifiedInternalSmtpclient_failure.name.smtp01,type=meters

Events

When sending e-mail using following events are possible

• SMTP001 - Mail sent
  • traceID if present
  • to - comma separated list
  • cc - comma separated list
  • bcc - comma separated list
  • subject - message subject
• SMTP002 - Mail could not be sent
  • traceID if present
  • subject - message subject
• SMTP003 - Mail send timed out
  • traceID if present
  • subject - message subject
  • Note: local timeout in SMTP module; final delivery outcome may still be unknown.