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.
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-testsUse 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.
- name: Wait for Buggregator
run: curl -sf --retry 30 --retry-delay 1 --retry-all-errors http://localhost:8000/api/version3. Start from a clean inbox
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.
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.
Docs: docs.buggregator.dev/guides/ci.html#github-actions
Requires Buggregator v2.3.0+
Related tips
- Mail
Wait for the confirmation email in an E2E test
Call /api/smtp/messages/wait from your E2E test. It returns the matching email as soon as it arrives, or 408 on timeout. No fixed sleeps.
- Mail
Pull the verification code out of a test email
Wait for the email in your test, then call /api/smtp/message/{uuid}/codes. Buggregator returns the 4–8 digit codes it finds, or your own pattern.
- Mail
Catch dev email in docker-compose with one service
Add Buggregator as a service in docker-compose.yml and set your app's mail host to its service name. Every email lands in the UI on port 8000.
Checked on with Buggregator v2.13.0