SMTP Configuration Reference

This page provides comprehensive documentation for all SMTP configuration options in MockForge.

Configuration File

Configuration can be provided via YAML or JSON files:

# config.yaml
smtp:
  # Server settings
  enabled: true
  port: 1025
  host: "0.0.0.0"
  hostname: "mockforge-smtp"

  # Connection settings
  timeout_secs: 30
  max_connections: 100

  # Mailbox settings
  enable_mailbox: true
  max_mailbox_messages: 1000

  # Fixtures
  fixtures_dir: "./fixtures/smtp"

Configuration Options

Server Settings

`enabled`

Type: boolean
Default: false
Description: Enable or disable the SMTP server

smtp:
  enabled: true

`port`

Type: integer
Default: 1025
Description: Port number for the SMTP server to listen on
Notes:
- Standard SMTP port is 25, but requires root/admin privileges
- Common development ports: 1025, 2525, 5025
- Must be between 1 and 65535

smtp:
  port: 1025

`host`

Type: string
Default: "0.0.0.0"
Description: IP address to bind the server to
Options:
- "0.0.0.0" - Listen on all interfaces
- "127.0.0.1" - Listen only on localhost
- Specific IP for network interface

smtp:
  host: "127.0.0.1"  # Localhost only

`hostname`

Type: string
Default: "mockforge-smtp"
Description: Server hostname used in SMTP greeting and responses
Notes: Appears in 220 greeting and 250 HELO/EHLO responses

smtp:
  hostname: "mail.example.com"

Connection Settings

`timeout_secs`

Type: integer
Default: 30
Description: Connection timeout in seconds
Range: 1 to 3600 (1 second to 1 hour)

smtp:
  timeout_secs: 60  # 1 minute timeout

`max_connections`

Type: integer
Default: 100
Description: Maximum number of concurrent SMTP connections
Notes: Prevents resource exhaustion from too many connections

smtp:
  max_connections: 500

Mailbox Settings

`enable_mailbox`

Type: boolean
Default: true
Description: Enable in-memory mailbox for storing received emails

smtp:
  enable_mailbox: true

`max_mailbox_messages`

Type: integer
Default: 1000
Description: Maximum number of emails to store in mailbox
Notes:
- Uses FIFO (First In, First Out) when limit is reached
- Oldest emails are removed when limit is exceeded
- Set to 0 for unlimited (not recommended)

smtp:
  max_mailbox_messages: 5000

Fixture Settings

`fixtures_dir`

Type: string (path)
Default: null (no fixtures)
Description: Directory containing SMTP fixture files
Notes:
- Can be absolute or relative path
- All .yaml and .yml files in directory will be loaded
- See Fixtures documentation for format

smtp:
  fixtures_dir: "./fixtures/smtp"

Or with absolute path:

smtp:
  fixtures_dir: "/opt/mockforge/fixtures/smtp"

Environment Variables

All configuration options can be overridden with environment variables using the prefix MOCKFORGE_SMTP_:

Environment Variable	Config Option	Example
`MOCKFORGE_SMTP_ENABLED`	`enabled`	`true`
`MOCKFORGE_SMTP_PORT`	`port`	`2525`
`MOCKFORGE_SMTP_HOST`	`host`	`127.0.0.1`
`MOCKFORGE_SMTP_HOSTNAME`	`hostname`	`testmail.local`

Example

export MOCKFORGE_SMTP_ENABLED=true
export MOCKFORGE_SMTP_PORT=2525
export MOCKFORGE_SMTP_HOST=0.0.0.0
export MOCKFORGE_SMTP_HOSTNAME=test-server

mockforge serve

Command-Line Arguments

Override configuration via CLI arguments:

mockforge serve \
  --smtp-port 2525 \
  --config ./config.yaml

Priority Order

Configuration is applied in the following order (highest to lowest priority):

Command-line arguments
Environment variables
Configuration file
Default values

Complete Example

Development Configuration

# config.dev.yaml
smtp:
  enabled: true
  port: 1025
  host: "127.0.0.1"
  hostname: "dev-smtp"
  timeout_secs: 30
  max_connections: 50
  enable_mailbox: true
  max_mailbox_messages: 500
  fixtures_dir: "./fixtures/smtp"

Production-Like Configuration

# config.prod.yaml
smtp:
  enabled: true
  port: 2525
  host: "0.0.0.0"
  hostname: "mockforge.example.com"
  timeout_secs: 60
  max_connections: 1000
  enable_mailbox: true
  max_mailbox_messages: 10000
  fixtures_dir: "/opt/mockforge/smtp-fixtures"

CI/CD Configuration

# config.ci.yaml
smtp:
  enabled: true
  port: 1025
  host: "127.0.0.1"
  hostname: "ci-smtp"
  timeout_secs: 10
  max_connections: 10
  enable_mailbox: true
  max_mailbox_messages: 100
  fixtures_dir: "./test/fixtures/smtp"

Performance Tuning

High-Volume Scenarios

For testing high-volume email sending:

smtp:
  max_connections: 2000
  max_mailbox_messages: 50000
  timeout_secs: 120

Memory considerations: Each stored email uses approximately 1-5 KB of memory depending on size. 50,000 emails ≈ 50-250 MB.

Low-Resource Environments

For constrained environments (CI, containers):

smtp:
  max_connections: 25
  max_mailbox_messages: 100
  timeout_secs: 15

Best Practices

Security

Bind to localhost in development:
```
host: "127.0.0.1"
```
Use non-privileged ports:
```
port: 1025  # Not 25
```
Limit connections:
```
max_connections: 100
```

Testing

Use fixtures for deterministic tests:
```
fixtures_dir: "./fixtures/smtp"
```

Configure appropriate mailbox size:

max_mailbox_messages: 1000  # Adjust based on test suite

Set realistic timeouts:

timeout_secs: 30  # Not too short, not too long

CI/CD

Use environment variables for flexibility:
```
MOCKFORGE_SMTP_PORT=1025
```
Start server in background:
```
mockforge serve --smtp &
```
Use localhost binding for security:
```
host: "127.0.0.1"
```

Troubleshooting

Port Already in Use

Error: Address already in use

Solution:

# Check what's using the port
lsof -i :1025

# Use a different port
mockforge serve --smtp-port 2525

Too Many Open Files

Error: Too many open files

Solution: Reduce max_connections:

smtp:
  max_connections: 50

Out of Memory

Error: OOM or slowdown with large mailbox

Solution: Reduce max_mailbox_messages:

smtp:
  max_mailbox_messages: 1000

MockForge Documentation