DOCSEARCHbyAlgolia
Submit Docs

MailCrab Documentation

repository·main·Indexed 21 days ago

https://github.com/tweedegolf/mailcrab

MailCrab is an email test server written in Rust for development environments. It features an accept-all SMTP server and a web interface for inspecting incoming emails, attachments, and raw content. The project includes a backend API for message management, support for TLS and authentication, and deployment options via Docker, Docker Compose, Helm for Kubernetes, and Fly.io.

Tokens
9.3K
Snippets
38
Records
42
Agent score
75%

What's inside MailCrab

  1. Enable TLS and Authentication

    main

    MailCrab supports TLS and authentication for the SMTP server.

    Automatic Certificate Generation

    Set ENABLE_TLS_AUTH=true. MailCrab will generate a self-signed certificate and print the key-pair. Any username/password combination is accepted.

    docker run --rm --env ENABLE_TLS_AUTH=true -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest

    Using Custom Certificates

    To use your own certificates, mount your key and certificate files to /app/key.pem and /app/cert.pem inside the container:

    docker run --rm --env ENABLE_TLS_AUTH=true -v key.pem:/app/key.pem:ro -v cert.pem:/app/cert.pem:ro -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest

  2. Deploy MailCrab using Helm

    main

    MailCrab can be deployed to Kubernetes using this Helm chart. The chart manages the deployment of the MailCrab application, including its web interface and SMTP server.

    To deploy, you will typically provide a values.yaml file to configure specific settings such as ingress, autoscaling, and environment variables.

    # Example command to install the chart
helm install mailcrab tweedegolf/mailcrab -f my-values.yaml

  3. Deploy MailCrab to Fly.io

    main

    Once your fly.toml is ready, follow these steps to launch the application:

    1. Run fly launch --ha=false in your configuration folder.
    2. When prompted, select No for the following options:
      • Set up a Postgresql database
      • Set up an Upstash Redis database
      • Allocate dedicated ipv4 and ipv6 addresses
    3. Allocate a shared IPv4 address using fly ips allocate-v4 --shared.
    4. Allocate an IPv6 address using fly ips allocate-v6.

    After deployment, your SMTP host will be your Fly.io app domain and the port will be 1025.

    # Launch the app
fly launch --ha=false

# Allocate network addresses
fly ips allocate-v4 --shared
fly ips allocate-v6

  5. Configure MailCrab ports and host

    main

    You can customize the network configuration using environment variables or Docker port mapping.

    Environment Variables

    • SMTP_PORT: Sets the SMTP server port.
    • HTTP_PORT: Sets the HTTP web interface port.
    • HTTP_HOST: Sets the host address the HTTP server listens on. Defaults to 0.0.0.0 in Docker and 127.0.0.1 when running via binary/cargo.

    Docker Port Mapping Example

    To map the internal ports to different host ports (e.g., HTTP to 3000 and SMTP to 2525):

    docker run --rm -p 3000:1080 -p 2525:1025 marlonb/mailcrab:latest

  6. Configure Nginx as a reverse proxy for MailCrab

    main

    To use Nginx as a reverse proxy for MailCrab, you must configure two location blocks: one for standard HTTP traffic and one specifically for WebSockets at the /ws endpoint. Ensure you set the appropriate headers (Host, X-Real-IP, X-Forwarded-For) and enable HTTP/1.1 with Upgrade and Connection headers for the WebSocket path.

    If you have configured the MAILCRAB_PREFIX environment variable (e.g., MAILCRAB_PREFIX=emails), you must update the location paths in Nginx to include that prefix (e.g., /emails and /emails/ws).

    server {
    listen 80;

    server_name <your server name>;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://<your MailCrab server>:1080;
    }

    location /ws {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_pass http://<your MailCrab server>:1080;
    }
}

  7. Install and run MailCrab via Docker

    main

    The quickest way to start MailCrab is using Docker. This command runs the container with the default SMTP port (1025) and HTTP port (1080) mapped to your host.

    To view the web interface, navigate to http://localhost:1080 in your browser after the container is running.

    docker run --rm -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest

  8. Authenticate with Fly.io

    main

    Before deploying, authenticate your CLI with your Fly.io account. If you have an account, use fly auth login. If you do not have an account, use fly auth signup to create one via your browser.

    # Login to existing account
fly auth login

# Sign up for a new account
fly auth signup

  9. Install flyctl

    main

    To deploy MailCrab on Fly.io, you must first install the flyctl command-line interface. Use the command corresponding to your operating system:

    # Linux
curl -L https://fly.io/install.sh | sh

# MacOS
brew install flyctl

# Windows (PowerShell)
pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"

  10. Configure Apache2 as a reverse proxy for MailCrab

    main

    Apache2 configuration depends on your version.

    For Apache2 version 2.4.47 and later

    Enable mod_proxy and mod_proxy_http. Use the upgrade=websocket parameter in the ProxyPass directive for the /ws endpoint.

    For Apache2 version 2.4.46 and earlier

    Enable mod_proxy, mod_proxy_http, and mod_proxy_wstunnel. You must proxy the /ws endpoint using the ws:// protocol instead of http://.

    Note on MAILCRAB_PREFIX: If using a prefix like emails, ensure all ProxyPass and ProxyPassReverse paths include the prefix (e.g., /emails/ws, /emails).

    # Apache 2.4.47+
<VirtualHost *:80>
    ProxyPass "/ws" "http://<your MailCrab server>:1080/ws" upgrade=websocket

    ProxyPass "/" "http://<your MailCrab server>:1080/"
    ProxyPassReverse "/" "http://<your MailCrab server>:1080/"
</VirtualHost>

# Apache 2.4.46 and earlier
<VirtualHost *:80>
    ProxyPass "/ws" "ws://<your MailCrab server>:1080/ws"

    ProxyPass "/" "http://<your MailCrab server>:1080/"
    ProxyPassReverse "/" "http://<your MailCrab server>:1080/"
</VirtualHost>

  11. Handle MIME parsing warnings

    main

    MailCrab detects common MIME format errors that might cause parts of a message to be lost (e.g., missing boundary terminators in multipart messages). These are surfaced in the parse_warnings field of both MailMessage and MailMessageMetadata.

    Common warnings include:

    • multipart/... part is missing a boundary attribute in its Content-Type header
    • multipart/... part is missing its terminating boundary "--boundary--"
    • multipart/... part declares boundary "...", but it never occurs in the message body

  12. Configure web interface path prefix

    main

    Use the MAILCRAB_PREFIX environment variable to serve the web interface under a specific sub-path.

    Example: Setting MAILCRAB_PREFIX=emails will make the interface available at http://localhost:1080/emails/.

    docker run --rm --env MAILCRAB_PREFIX=emails -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest