Skip to content
Contribute | freeCodeCamp.org

Debug outgoing emails

Some email workflows require the back-end API server to send outgoing emails. Mailpit is a developer tool for email testing that catches messages sent by the local API server instead of delivering them through a real email provider.

Scenarios that send emails

Section titled “Scenarios that send emails”
  • Update email: Users changing their email address
  • Report user: Abuse reports that notify moderators
  • Certification: Congratulations email when a user claims the Full Stack Developer v9 certification

Using Mailpit

Section titled “Using Mailpit”

Mailpit needs no installation. It starts with the rest of the services in every setup.

  • Your own machine: docker compose -f docker/docker-compose.yml -f docker/docker-compose.ports.yml up -d starts it.
  • Dev Container: it starts with the container.
  • GitHub Codespaces: it starts with the codespace.

Once the containers run, open http://localhost:8025 to reach the Mailpit web interface. It shows every email that your local freeCodeCamp instance sends.

In a codespace, open port 8025 from the Ports panel instead.

Troubleshooting

Section titled “Troubleshooting”

Emails not appearing?

  1. Check the API logs for email errors.

  2. Check that MAILPIT_HOST in .env is localhost. This is correct in every setup.

  3. On your own machine only, check that the containers run with docker ps, then restart Mailpit:

    Terminal window
    docker compose -f docker/docker-compose.yml -f docker/docker-compose.ports.yml restart mailpit

    The Dev Container and Codespaces images carry no Docker CLI. Rebuild the container instead.

Can’t access the UI?

  • Make sure that no other service uses port 8025
  • Try http://127.0.0.1:8025 instead of localhost
Section titled “Useful Links”