Troubleshooting

This guide covers common issues you might encounter when using Mailtura and how to resolve them.

Installation Issues

Docker Services Won’t Start

Problem: Services fail to start with Docker Compose.

Solution:

1. Check Docker logs:

   docker-compose logs

2. Verify port availability:

   lsof -i :587  # Check SMTP port
   lsof -i :5432 # Check PostgreSQL port

3. Ensure sufficient disk space:

   df -h

Database Connection Errors

Problem: Cannot connect to the database.

Solution:

1. Verify database is running:

   docker-compose ps postgres

2. Check connection string in .env:

   DATABASE_URL=postgresql://user:password@localhost:5432/mailtura

3. Test database connection:

   psql $DATABASE_URL

Email Delivery Issues

Emails Not Sending

Problem: Emails are queued but not being sent.

Solution:

1. Check SMTP configuration:

   curl https://your-mailtura-instance.com/api/v1/health

2. Verify SMTP credentials
3. Check firewall rules for outbound SMTP
4. Review email queue:

   curl https://your-mailtura-instance.com/api/v1/queue \
     -H "Authorization: Bearer YOUR_API_KEY"

Emails Going to Spam

Problem: Sent emails are marked as spam.

Solution:

1. Set up SPF record:

   v=spf1 include:your-mailtura-instance.com ~all

2. Configure DKIM signing
3. Add DMARC policy:

   v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com

4. Use a verified domain
5. Maintain good sender reputation

High Bounce Rate

Problem: Many emails are bouncing.

Solution:

1. Validate email addresses before sending
2. Clean your email list regularly
3. Check bounce reasons:

   curl https://your-mailtura-instance.com/api/v1/bounces \
     -H "Authorization: Bearer YOUR_API_KEY"

4. Remove hard bounces from your list
5. Implement double opt-in for subscriptions

API Issues

Authentication Errors

Problem: Getting 401 Unauthorized responses.

Solution:

1. Verify API key is valid:

   echo $MAILTURA_API_KEY

2. Check tenant ID header:

   X-Tenant-ID: your-tenant-id

3. Ensure API key has correct permissions
4. Check if API key is expired

Rate Limiting

Problem: Receiving 429 Too Many Requests errors.

Solution:

1. Check current rate limits:

   curl https://your-mailtura-instance.com/api/v1/quotas \
     -H "Authorization: Bearer YOUR_API_KEY"

2. Implement exponential backoff
3. Use bulk endpoints for multiple emails
4. Request quota increase if needed

Template Not Found

Problem: API returns template not found error.

Solution:

1. List available templates:

   curl https://your-mailtura-instance.com/api/v1/templates \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-Tenant-ID: your-tenant-id"

2. Verify template name matches exactly
3. Check tenant ID is correct
4. Ensure template is published

Performance Issues

Slow Email Delivery

Problem: Emails take a long time to deliver.

Solution:

1. Check queue depth:

   curl https://your-mailtura-instance.com/api/v1/metrics/queue

2. Scale worker processes
3. Optimize database queries
4. Check network latency to SMTP server
5. Review rate limiting settings

High Memory Usage

Problem: Mailtura consuming excessive memory.

Solution:

1. Monitor memory usage:

   docker stats

2. Reduce batch sizes for bulk operations
3. Optimize template sizes
4. Increase available memory
5. Check for memory leaks in logs

Monitoring and Debugging

Enable Debug Logging

Add to your .env file:

LOG_LEVEL=debug
DEBUG=mailtura:*

Check Application Logs

docker-compose logs -f mailtura

Monitor System Health

curl https://your-mailtura-instance.com/api/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Expected response:

{
  "status": "healthy",
  "services": {
    "database": "up",
    "smtp": "up",
    "queue": "up"
  }
}

Database Performance

Monitor slow queries:

SELECT * FROM pg_stat_statements
ORDER BY total_time DESC
LIMIT 10;

Common Error Codes

Getting Help

If you’re still experiencing issues:

1. Check the documentation: Review relevant docs sections
2. Search existing issues: GitHub Issues
3. Ask the community: Join discussions on GitHub
4. Create an issue: Provide:
   • Mailtura version
   • Environment details
   • Error messages
   • Steps to reproduce
   • Relevant logs

Useful Commands

Reset Everything

docker-compose down -v
docker-compose up -d

View Real-time Logs

docker-compose logs -f --tail=100

Check Configuration

docker-compose exec mailtura cat /etc/mailtura/config.yml

Database Backup

docker-compose exec postgres pg_dump -U postgres mailtura > backup.sql

Database Restore

docker-compose exec -T postgres psql -U postgres mailtura < backup.sql

Next Steps

• Monitor performance
• View API reference
• Join GitHub discussions