SMTP

Synopsis

Creates an SMTP server that receives email messages. Supports authentication, TLS encryption, and multiple workers with automatic message handling, and JSON conversion.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: smtp
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    username: <string>
    password: <string>
    port: <numeric>
    timeout: <numeric>
    reuse: <boolean>
    workers: <numeric>
    buffer_size: <numeric>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y		Unique identifier
name	Y		Device name
description	N	-	Optional description
type	Y		Must be smtp
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
address	N	"0.0.0.0"	Listen address
port	Y		Listen port
username	N	-	Authentication username
password	N	-	Authentication password
timeout	N	15	Connection timeout in seconds

TLS

Field	Required	Default	Description
tls.status	N	false	Enable TLS encryption
tls.cert_name	Y*		TLS certificate file name in the service root directory
tls.key_name	Y*		TLS private key file name in the service root directory

* = Required when tls.status: true

note

The TLS certificate and key files must be placed in the service root directory.

Performance

Field	Required	Default	Description
reuse	N	false	Enable multi-worker mode
workers	N	CPU count	Number of worker processes when reuse is enabled. Capped at the number of physical cores.
buffer_size	N	9000	Read buffer size in bytes

Details

Emails

The server captures and processes email headers, sender information, recipient information, message content, attachments, and remote client information.

JSON Conversion

All email messages are automatically converted to JSON format with the following fields:

Field	Description
from	Sender address
to	Recipient addresses
subject	Email subject
body	Message body
headers	Email headers
remoteAddr	Client IP address

Multiple Workers

When reuse is enabled, the server uses multiple worker processes which maintain a separate SMTP listener and process messages independently. Messages are automatically converted to JSON.

note

The worker count will be capped at the number of available CPU cores.

Examples

The following are commonly used configuration types.

Basic

Minimal SMTP server listening on port 25:

Creating a simple SMTP server...

devices: - id: 1 name: basic_smtp type: smtp properties: address: "0.0.0.0" port: 25

Secure

SMTP server with TLS and credential authentication:

Configuring TLS and authentication...

devices: - id: 2 name: secure_smtp type: smtp properties: address: "0.0.0.0" port: 587 username: "mailuser" password: "secret" timeout: 30 tls: status: true cert_name: "smtp.crt" key_name: "smtp.key"

note

Port 587 is commonly used for TLS-enabled SMTP (STARTTLS).

High-Volume

SMTP server tuned for high email volumes using multiple workers:

Optimizing for high message volumes...

devices: - id: 3 name: performant_smtp type: smtp properties: address: "0.0.0.0" port: 25 timeout: 60 reuse: true workers: 4 buffer_size: 32768

Submissions

Dedicated SMTP submission server on port 587 with TLS:

Configuring a message submission server...

devices: - id: 4 name: submission_smtp type: smtp properties: address: "0.0.0.0" port: 587 username: "mailuser" password: "secret" timeout: 30 tls: status: true cert_name: "smtp.crt" key_name: "smtp.key" reuse: true workers: 2

Pipelines

Applying preprocessing pipelines to incoming emails:

Applying custom processing to emails...

devices: - id: 5 name: pipeline_smtp type: smtp pipelines: - email_parser - spam_filter properties: address: "0.0.0.0" port: 25 timeout: 30

note

Pipelines are processed sequentially and can modify or drop messages before ingestion.