Mailpit

https://mailpit.axllent.org/docs
Admin
Mailpit is an SMTP server and web UI for testing email delivery, featuring real-time mail viewing,...
Tokens:34,787
Snippets:395
Trust Score:8.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Override From example - before

Source: https://mailpit.axllent.org/docs/configuration/smtp-forward

Example of the original From header before applying the override-from option. This is shown as the input that gets changed.

```text
From: "Original Recipient" <original@example.com>

```

--------------------------------

### Override From example - after

Source: https://mailpit.axllent.org/docs/configuration/smtp-forward

Example of the headers after applying the override-from option. The From address is replaced and an X-Original-From header is added.

```text
X-Original-From: original@example.com
From: "Original Recipient" <me@mydomain.com>

```

--------------------------------

### Install with GITHUB_TOKEN

Source: https://mailpit.axllent.org/docs/install

Sets the GITHUB_TOKEN environment variable to use a GitHub token during installation.

```bash
sudo GITHUB_TOKEN="your_token_here" sh < <(curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh)

```

--------------------------------

### Install via script (Linux & Mac)

Source: https://mailpit.axllent.org/docs/install

Installs Mailpit directly to /usr/local/bin/mailpit using the official install script.

```bash
sudo sh < <(curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh)

```

--------------------------------

### Start Mailpit systemd service

Source: https://mailpit.axllent.org/docs/install/systemd

Starts the mailpit service immediately.

```bash
systemctl start mailpit.service

```

--------------------------------

### Install with custom INSTALL_PATH

Source: https://mailpit.axllent.org/docs/install

Sets the INSTALL_PATH environment variable to change the installation directory from the default /usr/local/bin.

```bash
sudo INSTALL_PATH=/usr/bin sh < <(curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh)

```

--------------------------------

### Start the service with supervisorctl update

Source: https://mailpit.axllent.org/docs/install/supervisor

Runs supervisorctl update to start the Mailpit service.

```bash
supervisorctl update

```

--------------------------------

### Start Mailpit with STARTTLS using environment variables

Source: https://mailpit.axllent.org/docs/configuration/smtp

Equivalent to the CLI flags, using environment variables MP_SMTP_TLS_CERT and MP_SMTP_TLS_KEY.

```bash
MP_SMTP_TLS_CERT=/path/to/cert.pem MP_SMTP_TLS_KEY=/path/to/key.pem

```

--------------------------------

### Install and build JavaScript assets with npm

Source: https://mailpit.axllent.org/docs/development/getting-started

Run these commands in the top-level project folder to install dependencies and compile the frontend assets. Mailpit does not include precompiled JavaScript in the source.

```bash
npm install
npm run build

```

--------------------------------

### Start Mailpit with Unix sockets for HTTP and SMTP

Source: https://mailpit.axllent.org/docs/configuration/unix-domain-sockets

Starts Mailpit listening on Unix sockets for both HTTP and SMTP. The `--listen` and `--smtp` flags use `unix:<path>:<permissions>` syntax. Permissions `666` allow global read/write access to the socket files, provided the process has read/execute access to the parent directory.

```bash
mailpit --listen unix:/var/run/mailpit/http.sock:666 --smtp unix:/var/run/mailpit/smtp.sock:666

```

--------------------------------

### Install Node modules for the Mailpit web UI

Source: https://mailpit.axllent.org/docs/install/source

Installs the required Node.js modules for building the Mailpit web user interface. Run in the project's root directory.

```bash
npm install

```

--------------------------------

### Start Mailpit with STARTTLS using CLI flags

Source: https://mailpit.axllent.org/docs/configuration/smtp

Provide a TLS certificate and key via command flags to enable STARTTLS. The server accepts both plain text and STARTTLS connections.

```bash
mailpit --smtp-tls-cert /path/to/cert.pem --smtp-tls-key /path/to/key.pem

```

--------------------------------

### Enable Mailpit systemd service

Source: https://mailpit.axllent.org/docs/install/systemd

Enables the mailpit service to start at boot. The output shows the symlink created for multi-user.target.

```bash
systemctl enable mailpit.service
Created symlink /etc/systemd/system/multi-user.target.wants/mailpit.service → /etc/systemd/system/mailpit.service.

```

--------------------------------

### Start Mailpit with SSL/TLS using CLI flags

Source: https://mailpit.axllent.org/docs/configuration/smtp

Add --smtp-require-tls to require all communication over TLS. This disables STARTTLS support entirely.

```bash
mailpit --smtp-tls-cert /path/to/cert.pem --smtp-tls-key /path/to/key.pem --smtp-require-tls

```

--------------------------------

### SMTP relay configuration YAML example

Source: https://mailpit.axllent.org/docs/configuration/smtp-relay

Example YAML configuration for SMTP relaying. All options are optional except 'host'. The 'auth' option defaults to 'none', and 'username' is required for plain, login, and cram-md5 auth. 'password' is required for plain and login auth, while 'secret' is required for cram-md5 auth. 'starttls', 'tls', 'allow-insecure', 'preserve-message-ids', and 'forward-smtp-errors' default to false.

