MiniSMTP: a Self-Hosted SMTP Relay with an HTTP API in Docker

What problem does MiniSMTP solve?

Confirmation of registration, password recovery, invoice, check or system notification is usually sent through SendGrid, Mailgun, Postmark, Amazon SES and similar services. For a large product, this is a convenient path, but small and closed systems have additional limitations.

MiniSMTP takes place between these options: retains control of the self-hosted solution, but hides the routine SMTP integration behind a small API.

What's inside.

The foundation serves docker-mailserver — finished stack Postfix, Dovecot and DKIM. MiniSMTP adds the Docker Compose configuration, HTTP API with Bearer token and a practical publication scenario via Nginx and Let's Encrypt.

1. Backend forms a letter

   The application transmits the recipient, theme and text in a normal JSON request.

2. Nginx receives HTTPS

   Reverse proxy terminates TLS and forwards the request to local API.

3. API checks the token

   Request without correctness Authorization: Bearer It doesn't get in the mail circuit.

4. SMTP-relay sends a letter

   Postfix delivers a message using domain settings and a DKIM signature.

For the calling application, the entire route looks like one stable HTTP contract. It doesn’t need a SDK email provider and doesn’t have to store SMTP logic in every project.

Sending a letter in one request

curl -X POST https://mail.example.com/send \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "client@example.net",
    "subject": "Registration confirmation",
    "text": "Thank you! Your account has been created."
  }'

Such an interface is equally easy to call from Laravel, Symfony, Node.js, Python, Go or a small shell script. When changing the language of the application, the postal infrastructure remains the same.

Deploying — is only half the task.

A working container does not mean that the emails will be sent to «. Therefore, the MiniSMTP documentation covers more than docker compose upbut also basic delivery.

The main difficulty of SMTP — is not to send a letter, but to prove to the receiving servers that the sender can be trusted.

Secure publication scheme

HTTP API should not be accessed directly from the Internet, otherwise the token and endpoint become the only barrier to abuse. The basic scheme leaves the service on the loopback interface and publishes only reverse proxy.

Internet
   │ HTTPS :443
   ▼
Nginx + Let's Encrypt
   │ localhost
   ▼
MiniSMTP API : internal port
   │ SMTP
   ▼
docker-mailserver → recipient server

• A long random API token is stored in application secrets, not in a repository.
• Only the necessary ports are opened.
• Logs and query limits are controlled at the Nginx and application level.
• Access to VPS, DNS and backups is considered as part of email security.

Who is suitable for this relay?

Where is the decision boundary

MiniSMTP is designed for transactional mail of moderate volume. It does not replace the full-fledged ESP if the business needs mass mailings, visual editor, segmentation, campaign stats, and automatic reputation management.

In the minimum version, there is no queue with repeated attempts, automatic processing of bounce/complaint and unsubscribe compliance for marketing messages. If these features are required, add them around relay or choose a dedicated provider.

What happened in the end?

MiniSMTP converts a complex but typical infrastructure problem into a reproducible configuration. The app sends JSON over HTTPS, API checks the token, and the email stack is responsible for SMTP and DKIM. The team retains control over the server, domain and data.

The point of the decision is not to abandon external services at any cost. It is useful where volume is small, requirements are clear, and control and predictability are more important than the built-in marketing ecosystem.