Features

Required

Four keys must be present. recipient can be substituted with recipient_file.

smtpbench [email protected] port=587 threads=5 messages=10

Load generation

How much traffic, and how fast.

smtpbench [email protected] port=587 threads=10 messages=0 rate=10

smtpbench [email protected] port=587 threads=5 messages=100 delay=1

Targeting and delivery

Where the mail goes, and what happens when a host is down.

smtpbench [email protected] port=25 threads=10 messages=100

smtpbench [email protected] lb_host=smtp.dev.lets.qa port=587 threads=5 messages=10

smtpbench recipient_file=recipients.txt recipient_file_order=roundrobin \
          from_file=senders.txt \
          lb_host=smtp.dev.lets.qa port=587 threads=5 messages=100

Sender identity and journaling

Journal mode exists for testing archiving and compliance paths. The same message also goes to a journaling address, the way a real archiving deployment would capture it.

smtpbench [email protected] port=587 threads=5 messages=10 \
          journal=true [email protected]

Transport and authentication

smtpbench [email protected] port=465 threads=5 messages=10 tls_mode=ssl

export SMTPBENCH_USER=myuser
export SMTPBENCH_PASS=mypassword
smtpbench [email protected] port=587 threads=5 messages=10

smtpbench [email protected] port=587 threads=5 messages=10 \
          dotenv_path=/etc/smtpbench.env

Message realism

Real relays behave differently under 2MB attachments than under empty test messages.

smtpbench [email protected] port=587 threads=5 messages=20 \
          attachment_dir=./corpus attachment_probability=0.8 attachment_count=1-3

smtpbench [email protected] port=587 threads=5 messages=50 \
          attachment_size=10KB-2MB

smtpbench [email protected] port=587 threads=5 messages=20 \
          body_text_dir=./text-corpus

Output and observability

Every message is traceable

Each message carries headers for correlation across distributed mail systems. The run UUID is constant per run; thread and message IDs vary per message. Find one message in a downstream mailbox and tie it back to the log line that produced it, or filter an entire run out of a shared mailbox afterwards.

X-SMTPBench-Run-UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-SMTPBench-Thread-ID: 3
X-SMTPBench-Message-ID: 7

The summary artifact

Every run writes summary_{timestamp}_{uuid}.json. Field shapes below; the file also records elapsed_seconds and config.address_lists.

{
  "run_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "config": {
    "threads": 5, "messages": 100, "rate": null,
    "tls_mode": "starttls", "auth": false, "port": 587, "offline": false
  },
  "totals": { "sent": ..., "failed": ..., "retried": ..., "success_rate": ... },
  "latency_ms": { "p50": ..., "p95": ..., "p99": ..., "max": ... },
  "per_mx": { "mx1.dev.lets.qa": { "sent": ..., "failed": ... } }
}

Offline mode

Fully offline: no DNS or MX lookup, no banner check, no connection. The recipient is used only as a message header, and since 1.2.1 no port is needed.

smtpbench [email protected] threads=5 messages=20 \
          eml_out_dir=./eml-output

smtpbench [email protected] threads=2 messages=10 \
          eml_out_dir=./eml-output attachment_dir=./corpus \
          attachment_probability=0.5 body_text_dir=./text-corpus

Getting help

--help, -h, help, ?, --version, -v, version, and zero arguments all short-circuit before any parsing, so they are always safe to run.

smtpbench --help      # full option list and examples
smtpbench --version