```yaml
host: <hostname-or-ip> # required - SMTP host or IP to send via
port: <port> # optional - SMTP port, default 25
starttls: <true|false> # optional - connect using STARTTLS, default false
tls: <true|false> # optional - connect using TLS, default false
allow-insecure: <true|false> # optional - do not validate TLS certificate, default false
auth: <none|plain|login|cram-md5> # optional - default none
username: <username> # required for plain, login and cram-md5 auth
password: <password> # required for plain & login auth
secret: <cram-secret> # required for cram-md5 auth
return-path: <bounce-address> # optional - overrides Return-Path for all released emails
override-from: <email-address> # optional - overrides the From email address
allowed-recipients: '@example\.com$' # optional - limit allowed relay addresses or domains
blocked-recipients: '@example2\.com$' # optional - prevent relating to addresses or domains
preserve-message-ids: <true|false> # optional - preserve the original Message-IDs when relaying, default false
forward-smtp-errors: <true|false> # optional - whether to log smtp-errors or forward them to upstream-client
```

--------------------------------

### Override From example: changing From header

Source: https://mailpit.axllent.org/docs/configuration/smtp-relay

Shows how Mailpit changes the From header when override-from is set. The original From email address is replaced with the configured address, and the original is stored in X-Original-From.

```text
From: "Original Recipient" <original@example.com>

```

```text
X-Original-From: original@example.com
From: "Original Recipient" <me@mydomain.com>

```

--------------------------------

### X-Tags header example

Source: https://mailpit.axllent.org/docs/usage/tagging

Example of an X-Tags message header that Mailpit uses to apply tags. Tags are comma-separated.

```text
X-Tags: Tag 1, Tag 2, hostname

```

--------------------------------

### Run Mailpit with Docker

Source: https://mailpit.axllent.org/docs/install/docker

Basic Docker run command to start Mailpit, mapping the default web UI port (8025) and SMTP port (1025).

```bash
docker run -d \
--restart unless-stopped \
--name=mailpit \
-p 8025:8025 \
-p 1025:1025 \
axllent/mailpit
```

--------------------------------

### Docker Compose example

Source: https://mailpit.axllent.org/docs/install/docker

Docker Compose service definition for Mailpit, exposing web UI (8025) and SMTP (1025) ports, with environment variables for message limits and SMTP authentication.

```yaml
services:
    mailpit:
        image: axllent/mailpit
        container_name: mailpit
        restart: unless-stopped
        volumes:
            - ./data:/data
        ports:
            - 8025:8025
            - 1025:1025
        environment:
            MP_MAX_MESSAGES: 5000
            MP_DATABASE: /data/mailpit.db
            MP_SMTP_AUTH_ACCEPT_ANY: 1
            MP_SMTP_AUTH_ALLOW_INSECURE: 1
```

--------------------------------

### Websocket 'new' message example

Source: https://mailpit.axllent.org/docs/api-v1/websocket

When a new message is received, the websocket broadcasts a Type 'new' with Data as a message summary. This example shows the full structure including fields like ID, MessageID, From, To, Subject, and Snippet.

```json
{
    "Type": "new",
    "Data": {
        "ID": "YsABjkFERuPyq8XC6WaKs2",
        "MessageID": "LDBnLCzbh3LQGbHb6d2B8H@mailpit",
        "Read": false,
        "From": {
            "Name": "Mailpit",
            "Address": "mailpit@example.com"
        },
        "To": [
            {
                "Name": "Test user",
                "Address": "test@example.com"
            }
        ],
        "Cc": [],
        "Bcc": [
            {
                "Name": "",
                "Address": "test@test"
            }
        ],
        "ReplyTo": [],
        "Subject": "Hello from Mailpit SMTP API!",
        "Created": "2025-03-08T23:58:34.665934146+13:00",
        "Tags": [],
        "Size": 935,
        "Attachments": 0,
        "Snippet": "Mailpit is a small, fast, low memory, zero-dependency, multi-platform email testing tool \u0026 API for developers."
    }
}
```

--------------------------------

### GET /readyz

Source: https://mailpit.axllent.org/docs/integration/healthcheck

Readiness probe endpoint that returns a 200 response when Mailpit is running correctly. Used to indicate that the service is ready to receive traffic.

```APIDOC
## GET /readyz

### Description
Readiness probe endpoint that returns a 200 response when Mailpit is running correctly. Used to indicate that the service is ready to receive traffic.

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
Returns a 200 status code when Mailpit is running correctly.

```

--------------------------------

### Start Mailpit with allowed hosts for DNS rebinding mitigation

Source: https://mailpit.axllent.org/docs/configuration/http

Use the --allowed-hosts flag to specify a comma-separated list of hostnames expected in the Host header. Requests with a Host outside this list are rejected with 403 Forbidden. Entries with ports match exactly; entries without ports match any port. Loopback and raw IP addresses are always allowed.

```bash
mailpit --allowed-hosts "mailpit.example.com,mailpit.internal:8025"
```

--------------------------------

### Start Mailpit with CORS allowed origin including port

Source: https://mailpit.axllent.org/docs/configuration/http

Include the port number in the hostname when configuring CORS for origins that use a non-default port.

```bash
mailpit --api-cors "example.com:8080"
```

--------------------------------

### Start Mailpit with CORS allowed origins

Source: https://mailpit.axllent.org/docs/configuration/http

Use the --api-cors flag to allow requests from specific origins. Hostnames must be comma-separated and include port numbers if needed. Setting to '*' allows any origin and port, but this is risky.

```bash
mailpit --api-cors "example.com,anotherdomain.com"
```

--------------------------------

### GET /livez

Source: https://mailpit.axllent.org/docs/integration/healthcheck

Liveness probe endpoint that returns a 200 response when Mailpit is running correctly. Used to indicate that the service is alive.

