Mailpit (SMTP catcher)

Curated name mailpit. Adds Mailpit - an SMTP catcher with a web UI - to the workbench in compose mode.

What it’s for

A fake SMTP server for local development: point your app’s mail at it and nothing leaves the machine. Every message your app sends - sign-up mails, password resets, notifications - is caught and shown in a web inbox, so you can test email flows without a real provider and without spamming anyone. SMTP is on mailpit:1025; the web UI and API are on 8025.

Add it

At init, or to an existing workbench:

monoceros init acme --with-services=mailpit
monoceros add-service acme mailpit

One catcher is usually enough, but if you want to isolate mail per app you can add another under a different name with --as - each gets its own host and connection env:

monoceros add-service acme mailpit --as=billing-mail

Remove it

monoceros remove-service acme mailpit

Or delete the service’s block from acme.yml by hand and re-run monoceros apply acme - the yml is the source of truth. (Mailpit keeps mail in memory, so there is no host data dir to clean up.)

The yml entry

services:
  - name: mailpit # host name in the container
    image: axllent/mailpit:latest
    port: 1025 # in-container SMTP port (feeds `monoceros tunnel`)
    httpPort: 8025 # the web inbox, shared by `monoceros share`
    restart: unless-stopped
    healthcheck: # workspace waits for service_healthy
      test: [CMD, /mailpit, readyz] # Mailpit ships its own readiness probe
      interval: 15s
      timeout: 5s
      retries: 5
    connectionEnv: # → the workspace env vars below
      URL: smtp://${host}:${port}
      HOST: ${host}
      PORT: ${port}

Mailpit needs no credentials and no persistent volume, so the entry is just the image, the SMTP port, and a healthcheck.

What your code sees

Monoceros injects a connection env into the workspace container, prefixed with the service name:

Variable	Value (defaults)
`MAILPIT_URL`	`smtp://mailpit:1025`
`MAILPIT_HOST`	`mailpit`
`MAILPIT_PORT`	`1025`
`MAILPIT_PUBLIC_URL`	`http://acme-mailpit.localhost`

Point your app’s SMTP host/port at MAILPIT_HOST / MAILPIT_PORT (no username/password, no TLS). The prefix is the service name, uppercased.

Tips

Open the web inbox from the host at acme-mailpit.localhost. The proxy routes it to port 8025 for you, so the SMTP port stays out of the way, and the address is there as long as the workbench is.

A tunnel is the alternative when you want it on a local port instead:

monoceros tunnel acme mailpit:8025

See Proxy and tunnels.