Runtime options

--databaseMP_DATABASE

Specify the local database filename to store persistent data. The default is a local temporary file which is auto-deleted when Mailpit exits. You can optionally use a remote rqlite database by specifying a “http address” (see docs).

--disable-walMP_DISABLE_WALfalse v1.23.0

Disable Write-Ahead Logging (WAL) support for local database. WAL (enabled by default) provides better performance, however is not compatible with network file systems such as NFS or Samba. Set this option if you intend to use persistent storage on a network volume.

--disable-version-checkMP_DISABLE_VERSION_CHECKfalse v1.26.2

Disable Mailpit’s automatic version checking. When enabled, Mailpit will not contact GitHub to check for new releases.

--disable-auto-vacuumMP_DISABLE_AUTO_VACUUMfalse v1.29.5

Disable automatic VACUUMing of the local SQLite database. This is not recommended as it may lead to increased database file size and reduced performance over time (see docs).

--compressionMP_COMPRESSION1 v1.23.0

Compression level to store raw messages in the database (0-3) (see docs.)

--labelMP_LABEL

Set an optional label to identify this Mailpit instance. This adds the label to the web UI, SMTP and POP3 servers.

--tenant-idMP_TENANT_ID

Set a tenant ID (table prefix). This is used to isolate the data from other Mailpit instances sharing the same data file (see docs).

--maxMP_MAX_MESSAGES500

Maximum number of messages to store. Mailpit will periodically delete the oldest messages if greater than this. Set to 0 to disable auto-deletion (see docs).

--max-ageMP_MAX_AGE

Maximum age of messages to store in either (h)ours or (d)ays. Mailpit will periodically delete the oldest messages if greater than this. The value must be either in hours (eg: --max-age 36h) or days (eg: --max-age 14d) (see docs).

--max-message-sizeMP_MAX_MESSAGE_SIZE50 v1.30.0

Maximum size in MB of messages to accept via SMTP & API. Messages larger than this will be rejected.

--use-message-datesMP_USE_MESSAGE_DATESfalse

Use message header date as the Mailpit received date & time instead of the SMTP-received date & time.

--ignore-duplicate-idsMP_IGNORE_DUPLICATE_IDSfalse

Ignore duplicate messages based on Message-Ids.

--log-fileMP_LOG_FILE

Log Mailpit output to file instead of stdout. eg: --log-file /path/to/logfile.log

--quietMP_QUIETfalse

Quiet logging (errors only)

--verboseMP_VERBOSEfalse

Verbose logging (debug)

--listenMP_UI_BIND_ADDR0.0.0.0:8025

HTTP bind interface and port for UI.

--webrootMP_WEBROOT/

Set the webroot for web UI & API, for example mail would result in http://0.0.0.0:8025/mail/.

--ui-auth-fileMP_UI_AUTH_FILE

Specify a password file for web UI & API basic authentication (see docs).

--ui-tls-certMP_UI_TLS_CERT

TLS certificate for web UI & API (ie: HTTPS). This option requires the --ui-tls-key argument or MP_UI_TLS_KEY environment variable to be set.

--ui-tls-keyMP_UI_TLS_KEY

TLS key for web UI & API (ie: HTTPS). This option requires the --ui-tls-cert argument or MP_UI_TLS_CERT environment variable to be set.

--api-corsMP_API_CORS

Specify one or more hosts for CORS Access-Control-Allow-Origin to permit cross-domain browser requests to the API (see docs).

--block-remote-css-and-fontsMP_BLOCK_REMOTE_CSS_AND_FONTSfalse

Block all browser access to remote CSS and fonts imported via message stylesheets. Mailpit uses the HTTP Content Security Policy (CSP) method to block these. This does not block remote images or clicking on external links.

--allow-internal-http-requestsMP_ALLOW_INTERNAL_HTTP_REQUESTSfalse v1.29.2