```APIDOC
## GET /livez

### Description
Liveness probe endpoint that returns a 200 response when Mailpit is running correctly. Used to indicate that the service is alive.

### Method
GET

### Endpoint
/livez

### Response
#### Success Response (200)
Returns a 200 status code when Mailpit is running correctly.

```

--------------------------------

### Caddy subdirectory proxy configuration for Mailpit

Source: https://mailpit.axllent.org/docs/configuration/proxy

Caddy configuration to proxy Mailpit under a subdirectory (/mailpit/), including a redirect and path rewriting. Start Mailpit with --webroot /mailpit/ to match.

```caddy
localhost:80 {
    redir /mailpit /mailpit/
    handle_path /mailpit/* {
        rewrite * /mailpit{path}
        reverse_proxy 172.17.0.1:8025 {
            header_up Host {host}
        }
    }
}

```

--------------------------------

### Caddy reverse proxy configuration for Mailpit

Source: https://mailpit.axllent.org/docs/configuration/proxy

Caddy configuration to reverse proxy to Mailpit at 172.17.0.1:8025, preserving the Host header. This is the basic setup for the root path.

```caddy
localhost:80 {
    reverse_proxy 172.17.0.1:8025 {
        header_up Host {host}
    }
}

```

--------------------------------

### Verify Mailpit systemd service status

Source: https://mailpit.axllent.org/docs/install/systemd

Shows the status of the mailpit service, including active state, PID, memory usage, and recent log entries. The example output indicates the service is running and listening on ports 1025 (SMTP) and 8025 (HTTP).

```bash
systemctl status mailpit.service
● mailpit.service - Mailpit server
     Loaded: loaded (/etc/systemd/system/mailpit.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2023-12-08 16:46:29 NZDT; 6s ago
   Main PID: 41913 (mailpit)
      Tasks: 10 (limit: 18768)
     Memory: 3.3M
        CPU: 27ms
     CGroup: /system.slice/mailpit.service
             └─41913 /usr/local/bin/mailpit -d /tmp/mailpit.db

Dec 08 16:46:29 mailpit systemd[1]: Started Mailpit server.
Dec 08 16:46:29 mailpit mailpit[41913]: INFO[2023/12/08 16:46:29] [smtpd] starting on [::]:1025
Dec 08 16:46:29 mailpit mailpit[41913]: INFO[2023/12/08 16:46:29] [http] starting on [::]:8025
Dec 08 16:46:29 mailpit mailpit[41913]: INFO[2023/12/08 16:46:29] [http] accessible via http://localhost:8025/

```

--------------------------------

### Websocket message envelope format

Source: https://mailpit.axllent.org/docs/api-v1/websocket

The websocket broadcasts JSON objects with a Type string and a Data object. The Type can be 'stats', 'update', 'delete', or 'new'. This example shows the general envelope structure.

```json
{
    "Type": "<string>",
    "Data": <object>
}
```

--------------------------------

### nginx proxy configuration for Mailpit

Source: https://mailpit.axllent.org/docs/configuration/proxy

Configure nginx to proxy requests to Mailpit at http://172.17.0.1:8025, preserving the original Host header and enabling websocket support. Adjust the proxy_pass address to match your setup.

```nginx
server {
    listen       80;
    server_name  localhost;

    location / {
        proxy_set_header Host $http_host; # preserve original host header
        proxy_pass http://172.17.0.1:8025; # internal Mailpit address

        # configure the websocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

```

--------------------------------

### Require STARTTLS with environment variable

Source: https://mailpit.axllent.org/docs/configuration/smtp

Environment variable equivalent to the --smtp-require-starttls flag.

```bash
MP_SMTP_REQUIRE_STARTTLS=true

```

--------------------------------

### Configure send API authentication via environment variables

Source: https://mailpit.axllent.org/docs/configuration/http

Set environment variables to configure send API authentication. MP_SEND_API_AUTH_FILE specifies a password file, MP_SEND_API_AUTH provides credentials directly as a space-separated list, and MP_SEND_API_AUTH_ACCEPT_ANY accepts any credentials. Note that --send-api-auth-file and --send-api-auth-accept-any cannot be used together.

```bash
# Set dedicated send API endpoint credentials
MP_SEND_API_AUTH_FILE=/path/to/send-api-password-file

# Or provide credentials directly (space-separated list)
MP_SEND_API_AUTH="senduser1:password1 senduser2:password2"

# Or accept any credentials for Send API
MP_SEND_API_AUTH_ACCEPT_ANY=true
```

--------------------------------

### Enable the service with supervisorctl reread

Source: https://mailpit.axllent.org/docs/install/supervisor

Runs supervisorctl reread to make supervisor aware of the new configuration file.

```bash
supervisorctl reread

```

--------------------------------

### Enable Prometheus metrics in integrated mode

Source: https://mailpit.axllent.org/docs/configuration/prometheus

Serve metrics on the main web UI port at /metrics, inheriting TLS and authentication. Use either the command-line flag or the MP_ENABLE_PROMETHEUS environment variable.

```bash
# Using command line flag
mailpit --enable-prometheus true

# Using environment variable
export MP_ENABLE_PROMETHEUS=true
mailpit

```

--------------------------------

### Require STARTTLS with CLI flag

Source: https://mailpit.axllent.org/docs/configuration/smtp

Add --smtp-require-starttls to force clients to use STARTTLS. The environment variable equivalent is MP_SMTP_REQUIRE_STARTTLS=true.

```bash
--smtp-require-starttls

```

--------------------------------

### Add basic authentication with password file

Source: https://mailpit.axllent.org/docs/configuration/http

