Troubleshooting

Common issues and solutions for Zapmail

Emails not appearing

Email sent but not showing in inbox

If you’ve sent an email to your temporary address but it’s not appearing in the inbox, try these steps:

1. Verify the recipient address

   Double-check that the email was sent to the exact address shown in Zapmail. The username is case-sensitive and must match exactly.

   The backend extracts the username using strings.Split(rcpt, "@") (backend/main.go:163-170), so any typos will result in the email being stored under a different username.

2. Refresh your browser

   Manually refresh the page or wait for the automatic refresh cycle. The frontend polls the API for new emails at regular intervals.

3. Check if email was received by the server

   If you have access to server logs, check for entries showing the email was received:

   Received: MAIL FROM:<[e-mail]>
   Received: RCPT TO:<[e-mail]>
   Received raw email data:
   

   These log messages indicate the SMTP server successfully received the email.

4. Verify database storage

   If the email was received but not displayed, there may be a database storage issue. Check logs for:

   Error storing email: [error details]
   

   This would indicate the SMTP server responded with 550 Error storing email (backend/main.go:147).

Emails older than 7 days are automatically deleted. If you’re looking for an old email, it may have been purged by the cleanup job.

Email rejected with error code

If the sending server reports an error when trying to deliver to your Zapmail address:

500 Unrecognized command

• The sending server used an SMTP command not supported by Zapmail
• See the list of supported commands: HELO, EHLO, MAIL FROM, RCPT TO, DATA, NOOP, VRFY, HELP, EXPN, QUIT (backend/main.go:101-102)

550 Error storing email

• The SMTP server received the email but couldn’t save it to the database
• This indicates a database connection or query execution error
• Check the Supabase connection and database schema

Use the HELP command to see what commands the server supports:

telnet yourdomain.com 2525
HELP

Connection issues

Cannot connect to SMTP server

If external mail servers cannot connect to your Zapmail SMTP server:

Server not listening

Symptoms: Connection refused or timeout errors

Diagnosis:

1. Check if the server is running:

   ps aux | grep main
   

2. Verify the server is listening on the correct port:

   netstat -tlnp | grep :2525
   

3. Check server startup logs:

   Temporary Mail Service SMTP Server listening on port 2525
   

Solutions:

• Ensure the PORT environment variable is set (backend/main.go:40-43)
• Verify the server process started without errors
• Check that no other service is using the same port

Firewall blocking connections

Symptoms: External connections time out, but local connections work

Solutions:

• Open the SMTP port in your firewall (e.g., port 2525)
• Configure cloud provider security groups to allow inbound TCP traffic on the SMTP port
• Verify the server is bound to 0.0.0.0 (all interfaces) not just 127.0.0.1 (localhost)

Test external connectivity:

telnet your-domain.com 2525

You should see:

220 Welcome to Temporary Mail Service

Database connection failure

Symptoms: Server starts but crashes when trying to store emails

Error messages:

Error connecting to DB: [details]
Cannot ping DB: [details]

Solutions:

1. Verify SUPABASE_CONN_STRING environment variable is set correctly
2. Test database connectivity:
   psql "$SUPABASE_CONN_STRING"
   
3. Check Supabase project status and connection limits
4. Verify the emails table exists with correct schema

The connection is tested at startup (backend/main.go:179-181):

if err := db.Ping(); err != nil {
    log.Fatal("Cannot ping DB:", err)
}

Frontend cannot reach API

If the web interface loads but cannot fetch emails:

1. Check API endpoint configuration - Verify the Next.js app is configured with the correct API URL
2. CORS issues - Ensure the backend allows requests from the frontend domain
3. Network connectivity - Test the API endpoint directly using curl or Postman

Deployment problems

Environment variables not set

The backend requires specific environment variables to function:

Required variables

# SMTP server port (required)
export PORT=2525

# Supabase/PostgreSQL connection string (required)
export SUPABASE_CONN_STRING="postgresql://user:password@host:5432/database"

If PORT is not set, the server will exit with: PORT environment variable not set (backend/main.go:42)

Docker deployment issues

Container exits immediately

Check logs:

docker logs <container-id>

Common issues:

• Missing environment variables
• Database connection failure
• Port already in use on host

Solution: Pass environment variables to container:

docker run -e PORT=2525 -e SUPABASE_CONN_STRING="..." -p 2525:2525 zapmail

Cannot access server from host

Ensure the port is properly mapped:

docker run -p 2525:2525 zapmail

The first port (2525) is the host port, the second is the container port. They should match the PORT environment variable.

Build failures

When building the Go backend:

Build command

go build -o zapmail backend/main.go

Common errors:

Missing dependencies

cannot find package "github.com/lib/pq"
cannot find package "github.com/joho/godotenv"

Solution:

cd backend
go mod init zapmail
go mod tidy
go build -o zapmail main.go

Performance issues

Slow email delivery

The SMTP server processes each connection in a separate goroutine (backend/main.go:60), allowing concurrent processing. If emails are slow to arrive:

1. Check server load - Monitor CPU and memory usage
2. Database performance - Slow inserts may indicate database issues
3. Network latency - Test connection speed to your database

Memory usage growing

If memory usage continuously increases:

1. Verify cleanup job is running - Check logs for:

   Cleanup job: Old emails removed.
   

2. Check for connection leaks - Ensure connections are being closed properly

   • The defer conn.Close() at backend/main.go:66 should close each connection

3. Database connection pooling - Monitor active database connections

Enable detailed logging to diagnose performance issues. The server logs all received SMTP commands at backend/main.go:90.

Getting help

If you’re still experiencing issues:

1. Check server logs for error messages
2. Review the Architecture guide for debugging tips
3. Verify your configuration matches the Quickstart instructions
4. Test SMTP connectivity using telnet or similar tools

When reporting issues, include:

• Error messages from server logs
• SMTP response codes received
• Steps to reproduce the problem
• Your deployment environment (local, Docker, cloud platform)