Allow Link Check, HTML Check and UI Screenshot to access internal (non-public) IPs when checking links or fetching remote assets (images, stylesheets, etc.). This is required for those features to work in test environments that use internal hostnames or IPs. Use caution in production - enabling this could allow SSRF (Server‑Side Request Forgery) if your Mailpit UI or SMTP are reachable by untrusted users.

--disable-link-check-rate-limitMP_DISABLE_LINK_CHECK_RATE_LIMITfalse v1.30.3

Disable the rate limit for link checking (see docs).

--enable-spamassassinMP_ENABLE_SPAMASSASSINfalse

Enable SpamAssassin integration for message spamminess score (see docs).

--allow-untrusted-tlsMP_ALLOW_UNTRUSTED_TLSfalse

Do not verify HTTPS certificates for either link checker & screenshot generation.

--disable-http-compressionMP_DISABLE_HTTP_COMPRESSIONfalse

Disable HTTP compression support in the web UI and API (see docs).

--hide-delete-all-buttonMP_HIDE_DELETE_ALL_BUTTONfalse v1.25.0

Hides the “Delete all” button in the web UI. This can be useful if you explicitly do not want your users to use this feature (see docs).

--send-api-auth-fileMP_SEND_API_AUTH_FILE v1.26.0

Specify a password file for Send API authentication (see docs). This provides separate authentication credentials specifically for the /api/v1/send endpoint.

--send-api-auth-accept-anyMP_SEND_API_AUTH_ACCEPT_ANYfalse v1.26.0

Accept any username and password for the Send API endpoint, including none (see docs). This option cannot be used together with --send-api-auth-file.

--smtpMP_SMTP_BIND_ADDR0.0.0.0:1025

SMTP bind interface and port.

--smtp-auth-fileMP_SMTP_AUTH_FILE

Specify a password file for SMTP authentication (see docs).

--smtp-auth-accept-anyMP_SMTP_AUTH_ACCEPT_ANYfalse

Accept any SMTP username and password, including none. Use this to basically allow anything.

--smtp-tls-certMP_SMTP_TLS_CERT

TLS certificate for SMTP STARTTLS. This option requires the --smtp-tls-key argument or MP_SMTP_TLS_KEY environment variable to be set.

--smtp-tls-keyMP_SMTP_TLS_KEY

TLS key for SMTP STARTTLS. This option requires the --smtp-tls-cert argument or MP_SMTP_TLS_CERT environment variable to be set.

--smtp-require-starttlsMP_SMTP_REQUIRE_STARTTLSfalse

Require all SMTP clients to use STARTTLS encryption. If set to true, the only allowed commands are NOOP, EHLO, STARTTLS and QUIT (as specified in RFC 4954) until the connection is upgraded to STARTTLS.

--smtp-require-tlsMP_SMTP_REQUIRE_TLSfalse

Require all SMTP clients to use SSL/TLS encryption. If set to true, all connections to the SMTP server must be handled over TLS. This is different to STARTTLS which requires the initial connection to be unencrypted. Note that this option disables STARTTLS and may reduce client compatibility.

--smtp-auth-allow-insecureMP_SMTP_AUTH_ALLOW_INSECUREfalse

Typically either STARTTLS or TLS is enforced for all SMTP authentication. This option allows insecure PLAIN & LOGIN SMTP authentication when using STARTTLS.

--smtp-strict-rfc-headersMP_SMTP_STRICT_RFC_HEADERSfalse

Force Mailpit to return an SMTP error if message headers contain \n instead to \r\n line breaks. By default Mailpit will silently fix incorrect line breaks generated by some broken sendmail clients (see related Github issue).

--smtp-max-recipientsMP_SMTP_MAX_RECIPIENTS100

Maximum number of SMTP recipients allowed per message.

--smtp-allowed-recipientsMP_SMTP_ALLOWED_RECIPIENTS

Only allow SMTP recipients matching a regular expression. Use this to restrict incoming mail to only those sent to a pre-defined list. An example would be --smtp-allowed-recipients '@example.com$' to only allow emails sent to recipients ending in @example.com.