Run Mailpit with the --ui-auth-file flag to enable basic authentication using a password file. The environment variable MP_UI_AUTH_FILE can be used instead.

```bash
mailpit --ui-auth-file /path/to/password-file
```

--------------------------------

### Enable HTTPS with SSL certificate and key

Source: https://mailpit.axllent.org/docs/configuration/http

Run Mailpit with the --ui-tls-cert and --ui-tls-key flags to enable HTTPS for the web UI and API. Both the certificate and private key must be provided.

```bash
mailpit --ui-tls-cert /path/to/cert.pem --ui-tls-key /path/to/key.pem
```

--------------------------------

### Accept any SMTP credentials

Source: https://mailpit.axllent.org/docs/configuration/smtp

Use --smtp-auth-accept-any to accept any username and password (or none) for testing.

```bash
--smtp-auth-accept-any

```

--------------------------------

### Build the Mailpit web UI

Source: https://mailpit.axllent.org/docs/install/source

Builds the Mailpit web UI. An alternative watch command, `npm run watch`, automatically rebuilds the HTML/CSS/JS on changes, but Mailpit must be restarted (`go run .`) and the browser refreshed to see changes.

```bash
npm run build

```

--------------------------------

### Create email.txt with test email content

Source: https://mailpit.axllent.org/docs/install/testing

Create a text file named email.txt with the email headers and body. This file is used as input for the sendmail commands.

```text
From: sender@example.com
To: recipient@example.com
Subject: Email Subject

This is the body of the email.
It can contain multiple lines of text.

```

--------------------------------

### Set SMTP authentication password file via environment

Source: https://mailpit.axllent.org/docs/configuration/smtp

Environment variable equivalent to the --smtp-auth-file flag.

```bash
MP_SMTP_AUTH_FILE=<file>

```

--------------------------------

### Enable Prometheus metrics in separate server mode

Source: https://mailpit.axllent.org/docs/configuration/prometheus

Run a dedicated metrics server on a custom port without TLS or authentication. Use either the command-line flag with a custom listen address or the MP_ENABLE_PROMETHEUS environment variable.

```bash
# Custom listen address for separate server
mailpit --enable-prometheus 0.0.0.0:9091

# Using environment variable
export MP_ENABLE_PROMETHEUS="0.0.0.0:9091"
mailpit

```

--------------------------------

### Go linting with gofmt

Source: https://mailpit.axllent.org/docs/development/code-linting

Run gofmt with -s, -l, and -d flags to check Go code formatting. This is the same check used in CI before merging.

```bash
gofmt -s -l -d .
```

--------------------------------

### Build the Mailpit binary

Source: https://mailpit.axllent.org/docs/install/source

Builds the Mailpit binary after the assets are compiled. The `-ldflags "-s -w"` flags strip debug information.

```bash
go build -ldflags "-s -w"

```

--------------------------------

### Create supervisor service configuration file mailpit.ini

Source: https://mailpit.axllent.org/docs/install/supervisor

Supervisor configuration for Mailpit. Sets the command to run Mailpit with a database at /var/lib/mailpit/mailpit.db, runs as user mailpit, and enables auto-start and auto-restart. Includes commented environment variables for SMTP relay.

```ini
[program:mailpit]

[Service]
command=/usr/local/bin/mailpit -d /var/lib/mailpit/mailpit.db
user=mailpit
numprocs=1
startsecs=0
autostart=true
autorestart=true
startretries=10
process_name=%(program_name)s_%(process_num)02d

# define your environments
# environment=MP_SMTP_RELAY_HOST="/path/to/your/smtp-relay.conf",MP_SMTP_RELAY_PORT="587"

```

--------------------------------

### Build a stand-alone sendmail binary

Source: https://mailpit.axllent.org/docs/install/source

Builds a stand-alone sendmail binary from the sendmail directory. This is optional and not intended for use with anything other than Mailpit.

```bash
cd sendmail
go build -ldflags "-s -w"

```

--------------------------------

### Create systemd service file for Mailpit

Source: https://mailpit.axllent.org/docs/install/systemd

Service unit file for Mailpit, placed at /etc/systemd/system/mailpit.service. Runs Mailpit with a database at /var/lib/mailpit/mailpit.db as user and group 'mailpit', with automatic restart after 10 seconds on crash. The database must be readable/writable by the service user.

```ini
[Unit]
Description=Mailpit server

[Service]
ExecStart=/usr/local/bin/mailpit -d /var/lib/mailpit/mailpit.db
Restart=always
# Restart service after 10 seconds if service crashes
RestartSec=10
SyslogIdentifier=mailpit
User=mailpit
Group=mailpit

[Install]
WantedBy=multi-user.target

```

--------------------------------

### Run Mailpit with environment variables

Source: https://mailpit.axllent.org/docs/install/docker

Docker run command that sets Mailpit options via environment variables, including MP_DATABASE, MP_UI_AUTH_FILE, and TZ, and mounts a data volume.

```bash
docker run -d \
--name=mailpit \
--restart unless-stopped \
-v /path/to/mailpit-data:/data \
-e MP_DATABASE=/data/mailpit.db \
-e MP_UI_AUTH_FILE=/data/authfile \
-e TZ=Europe/London \
-p 8025:8025 \
-p 1025:1025 \
axllent/mailpit
```

--------------------------------

### Generate Swagger spec with Docker

Source: https://mailpit.axllent.org/docs/development/swagger

