[GH-ISSUE #517] SMTP Relay Timeout Blocks Client Connection Until External Timeout #333

New issue

Closed

opened 2026-03-15 13:55:20 +03:00 by kerem · 2 comments

kerem commented

2026-03-15 13:55:20 +03:00

Owner

Originally created by @Lunaden on GitHub (Jun 12, 2025).
Original GitHub issue: https://github.com/axllent/mailpit/issues/517

Description

We are using Mailpit as an SMTP relay in a test environment, configured via Docker:

services:
  smtp-relay:
    image: axllent/mailpit
    restart: always
    ports:
      - "25:25"
    networks:
      - smtp
      - proxy
    volumes:
      - /containers/mailpit/config:/config:ro
      - /containers/mailpit/data:/data
    environment:
      TIMEZONE: Europe/Paris
      TZ: Europe/Paris
      MP_SMTP_RELAY_CONFIG: /config/smtp-relay.cfg
      MP_SMTP_RELAY_ALL: 'true'
      MP_SMTP_MAX_RECIPIENTS: 20
      MP_SMTP_DISABLE_RDNS: 'true'
      MP_ALLOW_UNTRUSTED_TLS: 'true'
      MP_MAX_MESSAGES: 10000
      MP_DATA_FILE: /data/mailpit.db
      MP_SMTP_BIND_ADDR: '0.0.0.0:25'

The service works well in most cases. However, we have noticed that when Mailpit attempts to relay to certain external SMTP servers (e.g., mail.example.com:25), it sometimes encounters connection timeouts, and during this time the client that initiated the email remains blocked until the timeout occurs.

Here are sample logs showing the issue:

time="2025/06/10 18:15:16" level=error msg="[smtp] error relaying message: error connecting to mail.example.com:25: dial tcp 52.101.xxx.xxx:25: connect: connection timed out"
...
time="2025/06/10 18:33:01" level=error msg="[smtp] error relaying message: error connecting to mail.example.com:25: dial tcp 52.101.xxx.xxx:25: connect: connection timed out"

Expected Behavior

Mailpit should accept the message from the SMTP client and respond immediately, even if the relay target is unreachable, handling the external delivery asynchronously.

Actual Behavior

When the relay fails (e.g., connection timeout), the SMTP client is kept waiting until the timeout completes. This causes blocking behavior in our upstream systems.

Context

This behavior is observed in a test environment, so the impact is currently limited. However, it is still disruptive during development, testing, and performance benchmarking, and would be problematic in a production setup.

Questions

Is this synchronous relay behavior expected by design?
Is there a way to configure Mailpit to immediately accept client messages and handle relay in the background (queue-first)?
If not, would it be possible to consider this as a feature request?

Environment

Mailpit image: axllent/mailpit
Environment: Docker on Linux
SMTP bind port: 25
Relay target: Third-party gateway

Originally created by @Lunaden on GitHub (Jun 12, 2025). Original GitHub issue: https://github.com/axllent/mailpit/issues/517 ### Description We are using **Mailpit as an SMTP relay in a test environment**, configured via Docker: ```yaml services: smtp-relay: image: axllent/mailpit restart: always ports: - "25:25" networks: - smtp - proxy volumes: - /containers/mailpit/config:/config:ro - /containers/mailpit/data:/data environment: TIMEZONE: Europe/Paris TZ: Europe/Paris MP_SMTP_RELAY_CONFIG: /config/smtp-relay.cfg MP_SMTP_RELAY_ALL: 'true' MP_SMTP_MAX_RECIPIENTS: 20 MP_SMTP_DISABLE_RDNS: 'true' MP_ALLOW_UNTRUSTED_TLS: 'true' MP_MAX_MESSAGES: 10000 MP_DATA_FILE: /data/mailpit.db MP_SMTP_BIND_ADDR: '0.0.0.0:25' ``` The service works well in most cases. However, we have noticed that when Mailpit attempts to relay to certain **external SMTP servers** (e.g., `mail.example.com:25`), it sometimes encounters **connection timeouts**, and during this time the client that initiated the email remains **blocked until the timeout occurs**. Here are sample logs showing the issue: ``` time="2025/06/10 18:15:16" level=error msg="[smtp] error relaying message: error connecting to mail.example.com:25: dial tcp 52.101.xxx.xxx:25: connect: connection timed out" ... time="2025/06/10 18:33:01" level=error msg="[smtp] error relaying message: error connecting to mail.example.com:25: dial tcp 52.101.xxx.xxx:25: connect: connection timed out" ``` --- ### Expected Behavior Mailpit should accept the message from the SMTP client and respond immediately, **even if the relay target is unreachable**, handling the external delivery **asynchronously**. --- ### Actual Behavior When the relay fails (e.g., connection timeout), the SMTP client is kept waiting until the timeout completes. This causes blocking behavior in our upstream systems. --- ### Context This behavior is observed in a **test environment**, so the impact is currently limited. However, it is still disruptive during development, testing, and performance benchmarking, and would be **problematic in a production setup**. --- ### Questions * Is this synchronous relay behavior expected by design? * Is there a way to configure Mailpit to **immediately accept client messages and handle relay in the background** (queue-first)? * If not, would it be possible to consider this as a feature request? --- ### Environment * **Mailpit image**: `axllent/mailpit` * **Environment**: Docker on Linux * **SMTP bind port**: 25 * **Relay target**: Third-party gateway ---

kerem closed this issue

2026-03-15 13:55:26 +03:00

kerem commented

2026-03-15 13:55:31 +03:00

Author

Owner

@axllent commented on GitHub (Jun 12, 2025):

Hi @Lunaden. I'll try respond to your questions, but please forgive me if I try keep this as short as I can as I need to get to bed.

This behavior is observed in a test environment, so the impact is currently limited. However, it is still disruptive during development, testing, and performance benchmarking, and would be problematic in a production setup.

The first thing to note is that Mailpit is a development tool, not a production tool, it's written everywhere in the title, descriptions etc. The relay functionality was added as an afterthought (feature request) which was manually initiated (releasing mail via the web UI), and later with an option to automatically relay all messages. This was however never intended to work as a high load transparent proxy which appears to be how you are using it.

I would also never recommend benchmarking delivery while Mailpit is connected to a third party SMTP server as that will be a sure way to get yourself banned.

Is this synchronous relay behavior expected by design?
Is there a way to configure Mailpit to immediately accept client messages and handle relay in the background (queue-first)?

It is 100% synchronous by design, and there is no option to change this because that functionality does not exist. The reasoning for this is if Mailpit was do what you are asking (to queue messages and send them in the background), then it would need to also handle all the other features of an actual mail server (like postfix), including rate limited sending, temporary deferrals, retries, bounces etc. That is not the purpose of Mailpit, that is the purpose of an actual mail server which is designed to send emails. Mailpit is designed to receive emails, not to send them. Trying to replicate that within Mailpit would be a huge amount of work to do properly - basically to build a complete mail server, and this is completely out of scope of this project.

If not, would it be possible to consider this as a feature request?

For the reasons I provided above, unfortunately no. There is a solution to your problem however, you need to set up an actual mail server (eg: postfix) as a relay proxy between Mailpit and your third party, which can then handle the sending, delays, etc. This way Mailpit can relay a tonne of emails to postfix (without delays) and let it handle the sending part, regardless how long those third party SMTP servers.

I hope this answers your questions?

@axllent commented on GitHub (Jun 12, 2025): Hi @Lunaden. I'll try respond to your questions, but please forgive me if I try keep this as short as I can as I need to get to bed. > This behavior is observed in a test environment, so the impact is currently limited. However, it is still disruptive during development, testing, and performance benchmarking, and would be problematic in a production setup. The first thing to note is that Mailpit is a **development** tool, not a production tool, it's written everywhere in the title, descriptions etc. The relay functionality was added as an afterthought (feature request) which was manually initiated (releasing mail via the web UI), and later with an option to automatically relay all messages. This was however never intended to work as a high load transparent proxy which appears to be how you are using it. I would also never recommend benchmarking delivery while Mailpit is connected to a third party SMTP server as that will be a sure way to get yourself banned. > Is this synchronous relay behavior expected by design? > Is there a way to configure Mailpit to immediately accept client messages and handle relay in the background (queue-first)? It is 100% synchronous by design, and there is no option to change this because that functionality does not exist. The reasoning for this is if Mailpit was do what you are asking (to queue messages and send them in the background), then it would need to also handle all the other features of an actual mail server (like postfix), including rate limited sending, temporary deferrals, retries, bounces etc. That is not the purpose of Mailpit, that is the purpose of an actual mail server which is designed to send emails. Mailpit is designed to receive emails, not to send them. Trying to replicate that within Mailpit would be a huge amount of work to do properly - basically to build a complete mail server, and this is completely out of scope of this project. > If not, would it be possible to consider this as a feature request? For the reasons I provided above, unfortunately no. There is a solution to your problem however, you need to set up an actual mail server (eg: postfix) as a relay proxy between Mailpit and your third party, which can then handle the sending, delays, etc. This way Mailpit can relay a tonne of emails to postfix (without delays) and let it handle the sending part, regardless how long those third party SMTP servers. I hope this answers your questions?

kerem commented

2026-03-15 13:55:37 +03:00

Author

Owner

@Lunaden commented on GitHub (Jun 12, 2025):

Hi, thank you very much for your detailed reply despite the late hour — much appreciated.

Just to clarify:

Yes, this is strictly a development environment, used for testing and QA workflows only.
I hadn't fully realized that the relay mechanism was entirely synchronous by design. I was actually expecting the opposite behavior — more of a decoupled queue-first pattern — which is what I’m used to with other tools or setups.
I now perfectly understand your explanation and the architectural reasons behind this choice.

Thank you again for your time and clear guidance !

@Lunaden commented on GitHub (Jun 12, 2025): Hi, thank you very much for your detailed reply despite the late hour — much appreciated. Just to clarify: * Yes, this is strictly a **development environment**, used for testing and QA workflows only. * I hadn't fully realized that the relay mechanism was **entirely synchronous by design**. I was actually expecting the opposite behavior — more of a decoupled queue-first pattern — which is what I’m used to with other tools or setups. * I now perfectly understand your explanation and the architectural reasons behind this choice. Thank you again for your time and clear guidance !