--smtp-ignore-rejected-recipientsMP_SMTP_IGNORE_REJECTED_RECIPIENTS v1.27.4

Silently ignore messages sent to rejected recipients (see smtp-allowed-recipients). Messages to rejected recipients still receive a 250 OK response, however the messages are ignored internally.

--smtp-disable-rdnsMP_SMTP_DISABLE_RDNSfalse

Disable SMTP reverse DNS lookups. SMTP will by default try resolve the hostname of the IP address of the connecting client, however in test networks this can sometimes be problematic causing delays for every message delivered.

--smtp-relay-configMP_SMTP_RELAY_CONFIG

SMTP configuration file to enable message relay/release (see docs). Alternatively the entire configuration can be passed via environment variables.

--smtp-relay-allMP_SMTP_RELAY_ALLfalse

Automatically relay all incoming messages via external SMTP server (see docs). Use with extreme caution!

--smtp-relay-matchingMP_SMTP_RELAY_MATCHING

Automatically relay some incoming messages to matching recipients via external SMTP server (see docs).

This will only relay to recipients matching a regular expression, and cannot be used in conjunction with --smtp-relay-all. An example would be --smtp-relay-matching '(user1@host1\.com|user2@host2\.com|@host3\.com)$'.

--smtp-forward-configMP_SMTP_FORWARD_CONFIG v1.22.0

SMTP configuration file to enable message forwarding (see docs). Alternatively the entire configuration can be passed via environment variables.

--enable-chaosMP_ENABLE_CHAOSfalse v1.22.0

Enable Chaos functionality (API / web UI) (see docs).

--chaos-triggersMP_CHAOS_TRIGGERS v1.22.0

Set the runtime Chaos triggers (see docs).

--pop3MP_POP3_BIND_ADDR0.0.0.0:1110

POP3 server bind interface and port.

--pop3-auth-fileMP_POP3_AUTH_FILE

Specify a password file for POP3 authentication (see docs).

Note: this option is required to enable the POP3 server, or alternatively credentials can be specified via an environment variable.

--pop3-tls-certMP_POP3_TLS_CERT

TLS certificate for POP3 SSL/TLS. This option requires the --pop3-tls-key argument or MP_POP3_TLS_KEY environment variable to be set.

--pop3-tls-keyMP_POP3_TLS_KEY

TLS key for POP3 SSL/TLS. This option requires the --pop3-tls-cert argument or MP_POP3_TLS_CERT environment variable to be set.

--tagMP_TAG

Auto-tag new messages matching filters (see docs).

--tags-configMP_TAGS_CONFIG

Load tags filters from yaml configuration file (see docs).

--tags-title-caseMP_TAGS_TITLE_CASEfalse

Enforces TitleCasing for all newly-created tags (see docs).

--tags-disableMP_TAGS_DISABLE

Disable specific auto-tagging. This option takes a comma-separated list of options (see docs).

--tags-usernameMP_TAGS_USERNAMEfalse v1.26.2

Automatically tag messages with the authenticated username (SMTP or HTTP). Useful for multi-user environments to easily filter and identify messages by user. When enabled, a tag matching the username will be added to each message sent by an authenticated user.

--enable-prometheusMP_ENABLE_PROMETHEUSfalse v1.26.0

Enable Prometheus metrics. Set to true to serve metrics on the main web UI port at /metrics, or specify a bind address (e.g., 0.0.0.0:9090) to run a separate metrics server (see docs).

--webhook-urlMP_WEBHOOK_URL

Call a webhook when new messages are received (see docs), eg: --webhook-url https://example.com/webhook.php.

--webhook-limitMP_WEBHOOK_LIMIT1

Rate limited webhook requests per second. To prevent potentially overloading the webhook server, this is rate limited by default to a maximum of 1 request per second (see docs).

--webhook-delayMP_WEBHOOK_DELAY0 v1.29.0

Delay in seconds before sending webhook requests.