Runs go-swagger in a Docker container to generate the Swagger JSON file. Uses a self-created Docker image for consistency. The command mounts the current directory and writes the output to ./server/ui/api/v1/swagger.json.

```bash
docker run --rm -it \
    -u $(shell id -u):$(shell id -g) \
    -v "${PWD}:/source" \
    axllent/go-swagger generate spec -m -i ./server/apiv1/swagger-config.yml \
    -o ./server/ui/api/v1/swagger.json

```

--------------------------------

### Allow insecure SMTP authentication via environment

Source: https://mailpit.axllent.org/docs/configuration/smtp

Environment variable equivalent to the --smtp-auth-allow-insecure flag.

```bash
MP_SMTP_AUTH_ALLOW_INSECURE=true

```

--------------------------------

### Send test email using system sendmail

Source: https://mailpit.axllent.org/docs/install/testing

If using a system-installed sendmail, use this command with the -t and -S flags to specify the Mailpit server. Note that different sendmail implementations may vary.

```bash
sendmail -t -S localhost:1025 < email.txt

```

--------------------------------

### Vue/JavaScript linting with npm run lint

Source: https://mailpit.axllent.org/docs/development/code-linting

Run ESLint and Prettier checks for Vue/JavaScript code. This command checks for warnings and errors.

```bash
npm run lint
```

--------------------------------

### Vue/JavaScript linting with npm run lint-fix

Source: https://mailpit.axllent.org/docs/development/code-linting

Automatically fix some warnings in Vue/JavaScript code using ESLint and Prettier.

```bash
npm run lint-fix
```

--------------------------------

### Run Mailpit in development with go run .

Source: https://mailpit.axllent.org/docs/development/getting-started

Runs the application directly from the project folder without building a binary each time. You can append Mailpit arguments, such as go run . -h. Restart Mailpit after modifying Go code or recompiling JavaScript assets.

```bash
go run .

```

--------------------------------

### Require TLS with environment variable

Source: https://mailpit.axllent.org/docs/configuration/smtp

Environment variable equivalent to the --smtp-require-tls flag.

```bash
MP_SMTP_REQUIRE_TLS=true

```

--------------------------------

### Set tag filters using --tag

Source: https://mailpit.axllent.org/docs/usage/tagging

Command-line option to set tag filters using a space-separated string format. Tags are comma-separated for multiple tags per match.

```bash
--tag 'user=user@example.com user2=from:user2@example.com "Scanned with antivirus"="X-Antivirus: " "Exact phrase"='"the quoted phrase'"'

```

--------------------------------

### SMTP forward configuration YAML

Source: https://mailpit.axllent.org/docs/configuration/smtp-forward

YAML configuration file for SMTP forwarding. Required fields are 'to' and 'host'. Optional fields include port, starttls, tls, allow-insecure, auth, username, password, secret, return-path, override-from, and forward-smtp-errors. Defaults: port 25, starttls false, tls false, allow-insecure false, auth none.

```yaml
to: <email-address> # required - comma-separated list of email addresses
host: <hostname-or-ip> # required - SMTP host or IP to send via
port: <port> # optional - SMTP port, default 25
starttls: <true|false> # optional - connect using STARTTLS, default false
tls: <true|false> # optional - connect using TLS, default false
allow-insecure: <true|false> # optional - do not validate TLS certificate, default false
auth: <none|plain|login|cram-md5> # optional - default none
username: <username> # required for plain, login and cram-md5 auth
password: <password> # required for plain & login auth
secret: <cram-secret> # required for cram-md5 auth
return-path: <bounce-address> # optional - overrides Return-Path for all forwarded emails
override-from: <email-address> # optional - overrides the From email address
forward-smtp-errors: <true|false> # optional - whether to log smtp-errors or forward them to upstream-client

```

--------------------------------

### Webhook Configuration

Source: https://mailpit.axllent.org/docs/integration/webhook

Configuration options for setting up a webhook URL, rate limiting, and delay for Mailpit's webhook feature.

```APIDOC
## Webhook Configuration

### Description
Mailpit can be configured to send a JSON POST to a specified webhook URL whenever a message is received. The webhook payload contains a message summary. Configuration is done via command-line options or environment variables.

### Configuration Options

#### Webhook URL
- **Option**: `--webhook-url <URL>`
- **Environment Variable**: `MP_WEBHOOK_URL=<url>`
- **Description**: Sets the URL to which Mailpit will send a JSON POST with the message summary.

#### Rate Limit
- **Option**: `--webhook-limit <seconds>`
- **Environment Variable**: `MP_WEBHOOK_LIMIT=<seconds>`
- **Description**: Sets the minimum interval (in seconds) between webhook calls. Default is 1 second. Set to 0 to disable rate limiting.

#### Delay
- **Option**: `--webhook-delay <seconds>`
- **Environment Variable**: `MP_WEBHOOK_DELAY=<seconds>`
- **Description**: Adds a delay (in seconds) before each webhook call.

### Notes
- Basic authentication can be used by including credentials in the webhook URL (e.g., `https://user:password@example.com/webhook`).
- Only received messages trigger the webhook; deleted messages do not.
- The JSON payload contains only the message summary and cannot be modified.
- Failed webhook calls are not retried.
- If a Mailpit label is specified, a `Mailpit-Label` header is automatically added to the webhook request.

### Request
Mailpit sends a JSON POST to the configured webhook URL. The request body contains a message summary (see Response -> Schema).

### Response
#### Success Response
- **Status Code**: 200 (implied)
- **Body**: The webhook endpoint should return a success status to acknowledge receipt.

