Skip to main content

Email tests in GitHub Actions with one service container

Add Buggregator under services: in your GitHub Actions job and publish ports 8000 and 1025. Your app sends mail to localhost:1025, and your tests ask GET /api/smtp/messages/wait whether the email arrived. It answers with the email, or 408 when time runs out. Nothing is delivered to a real inbox.

Steps

1. Add the service to the job

The service's ports are published on the runner, so the job uses localhost. Pin a version tag such as 2.13.0 instead of latest if you want CI to change only when you change it.

yaml
jobs:
  tests:
    runs-on: ubuntu-latest
    services:
      buggregator:
        image: ghcr.io/buggregator/server:latest
        ports:
          - 8000:8000 # HTTP: UI and API
          - 1025:1025 # SMTP
    env:
      MAIL_HOST: localhost
      MAIL_PORT: 1025
    steps:
      - uses: actions/checkout@v4
      - run: ./run-your-tests

Use your framework's own variable names for the SMTP host and port.

2. Wait until it answers

GET /api/version is a health check. Add this step before your tests.

yaml
      - name: Wait for Buggregator
        run: curl -sf --retry 30 --retry-delay 1 --retry-all-errors http://localhost:8000/api/version

3. Start from a clean inbox

bash
curl -X DELETE http://localhost:8000/api/events \
  -H 'Content-Type: application/json' -d '{"type": "smtp"}'

4. Assert in your test

After the action that sends mail, wait for the email. -f makes curl fail on the 408, so the test fails when no email came.

bash
curl -sf -G http://localhost:8000/api/smtp/messages/wait \
  --data-urlencode 'subject=Welcome' \
  --data-urlencode 'to=user@example.com' \
  --data-urlencode 'timeout=10s'

The wait holds the request for at most 60s. To read a code from the email, pass its uuid to GET /api/smtp/message/{uuid}/codes.

Why it works

Buggregator's fake SMTP server on port 1025 stores every email instead of sending it. The testing API on port 8000 lets any test runner ask what arrived. One server per job keeps events of parallel jobs apart, and in CI you usually run without SSO, so the API needs no token.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you