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 will catch the email messages sent by local API server, without needing to set up any email server.

Scenarios that send emails

Section titled “Scenarios that send emails”
  • Update email: Users changing their email address
  • Report user: Abuse reports that notify moderators
  • Certifications: Certificate verification emails

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”