#### Response Schema
The response schema is not explicitly documented in the source. The webhook payload is described as a "message summary" but the exact schema is not provided.
```

--------------------------------

### Generate self-signed certificate with SAN extension

Source: https://mailpit.axllent.org/docs/configuration/certificates

Appends the -addext option to include a Subject Alt Name (SAN) matching the hostname, required by some SMTP clients.

```bash
openssl req -x509 -newkey rsa:4096 \
-nodes -keyout key.pem -out cert.pem \
-sha256 -days 3650 \
-addext "subjectAltName = DNS:localhost"

```

--------------------------------

### Send test email via Docker exec

Source: https://mailpit.axllent.org/docs/install/testing

When running Mailpit in Docker, pipe email.txt into the container using docker exec. Replace <container> with your container name or ID. The -i flag is required to pass file contents via stdin.

```bash
docker exec -i <container> sendmail < email.txt

```

--------------------------------

### Clone the Mailpit repository

Source: https://mailpit.axllent.org/docs/install/source

Clones the Mailpit source repository and changes into its root directory. Requires Go (>= version 1.24) and npm to compile Mailpit.

```bash
git clone git@github.com:axllent/mailpit.git
cd mailpit

```

--------------------------------

### Set SMTP authentication password file

Source: https://mailpit.axllent.org/docs/configuration/smtp

Use --smtp-auth-file to specify a password file. Mailpit accepts PLAIN or LOGIN authentication mechanisms.

```bash
--smtp-auth-file <file>

```

--------------------------------

### Send test email using mailpit sendmail

Source: https://mailpit.axllent.org/docs/install/testing

Run the mailpit sendmail command with email.txt as input. This sends the email to Mailpit on the default port 1025.

```bash
mailpit sendmail < email.txt

```

--------------------------------

### Configure sendmail_path in php.ini for Mailpit

Source: https://mailpit.axllent.org/docs/install/sendmail

Sets Mailpit's sendmail as the sendmail path in php.ini. Requires the mailpit binary in /usr/local/bin and defaults to delivering to localhost:1025.

```ini
sendmail_path = /usr/local/bin/mailpit sendmail
```

--------------------------------

### Environment variables for SMTP relay configuration

Source: https://mailpit.axllent.org/docs/configuration/smtp-relay

Lists all environment variables for configuring SMTP relay. Only MP_SMTP_RELAY_HOST is required; all others are optional. These options are not available as CLI flags for security reasons.

```bash
MP_SMTP_RELAY_HOST=<hostname-or-ip>                # required
MP_SMTP_RELAY_PORT=<port>                          # optional - default 25
MP_SMTP_RELAY_STARTTLS=<true|false>                # optional - connect using STARTTLS, default false
MP_SMTP_RELAY_TLS=<true|false>                     # optional - connect using TLS, default false
MP_SMTP_RELAY_ALLOW_INSECURE=<true|false>          # optional - do not validate TLS certificate, default false
MP_SMTP_RELAY_AUTH=<none|plain|login|cram-md5>     # optional - default none
MP_SMTP_RELAY_USERNAME=<username>                  # required for plain, login and cram-md5 auth
MP_SMTP_RELAY_PASSWORD=<password>                  # required for plain & login auth
MP_SMTP_RELAY_SECRET=<cram-secret>                 # required for cram-md5 auth
MP_SMTP_RELAY_RETURN_PATH=<bounce-address>         # optional - overrides Return-Path for all released emails
MP_SMTP_RELAY_OVERRIDE_FROM=<email-address>        # optional - overrides the From email address
MP_SMTP_RELAY_ALLOWED_RECIPIENTS="@example\.com$"  # optional - regex to limit allowed relay addresses or domains via web UI & API
MP_SMTP_RELAY_BLOCKED_RECIPIENTS="@example2\.com$" # optional - regex to prevent relaying to addresses or domains via web UI & API
MP_SMTP_RELAY_PRESERVE_MESSAGE_IDS=<true|false>    # optional - preserve the original Message-IDs when relaying, default false
MP_SMTP_RELAY_FWD_SMTP_ERRORS=<true|false>         # optional - whether to log smtp-errors or forward them to upstream-client

```

--------------------------------

### Auto-generate self-signed certificates with sans: syntax

Source: https://mailpit.axllent.org/docs/configuration/certificates

Uses the sans: syntax to auto-generate self-signed certificates for SMTP, HTTP, and POP3. The same sans configuration must be used for both public and private keys. Certificates update on every Mailpit restart.

```bash
mailpit --smtp-tls-cert sans:localhost --smtp-tls-key sans:localhost

```

--------------------------------

### Set SMTP credentials via environment variable

Source: https://mailpit.axllent.org/docs/configuration/smtp

Export MP_SMTP_AUTH with a space-separated list of credentials. This option is not available as a CLI flag.

```bash
MP_SMTP_AUTH="user1:password1 user2:password"

```

--------------------------------

### Verify Mailpit is running with supervisorctl status

Source: https://mailpit.axllent.org/docs/install/supervisor

Runs supervisorctl status to check that Mailpit is running.

```bash
supervisorctl status

```

--------------------------------

### Plain text password file

Source: https://mailpit.axllent.org/docs/configuration/passwords

Plain text password file format. Each line contains a username and password separated by a colon. The file can contain multiple users, and all users have access to the same Mailpit instance.

```text
user1:password1
user2:password2

