Skip to main content

Send an Email Report

The runner can send a dark-themed HTML report via SMTP after a run completes. The report shows a card for each request executed — including request/response headers, bodies, and assertion results — so recipients get a full picture without needing terminal access.

Send to an address​

Use --mail-to to specify the recipient directly in the command:

voiden-runner run ./api-tests --mail-to team@example.com

To send to multiple recipients, set the VOIDEN_MAIL_TO environment variable (comma-separated) and use --mail instead:

VOIDEN_MAIL_TO=team@example.com,qa@example.com voiden-runner run ./api-tests --mail

SMTP configuration​

Provide SMTP credentials as flags or environment variables:

voiden-runner run ./api-tests \
  --mail-to team@example.com \
  --mail-from ci@example.com \
  --mail-subject "API Test Results — $(date +%Y-%m-%d)" \
  --smtp-host smtp.gmail.com \
  --smtp-port 587 \
  --smtp-secure \
  --smtp-user ci@example.com \
  --smtp-pass $SMTP_PASSWORD

Or use environment variables so credentials stay out of your command history:

VariableDescription
VOIDEN_MAIL_TODefault recipient(s), comma-separated
VOIDEN_MAIL_FROMDefault sender address
VOIDEN_SMTP_HOSTSMTP hostname
VOIDEN_SMTP_PORTSMTP port
VOIDEN_SMTP_USERSMTP username
VOIDEN_SMTP_PASSSMTP password

With those set, the command simplifies to:

voiden-runner run ./api-tests --mail

Configure SMTP via Environment File​

Create an .env.mail file (add it to .gitignore) and load it alongside your test environment:

VOIDEN_MAIL_TO=team@example.com
VOIDEN_MAIL_FROM=ci@example.com
VOIDEN_SMTP_HOST=smtp.gmail.com
VOIDEN_SMTP_PORT=587
VOIDEN_SMTP_USER=ci@example.com
VOIDEN_SMTP_PASS=your-app-password
voiden-runner run ./api-tests --env .env.staging --env .env.mail --mail

Combine with CSV​

Send the email report and export a CSV in the same run:

voiden-runner run ./api-tests \
  --csv report.csv \
  --mail-to team@example.com

Send from the report command​

If you accumulate results across multiple pipeline stages, generate and mail a combined report at the end:

voiden-runner report generate \
  --mail-to team@example.com \
  --csv combined.csv
App passwords

When using Gmail or Outlook, generate an app-specific password rather than using your main account password. Standard passwords are blocked for programmatic SMTP access on most providers.