With the SmtpService, the Integration Server provides a complete SMTP server that, through its integration into the overall system, is able to inform all connected applications about incoming mails.

The SmtpService offers the following possibilities to offer mail-based data exchange.

Receive mails using the SMTP protocol.
Limitation of the delivering partners using authentication methods, e.g. PLAIN or LOGIN for ASMTP.

XML configuration

Important note: The availability of a service depends on the license purchased and whether the service has been registered in the configuration file ./etc/factory.xml of the Service Factory (changes require server restart!). There you will also find the responsible configuration file for a service, otherwise you can also edit the configuration file of the service directly in the GUI of the service (changes require a service restart!).

The following XML fragment with all possible base settings can be used to configure the SmtpService.

<Set name="defaultMessageService">MessageService</Set>
<Set name="listenAddress">0.0.0.0</Set>
<Set name="maxAllowedMailSize">2048</Set>
<Set name="numberOfThreads">5</Set>
<Set name="usePersistantMessaging">true</Set>
<Set name="port">25</Set>

The parameters have the following meaning.

defaultMessageService	The name of the MessageService to forward incoming mails.
listenAddress	The IP address of the network interface to which incoming requests should be restricted. If all interfaces are to be supported, the parameter can be omitted or set to 0.0.0.0.
maxAllowedMailSize	The maximum size in bytes that an e-mail may have to be accepted by the SmtpService. The size must be specified in KB (1024 bytes). So if you want to accept up to 2 MB (the default) is accepted, the value 2048 should be specified. The value -1 specifies that there is no size limit.
numberOfThreads	The number of threads waiting in parallel for incoming requests. If all threads are busy with requests, further requests are not processed. Therefore, the number should be set high enough to avoid loss of speed.
port	The port to use for receiving incoming SMTP requests.
usePersistantMessaging	The mails are forwarded as persistent messages to the MessageService.

Enabling SMTPS

To enable SMTPS, the following section must be inserted.

<Set name="tlsPort">465</Set>
<Set name="tlsSubjectName">*CN=*SMTP Server Certificate Example*</Set>
<Set name="tlsRequired">true</Set>

Parameter tlsPort activates an additional port, on which the service is listening and direct TLS connections are established. For this to work, if acting as server, a certificate is needed, which must be set via the search string tlsSubjectName. If the certificate is set and found, the command STARTTLS is offered on the unencrypted port, which allows you to switch to TLS. With tlsRequired set to true, STARTTLS must be executed before any other operation can be performed, otherwise its use is optional.

Setting whitelist and blacklist entries

With this XML fragment a whitelist (allowed addresses) and blacklist (not allowed addresses) can be added.

"AddIpAddress" adds a single IP address, "addAddressRange" adds an address range.

<!-- define white access list here -->
<Call name="getWhiteAccessList">
	<Call name="addIpAddress">
		<Arg>a_single_IP_address</Arg>
	</Call>
	<Call name="addAddressRange">
		<Arg>base_IP_address</Arg>
		<Arg>a_netmask</Arg>
	</Call>
</Call>
 
<!-- define black access list here -->
<Call name="getBlackAccessList">
	<Call name="addIpAddress">
		<Arg>a_single_IP_address</Arg>
	</Call>
	<Call name="addAddressRange">
		<Arg>base_IP_address</Arg>
		<Arg>a_netmask</Arg>
	</Call>
</Call>

Restricting to specific senders and receivers

You can use the configuration file ./etc/mail_address.properties exists to specify email senders and email recipients (including CCs). Only if both the sender and the recipient of the received email are found in this file, the the email be processed. This is especially useful when you are using a DMZ server to exclude spam emails. The file is structured as follows.

# define access list for smtp service
# only accept mails if sender address or (cc) recipients of incoming mail
# are found within this list
# addresses are separated by ;
# example:
# mail.sender=info@lobster.de;lobster.de
# mail.recipients=dw@lobster.de;lobster.de
#
mail.sender=lobster.de;test.org
mail.recipients=hub.org;xxx.org

Adding an "SmtpAction"

The following XML fragment adds an SmtpAction to the SmtpService.

<Call name="addAction">
	<Arg>
		<New class="com.ebd.hub.services.smtp.SmtpAction">
			<Arg>System</Arg>
			<Arg>smtp</Arg>
			<Call name="add">
				<Arg>allowedAddress@domain</Arg>
			</Call>
		</New>
	</Arg>
</Call>

The two parameters correspond to the message context and the message queue to be used. For each email address that is to be activated for this queue, a corresponding call entry must be added to the configuration file.

Setting a "NoActionDefinedHandler"

If an email is received that does not contain an email address for which a SmtpAction has been defined, it can be forwarded to a corresponding handler. If no such handler is set, these incoming emails are ignored and discarded.