```

--------------------------------

### Prometheus scrape configuration for integrated mode

Source: https://mailpit.axllent.org/docs/configuration/prometheus

Add this to prometheus.yml to scrape Mailpit metrics from the integrated mode endpoint at localhost:8025/metrics.

```yaml
scrape_configs:
    - job_name: "mailpit"
      static_configs:
          - targets: ["localhost:8025"]
      scrape_interval: 30s
      metrics_path: "/metrics"

```

--------------------------------

### Prometheus scrape configuration for separate server mode

Source: https://mailpit.axllent.org/docs/configuration/prometheus

Add this to prometheus.yml to scrape Mailpit metrics from the dedicated metrics server. Replace the target port with your custom port.

```yaml
scrape_configs:
    - job_name: "mailpit"
      static_configs:
          - targets: ["localhost:9091"] # Use your custom port
      scrape_interval: 30s
      metrics_path: "/metrics"

```

--------------------------------

### Dump messages from local database using mailpit dump --database

Source: https://mailpit.axllent.org/docs/usage/import-export

Exports messages directly from a local Mailpit database file. Requires direct access to the database and may cause temporary database locks. Use `--tenant-id` if the database uses a tenant ID.

```bash
mailpit dump --database <database-file> <output-folder>

```

--------------------------------

### Accept any credentials for send API via CLI flag

Source: https://mailpit.axllent.org/docs/configuration/http

Use the --send-api-auth-accept-any flag to bypass authentication for the send API endpoint only. Other API endpoints and the web UI still require proper authentication if configured.

```bash
mailpit --send-api-auth-accept-any
```

--------------------------------

### Configure dedicated send API credentials via CLI flag

Source: https://mailpit.axllent.org/docs/configuration/http

Use the --send-api-auth-file flag to specify a password file for the send API endpoint. When set, the send API requires these credentials, while other endpoints and the web UI follow standard UI authentication.

```bash
mailpit --send-api-auth-file /path/to/send-api-password-file
```

--------------------------------

### Generate self-signed certificate with openssl

Source: https://mailpit.axllent.org/docs/configuration/certificates

Generates a self-signed certificate and key valid for 10 years. Set the Common Name to the hostname used to access Mailpit (e.g., localhost).

```bash
openssl req -x509 -newkey rsa:4096 \
-nodes -keyout key.pem -out cert.pem \
-sha256 -days 3650

```

--------------------------------

### Tag filters YAML configuration

Source: https://mailpit.axllent.org/docs/usage/tagging

YAML configuration file structure for setting tag filters. Each filter has a match and tags, with tags comma-separated. Use double quotes for exact phrase matches.

```yaml
filters:
    # match all words (in any order)
    - match: search all words
      tags: Tag 1
    # match to test@example.com
    - match: addressed:test@example.com
      tags: Tag 2
    # match from@example.com and apply two tags
    - match: from:from@example.com
      tags: Tag 1, Tag 2
    # match exact phrase - note double quoting!
    - match: '"match this phrase"'
      tags: Exact phrase

```

--------------------------------

### Mailpit sendmail flags help output

Source: https://mailpit.axllent.org/docs/install/sendmail

Output of `mailpit sendmail -h`. Shows that most flags are ignored for compatibility; only -S and -f are meaningful.

```text
Usage: mailpit sendmail [flags] [recipients] < message

Flags:
  -S  string  SMTP server address (default "localhost:1025")
  -f  string  Set the envelope sender address (default "user@host")
  -bs         Handle SMTP commands on standard input
  -t          Ignored
  -i          Ignored
  -o          Ignored
  -v          Ignored
```

--------------------------------

### Send test email using telnet

Source: https://mailpit.axllent.org/docs/install/testing

Use telnet to send an email directly to Mailpit on port 1025. The command sends SMTP commands via a pipe to telnet.

```bash
{
  echo "EHLO localhost"
  echo "MAIL FROM: <from@example.com>"
  echo "RCPT TO: <recipient@example.com>"
  echo "DATA"
  echo "From: <from@example.com>"
  echo "To: <recipient@example.com>"
  echo "Subject: Your Subject"
  echo ""
  echo "Your message body"
  echo "."
  echo "QUIT"
} | telnet localhost 1025

```

--------------------------------

### Allow insecure SMTP authentication

Source: https://mailpit.axllent.org/docs/configuration/smtp

Use --smtp-auth-allow-insecure to allow authentication over plain text connections for testing purposes.

```bash
--smtp-auth-allow-insecure

```

--------------------------------

### Apache reverse proxy to Mailpit Unix socket

Source: https://mailpit.axllent.org/docs/configuration/unix-domain-sockets

Apache VirtualHost configuration for proxying to a Unix socket. Requires Apache >= 2.4.47 with `proxy` and `proxy_http` modules enabled. The syntax must include `|http://<anything>` (unused) and `upgrade=websocket` for websocket support.

```apache
<VirtualHost *:80>
    ServerName localhost

    ProxyPass "/" "unix:/var/run/mailpit/http.sock|http://ignore.this/" upgrade=websocket
</VirtualHost>

```

--------------------------------

### Apache proxy configuration for Mailpit

Source: https://mailpit.axllent.org/docs/configuration/proxy

Apache VirtualHost configuration to proxy requests to Mailpit, preserving the Host header and enabling websocket proxying. Requires the rewrite, proxy, proxy_http, and proxy_wstunnel modules.

```apache
<VirtualHost *:80>
    ServerName localhost

    ProxyPreserveHost On # preserve original host header
    ProxyPass "/" "http://172.17.0.1:8025/" # internal Mailpit address
    ProxyPassReverse "/" "http://172.17.0.1:8025/" # internal Mailpit address

    # configure the websocket
    RewriteEngine on
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://172.17.0.1:8025/$1" [P,L] # internal Mailpit address
</VirtualHost>

```

