One email sandbox for the whole team
Install Buggregator once in your cluster with the Helm chart, list your apps as projects, and turn on SSO. Each app sends its mail to port 1025 with its project key as the SMTP user name. Your team signs in to one inbox and picks a project to see only that app's emails. No email reaches a real mailbox.
Steps
1. Write the values file
config becomes Buggregator's own buggregator.yaml, so the projects go there. auth turns on sign-in for the web UI. The Ingress carries the UI over HTTPS.
config:
projects:
- key: shop
name: Shop
- key: billing
name: Billing
auth:
enabled: true
provider: google
providerUrl: https://accounts.google.com
clientId: YOUR_CLIENT_ID
clientSecret: YOUR_CLIENT_SECRET
callbackUrl: https://mail-sandbox.example.com/auth/sso/callback
ingress:
enabled: true
className: nginx
annotations:
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
hosts:
- host: mail-sandbox.example.com
paths:
- path: /
pathType: PrefixThe timeouts keep the UI's live WebSocket connection open. Other providers: auth0, github, keycloak, gitlab and any OIDC provider.
2. Install the chart
The chart keeps the database on a 5 GiB volume, so emails survive a pod restart.
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator -f values.yaml3. Send each app's mail to its project
Inside the cluster, the SMTP address is the Service name. The SMTP user name picks the project; the password can be anything. For a Laravel app in the default namespace:
MAIL_MAILER=smtp
MAIL_HOST=buggregator.default.svc
MAIL_PORT=1025
MAIL_USERNAME=shop
MAIL_PASSWORD=anyFor Symfony: MAILER_DSN=smtp://billing:any@buggregator.default.svc:1025. Mail without a user name lands in the default project.
4. Reach SMTP from outside the cluster
An Ingress carries only HTTP. For apps outside the cluster, add a TCP Service and limit who can connect, because the SMTP port has no sign-in. It exposes SMTP on 1025 together with the VarDumper and Monolog ports 9912 and 9913:
tcpService:
enabled: true
extraSpec:
loadBalancerSourceRanges: ["203.0.113.0/24"]5. Sign in and pick a project
Buggregator lets in anyone who finishes the provider's sign-in. Keep it to your team at the provider: in Google Cloud, set the OAuth app's user type to Internal, so only accounts of your Google Workspace can sign in. With Keycloak, use a realm that holds only your team, with user registration off. With GitLab, only a self-hosted instance limits it to its own users; on gitlab.com any account can sign in.
Open https://mail-sandbox.example.com and sign in with your provider. The project selector in the sidebar switches between apps.
Why it works
SSO puts the web UI and its API behind your provider's sign-in, and the provider decides who gets in. Ingestion stays open: apps send mail over SMTP with no sign-in, and the SMTP user name only chooses the project. Test scripts that read mail through /api/smtp/* need the X-Auth-Token header while SSO is on. The chart runs one replica with SQLite on its own volume, so nothing else needs to be set up.
Related tips
- Sentry
One Buggregator for all your apps, each in its own project
Give each service its own project key in the Sentry DSN path, the SMTP user name or the profiler URL. One Buggregator keeps their errors and mail apart.
- 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.
- 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
A fake SMTP server as one binary, no Docker
Install one Buggregator binary, run it, and point your app's SMTP at 127.0.0.1:1025. Every email lands in a browser inbox on port 8000.
Checked on with Buggregator v2.13.0