The following XML fragment adds a NoActionDefinedHandler to the SmtpService.

<Call name="setNoActionDefinedHandler">
	<Arg>
		<New class="[name of the class to set]">
		[possibly necessary settings]
		</New>
	</Arg>
</Call>

The class to be set must implement the interface com.ebd.hub.services.smtp.INoActionDefinedHandler. We provide a programming interface (API) that also allows you to develop your own classes (preparsers, functions, etc.) in Java. For this, we offer in-depth training. If you are interested, please contact our support or sales staff.

A default handler is the DefaultNoActionDefinedHandler, which is described below.

Setting a "DefaultNoActionDefinedHandler"

If this handler is set as NoActionDefinedHandler, all emails that cannot be further processed by a corresponding SmtpAction, are forwarded to a specified email address. The forwarding takes place via a correspondingly defined email server. The following XML fragment creates a DefaultNoActionDefinedHandler.

<Call name="setNoActionDefinedHandler">
	<Arg>
		<New class="com.ebd.hub.services.smtp.DefaultNoActionDefinedHandler">
			<Set name="host">mailserver</Set>
			<Set name="port">25</Set>
			<Set name="user">user</Set>
			<Set name ="pwd">passwd</Set>
			<Set name="sender">sender@domain.invalid</Set>
			<Set name="forwardAddress">recipient@domain.invalid</Set>
		</New>
	</Arg>
</Call>

The parameters have the following meaning.

Parameter	Description
host	The host name of the SMTP server to use.
port	The port of the SMTP server. If no port is set, the default value 25 is used.
user	The user name to use for authentication to the SMTP server. If no user name is specified, no authentication is attempted.
pwd	The password to use for authentication to the SMTP server.
sender	The sender address to use for the email.
forwardAddress	The address to which the email should be forwarded.

Note: The forwarded email no longer corresponds to the format of the original email. It is reassembled from the individual parts (body, attachments).

Setting an "SmtpAuthenticator"

If an authentication for the SMTP protocol is to be activated, it is necessary to set the authenticator to be used. The SmtpService provides two possible authenticator.

The DirectSetAuthenticator whose users are set directly in the XML configuration file.
The FileAuthenticator whose users are defined in a separate file and loaded on startup.

The following XML fragment sets the Authenticator to be used by the SmtpService.

<Call name="setSmtpAuthenticator">
	<Arg>
		<New class="[class name of the Authenticator to use]">
			[possibly necessary settings]
		</New>
	</Arg>
</Call>

Setting a "DirectSetAuthenticator"

The DirectSetAuthenticator can set the allowed users directly within the XML configuration file.

The class name to add it to the SmtpService is com.ebd.hub.services.smtp.auth.direct.DirectSetAuthenticator.

Adding a user

The following XML fragment adds a user to the DirectSetAuthenticator.

<Call name="addUser">
	<Arg>
		<New class="com.ebd.hub.services.smtp.SmtpUser">
			<Arg>username</Arg>
			<Arg>password</Arg>
		</New>
	</Arg>
</Call>

Setting a "FileAuthenticator"

The FileAuthenticator loads the allowed users via another file containing all usernames and passwords.

The class name to add it to the SmtpService is com.ebd.hub.services.smtp.auth.direct.FileAuthenticator.

Reading the user file

The following XML fragment makes the manager read the user file.

<Call name="readUserFile">
	<Arg>./etc/mail_users.cfg</Arg>
</Call>

The structure of a file for defining users is described in section Format of the FileAuthenticator User File.

General settings and available "SMTPActions"

images/download/attachments/189460125/Services_41_EN-version-1-modificationdate-1737526404742-api-v2.png

images/download/attachments/189460125/Services_42_EN-version-1-modificationdate-1737526404739-api-v2.png

images/download/attachments/189460125/Services_43_EN-version-1-modificationdate-1737526404736-api-v2.png

(1) The MessageService to be used.

(2) The messages are forwarded as persistent messages to the MessageService.

(3) IP address and port of the SmtpService.

(4) Number of threads used to process incoming emails.

(5) Whitelist and blacklist can be edited here.

(6) The maximum size in bytes that an email may have to be accepted by the SmtpService. The size must be specified in kB (1024 bytes). So, if you want to accept a maximum of 2 MB (the default), specify 2048. The value -1 specifies that there is no limit to amount of data to be accepted.

(7) List of the available SMTPActions. These can be added, edited and removed via the context menu.

Editing "SMTPAction"

images/download/attachments/189460125/Services_44_EN-version-1-modificationdate-1737526404733-api-v2.png

(8) Settings of the MessageService for the SMTPAction. You can either use the Default MessageService, or any other one. With the parameters Message Context and Message Queue, you can use the MessageService to control who should receive the messages.

(9) Email addresses can be added, changed and deleted here.