--------------------------------

### Encrypted password file with APR1Crypt

Source: https://mailpit.axllent.org/docs/configuration/passwords

Encrypted password file format using APR1Crypt (Apache MD5) hashes. Each line contains a username and an encrypted password separated by a colon. The same file can be reused for any of the services.

```text
user1:$apr1$rja5hy8u$0DN2pENpLk1d4BqgPEho61
user2:$apr1$asfohhn3$WXNtWWEnCMRFkI75J3exy1

```

--------------------------------

### Dump messages via network/API using mailpit dump --http

Source: https://mailpit.axllent.org/docs/usage/import-export

Exports all messages from a running Mailpit instance over HTTP. The `--http` flag must include the host and port, and should include the webroot if configured. Basic auth credentials can be supplied in the URL.

```bash
mailpit dump --http http://localhost:8025 <output-folder>

```

--------------------------------

### SMTP forward environment variables

Source: https://mailpit.axllent.org/docs/configuration/smtp-forward

Environment variables for configuring SMTP forwarding. Required: MP_SMTP_FORWARD_TO and MP_SMTP_FORWARD_HOST. Optional variables mirror the YAML options. These options are not available as CLI flags for security reasons.

```bash
MP_SMTP_FORWARD_TO=<email-address>                   # required - comma-separated list of email addresses top forward to
MP_SMTP_FORWARD_HOST=<hostname-or-ip>                # required - SMTP host or IP to send via
MP_SMTP_FORWARD_PORT=<port>                          # optional - default 25
MP_SMTP_FORWARD_STARTTLS=<true|false>                # optional - connect using STARTTLS, default false
MP_SMTP_FORWARD_TLS=<true|false>                     # optional - connect using TLS, default false
MP_SMTP_FORWARD_ALLOW_INSECURE=<true|false>          # optional - do not validate TLS certificate, default false
MP_SMTP_FORWARD_AUTH=<none|plain|login|cram-md5>     # optional - default none
MP_SMTP_FORWARD_USERNAME=<username>                  # required for plain, login and cram-md5 auth
MP_SMTP_FORWARD_PASSWORD=<password>                  # required for plain & login auth
MP_SMTP_FORWARD_SECRET=<cram-secret>                 # required for cram-md5 auth
MP_SMTP_FORWARD_RETURN_PATH=<bounce-address>         # optional - overrides Return-Path for all released emails
MP_SMTP_FORWARD_OVERRIDE_FROM=<email-address>        # optional - overrides the From email address
MP_SMTP_FORWARD_FWD_SMTP_ERRORS=<true|false>         # optional - whether to log smtp-errors or forward them to upstream-client

```

--------------------------------

### Auto-restart Mailpit on file changes with entr

Source: https://mailpit.axllent.org/docs/development/getting-started

Uses the entr tool to watch the listed directories and automatically restart Mailpit when any file changes are detected. Replace <options> with your desired Mailpit arguments.

```bash
find cmd/ config/ internal/ proxy/ sendmail/ server/ | entr -s -r 'go run . <options>'

```

--------------------------------

### Watch mode for JavaScript assets with npm run watch

Source: https://mailpit.axllent.org/docs/development/getting-started

Use this command to automatically rebuild assets when JavaScript or Vue files change. It does not reload the JavaScript in a running Mailpit instance, so you must manually restart Mailpit after recompiling.

```bash
npm run watch
```

--------------------------------

### Disable auto-tagging with --tags-disable

Source: https://mailpit.axllent.org/docs/usage/tagging

Disables auto-tagging for plus-addresses and x-tags. The option accepts a comma-separated list of types.

```bash
--tags-disable plus-addresses,x-tags

```

--------------------------------

### Nginx reverse proxy to Mailpit Unix socket

Source: https://mailpit.axllent.org/docs/configuration/unix-domain-sockets

Nginx server block that proxies HTTP requests to a Unix socket at `/var/run/mailpit/http.sock`. Includes websocket support via `proxy_http_version 1.1` and upgrade headers.

```nginx
server {
    listen       80;
    server_name  localhost;

    location / {
        proxy_pass http://unix:/var/run/mailpit/http.sock;

        # enable the websocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

```

--------------------------------

### Send mail via Unix socket with Mailpit sendmail

Source: https://mailpit.axllent.org/docs/configuration/unix-domain-sockets

Uses Mailpit's sendmail command to send a message via a Unix socket. The `-S unix:<path>` flag sets the SMTP server address to the socket.

```bash
mailpit sendmail -S unix:/var/run/mailpit/smtp.sock < message

```

--------------------------------

### Stop Mailpit systemd service

Source: https://mailpit.axllent.org/docs/install/systemd

Stops the mailpit service.

```bash
systemctl stop mailpit.service

```

--------------------------------

### Symfony mailer DSN for Mailpit Unix socket

Source: https://mailpit.axllent.org/docs/configuration/unix-domain-sockets

Environment variable `MAILER_DSN` for Symfony mailer to use Mailpit's sendmail with a Unix socket. The command is URL-encoded: `mailpit%20sendmail%20-S%20unix:/var/run/mailpit/smtp.sock%20-bs`.

```env
MAILER_DSN="sendmail://default?command=mailpit%20sendmail%20-S%20unix:/var/run/mailpit/smtp.sock%20-bs"

```
Tokens:
Raw