[GH-ISSUE #131] UI flashing with IIS reverse proxy #88

New issue

Closed

opened 2026-03-15 12:29:10 +03:00 by kerem · 9 comments

kerem commented 2026-03-15 12:29:10 +03:00

Owner

Copy link

Originally created by @kustanbruno on GitHub (Jun 26, 2023).
Original GitHub issue: https://github.com/axllent/mailpit/issues/131

We are upgrading from mailhog to mailpit. We are trying to use mailpit with IIS as reverse proxy, the configuration seems to be working, but the UI is always refreshing. There are no errors shown in the browser console nor in the output of mailpit. The network tab of the browser shows 2 request repeating:

• wss://mailhog.cooldigit.hu/api/events
• https://mailhog.cooldigit.hu/api/v1/messages?limit=50

I was able to replicate the problem in postman too. When connecting via ip address without IIS as reverse proxy, de output looks like this:

With IIS as reverse proxy, the output looks like this:

Mailhogs websocket endpoint seems to have no problem with the IIS as reverse proxy:

How should we troubleshoot this problem?

Originally created by @kustanbruno on GitHub (Jun 26, 2023). Original GitHub issue: https://github.com/axllent/mailpit/issues/131 We are upgrading from mailhog to mailpit. We are trying to use mailpit with IIS as reverse proxy, the configuration seems to be working, but the UI is always refreshing. There are no errors shown in the browser console nor in the output of mailpit. The network tab of the browser shows 2 request repeating: - wss://mailhog.cooldigit.hu/api/events - https://mailhog.cooldigit.hu/api/v1/messages?limit=50 I was able to replicate the problem in postman too. When connecting via ip address without IIS as reverse proxy, de output looks like this: <img width="1663" alt="image" src="https://github.com/axllent/mailpit/assets/33034369/4a53d9be-fa17-4358-8bd6-08da11797a0f"> With IIS as reverse proxy, the output looks like this: <img width="1674" alt="image" src="https://github.com/axllent/mailpit/assets/33034369/b53501e5-f088-41c1-8d68-deedd9da5a55"> Mailhogs websocket endpoint seems to have no problem with the IIS as reverse proxy: <img width="1639" alt="image" src="https://github.com/axllent/mailpit/assets/33034369/1a815ac3-2516-453f-a556-41b77dd2f19b"> How should we troubleshoot this problem?

kerem 2026-03-15 12:29:10 +03:00

• closed this issue
• added the
  documentation
  label

kerem commented 2026-03-15 12:29:26 +03:00

Author

Owner

Copy link

@axllent commented on GitHub (Jun 27, 2023):

I can't really say how IIS works, however it appears to be that IIS is closing the websocket connection. Each time the websocket reconnects Mailpit will refresh the messages automatically (so that part is expected). How long does it "hold" the connection for (it appears to immediately disconnect based on what I can see)?

So the issue here is your IIS proxy - if you find out why it's not holding the websocket connection (abnormal closure), then I suspect you'll have your solution. Sorry I can't be more help here, but I really have zero experience in over 15 years with IIS.

<!-- gh-comment-id:1608833559 --> @axllent commented on GitHub (Jun 27, 2023): I can't really say how IIS works, however it appears to be that IIS is closing the websocket connection. Each time the websocket reconnects Mailpit will refresh the messages automatically (so that part is expected). How long does it "hold" the connection for (it appears to immediately disconnect based on what I can see)? So the issue here is your IIS proxy - if you find out why it's not holding the websocket connection (abnormal closure), then I suspect you'll have your solution. Sorry I can't be more help here, but I really have zero experience in over 15 years with IIS.

kerem commented 2026-03-15 12:29:31 +03:00

Author

Owner

Copy link

@doughless commented on GitHub (Jul 17, 2023):

I ran into this when trying to set this up at work, too. Apparently, IIS's advanced request routing does not support permessage-deflate:
https://serverfault.com/questions/1037407/websocket-based-website-behind-a-reverse-proxy-in-iis
https://stackoverflow.com/questions/38933815/iis-8-websockets-with-permessage-deflate

I was able to get it working using the following workaround:

1. Add HTTP_SEC_WEBSOCKET_EXTENSIONS as an allowed server variable, then
2. Add the following to your HTTP rewrite rule (I have separate rewrite rules for HTTP and WS, I noticed it only fixed the issue when rewriting the server variable specifically with the HTTP rule):

<serverVariables>
  <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" />
</serverVariables>

<!-- gh-comment-id:1638915147 --> @doughless commented on GitHub (Jul 17, 2023): I ran into this when trying to set this up at work, too. Apparently, IIS's advanced request routing does not support permessage-deflate: https://serverfault.com/questions/1037407/websocket-based-website-behind-a-reverse-proxy-in-iis https://stackoverflow.com/questions/38933815/iis-8-websockets-with-permessage-deflate I was able to get it working using the following workaround: 1. Add HTTP_SEC_WEBSOCKET_EXTENSIONS as an allowed server variable, then 2. Add the following to your HTTP rewrite rule (I have separate rewrite rules for HTTP and WS, I noticed it only fixed the issue when rewriting the server variable specifically with the HTTP rule): ``` <serverVariables> <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" /> </serverVariables> ```

kerem commented 2026-03-15 12:29:36 +03:00

Author

Owner

Copy link

@axllent commented on GitHub (Jul 18, 2023):

Thanks @doughless, I am sure this will help some. Given what you now know, do you think it is fairly easy to document the steps needed in order to set up a proxy for Mailpit using ISS? What I mean is, if I was to get a simple set of instructions of how to set it up on ISS, I could then document this in the Mailpit Wiki for other users to refer to.

<!-- gh-comment-id:1639270279 --> @axllent commented on GitHub (Jul 18, 2023): Thanks @doughless, I am sure this will help some. Given what you now know, do you think it is fairly easy to document the steps needed in order to set up a proxy for Mailpit using ISS? What I mean is, if I was to get a simple set of instructions of how to set it up on ISS, I could then document this in the Mailpit Wiki for other users to refer to.

kerem commented 2026-03-15 12:29:41 +03:00

Author

Owner

Copy link

@doughless commented on GitHub (Jul 18, 2023):

@axllent Sure, this is what I put together, hopefully I remembered everything:

Install prerequisites

URL Rewrite 2.1
Application Request Routing 3.0

Enable Application Request Routing proxy

Open IIS Manager, select your server, then open the Application Request Routing Cache feature:

Next, click Server Proxy Settings...

Finally, check “Enable proxy” and click Apply.

Add server variables

Because Application Request Routing doesn’t work with the permessage_deflate WebSocket extension, you will need to add the HTTP_SEC_WEBSOCKET_EXTENSIONS server variable to URL Rewrite to allow your rewrite rules to remove the Sec-WebSocket-Extensions header value.

To do this, open IIS Manager, select your website, and open the URL Rewrite feature:

Then click on View Server Variables... and add a server variable named HTTP_SEC_WEBSOCKET_EXTENSIONS:

You can then close IIS Manager; you will need to manually add the URL Rewrite rules to your web.config, because URL Rewrite's UI doesn't allow setting server variables to an empty string value.

Configure URL Rewrite rules

Edit the web.config for your website, and add the following rewrite rules:

• Replace MP_WEBROOT with your MailPit web root; or remove it from the regex patterns if you are not using a custom web root.
• You only need to replace localhost:8025 with your MailPit server and port if you are running MailPit on a different server than your IIS reverse proxy, or you configured MP_UI_BIND_ADDR to use a different port.

<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="MailPit Reverse Proxy" stopProcessing="true">
                    <match url="^(MP_WEBROOT.*)" />
                    <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
                        <add input="{SERVER_PROTOCOL}" pattern="wss" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="http://localhost:8025/{R:1}" />
                    <serverVariables>
                        <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" />
                    </serverVariables>
                </rule>
                <rule name="MailPit WebSocket Reverse Proxy" stopProcessing="true">
                    <match url="^(MP_WEBROOT.*)" />
                    <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
                        <add input="{SERVER_PROTOCOL}" pattern="wss" />
                    </conditions>
                    <action type="Rewrite" url="ws://localhost:8025/{R:1}" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

<!-- gh-comment-id:1641054844 --> @doughless commented on GitHub (Jul 18, 2023): @axllent Sure, this is what I put together, hopefully I remembered everything: ### Install prerequisites [URL Rewrite 2.1](https://www.iis.net/downloads/microsoft/url-rewrite) [Application Request Routing 3.0](https://www.iis.net/downloads/microsoft/application-request-routing) ### Enable Application Request Routing proxy Open IIS Manager, select your server, then open the Application Request Routing Cache feature:  Next, click Server Proxy Settings...  Finally, check “Enable proxy” and click Apply.  ### Add server variables Because Application Request Routing doesn’t work with the permessage_deflate WebSocket extension, you will need to add the HTTP_SEC_WEBSOCKET_EXTENSIONS server variable to URL Rewrite to allow your rewrite rules to remove the Sec-WebSocket-Extensions header value. To do this, open IIS Manager, select your website, and open the URL Rewrite feature:  Then click on View Server Variables... and add a server variable named HTTP_SEC_WEBSOCKET_EXTENSIONS:   You can then close IIS Manager; you will need to manually add the URL Rewrite rules to your web.config, because URL Rewrite's UI doesn't allow setting server variables to an empty string value. ### Configure URL Rewrite rules Edit the web.config for your website, and add the following rewrite rules: - Replace MP_WEBROOT with your MailPit web root; or remove it from the regex patterns if you are not using a custom web root. - You only need to replace localhost:8025 with your MailPit server and port if you are running MailPit on a different server than your IIS reverse proxy, or you configured MP_UI_BIND_ADDR to use a different port. ```xml <configuration> <system.webServer> <rewrite> <rules> <rule name="MailPit Reverse Proxy" stopProcessing="true"> <match url="^(MP_WEBROOT.*)" /> <conditions logicalGrouping="MatchAll" trackAllCaptures="false"> <add input="{SERVER_PROTOCOL}" pattern="wss" negate="true" /> </conditions> <action type="Rewrite" url="http://localhost:8025/{R:1}" /> <serverVariables> <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" /> </serverVariables> </rule> <rule name="MailPit WebSocket Reverse Proxy" stopProcessing="true"> <match url="^(MP_WEBROOT.*)" /> <conditions logicalGrouping="MatchAll" trackAllCaptures="false"> <add input="{SERVER_PROTOCOL}" pattern="wss" /> </conditions> <action type="Rewrite" url="ws://localhost:8025/{R:1}" /> </rule> </rules> </rewrite> </system.webServer> </configuration> ```

kerem commented 2026-03-15 12:29:46 +03:00

Author

Owner

Copy link

@doughless commented on GitHub (Jul 18, 2023):

Thought I'd include a mention to you, @kustanbruno, to see if this helps you.

<!-- gh-comment-id:1641058745 --> @doughless commented on GitHub (Jul 18, 2023): Thought I'd include a mention to you, @kustanbruno, to see if this helps you.

kerem commented 2026-03-15 12:29:51 +03:00

Author

Owner

Copy link

@axllent commented on GitHub (Jul 23, 2023):

My apologies for the late reply @doughless - I was away for a few days. That is great, thank you! I have linked it to the Troubleshooting wiki page for now, but will hopefully (one one day not too far away) create and add it directly to a more suitable documentation website for Mailpit 👍

<!-- gh-comment-id:1646955515 --> @axllent commented on GitHub (Jul 23, 2023): My apologies for the late reply @doughless - I was away for a few days. That is great, thank you! I have linked it to the [Troubleshooting](https://github.com/axllent/mailpit/wiki/Troubleshooting) wiki page for now, but will hopefully (one one day not too far away) create and add it directly to a more suitable documentation website for Mailpit :+1:

kerem commented 2026-03-15 12:29:56 +03:00

Author

Owner

Copy link

@kustanbruno commented on GitHub (Jul 24, 2023):

Hi @doughless, thanks a lot, the configuration works. Your tutorial was really detailed and easy to follow. 👍

I had to add around the two rewrite rules.

<!-- gh-comment-id:1647437989 --> @kustanbruno commented on GitHub (Jul 24, 2023): Hi @doughless, thanks a lot, the configuration works. Your tutorial was really detailed and easy to follow. 👍 I had to add <rules></rules> around the two rewrite rules.

kerem commented 2026-03-15 12:30:01 +03:00

Author

Owner

Copy link

@pranithan-kang commented on GitHub (Aug 21, 2025):

@axllent Sure, this is what I put together, hopefully I remembered everything:

Install prerequisites

URL Rewrite 2.1 Application Request Routing 3.0

Enable Application Request Routing proxy

Open IIS Manager, select your server, then open the Application Request Routing Cache feature:

Next, click Server Proxy Settings...

Finally, check “Enable proxy” and click Apply.

Add server variables

Because Application Request Routing doesn’t work with the permessage_deflate WebSocket extension, you will need to add the HTTP_SEC_WEBSOCKET_EXTENSIONS server variable to URL Rewrite to allow your rewrite rules to remove the Sec-WebSocket-Extensions header value.

To do this, open IIS Manager, select your website, and open the URL Rewrite feature:

Then click on View Server Variables... and add a server variable named HTTP_SEC_WEBSOCKET_EXTENSIONS:

You can then close IIS Manager; you will need to manually add the URL Rewrite rules to your web.config, because URL Rewrite's UI doesn't allow setting server variables to an empty string value.

Configure URL Rewrite rules

Edit the web.config for your website, and add the following rewrite rules:

• Replace MP_WEBROOT with your MailPit web root; or remove it from the regex patterns if you are not using a custom web root.
• You only need to replace localhost:8025 with your MailPit server and port if you are running MailPit on a different server than your IIS reverse proxy, or you configured MP_UI_BIND_ADDR to use a different port.

I took the web.config above to put in IIS and found that it returns 500.12. I later realized that the rules must be wrapped with the <rules> tag. So, the final web.config must be:

<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="MailPit Reverse Proxy" stopProcessing="true">
                    <match url="^(MP_WEBROOT.*)" />
                    <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
                        <add input="{SERVER_PROTOCOL}" pattern="wss" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="http://localhost:8025/{R:1}" />
                    <serverVariables>
                        <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" />
                    </serverVariables>
                </rule>
                <rule name="MailPit WebSocket Reverse Proxy" stopProcessing="true">
                    <match url="^(MP_WEBROOT.*)" />
                    <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
                        <add input="{SERVER_PROTOCOL}" pattern="wss" />
                    </conditions>
                    <action type="Rewrite" url="ws://localhost:8025/{R:1}" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

<!-- gh-comment-id:3209298719 --> @pranithan-kang commented on GitHub (Aug 21, 2025): > [@axllent](https://github.com/axllent) Sure, this is what I put together, hopefully I remembered everything: > > ### Install prerequisites > [URL Rewrite 2.1](https://www.iis.net/downloads/microsoft/url-rewrite) [Application Request Routing 3.0](https://www.iis.net/downloads/microsoft/application-request-routing) > > ### Enable Application Request Routing proxy > Open IIS Manager, select your server, then open the Application Request Routing Cache feature: > >  > > Next, click Server Proxy Settings...  > > Finally, check “Enable proxy” and click Apply.  > > ### Add server variables > Because Application Request Routing doesn’t work with the permessage_deflate WebSocket extension, you will need to add the HTTP_SEC_WEBSOCKET_EXTENSIONS server variable to URL Rewrite to allow your rewrite rules to remove the Sec-WebSocket-Extensions header value. > > To do this, open IIS Manager, select your website, and open the URL Rewrite feature:  > > Then click on View Server Variables... and add a server variable named HTTP_SEC_WEBSOCKET_EXTENSIONS:   > > You can then close IIS Manager; you will need to manually add the URL Rewrite rules to your web.config, because URL Rewrite's UI doesn't allow setting server variables to an empty string value. > > ### Configure URL Rewrite rules > Edit the web.config for your website, and add the following rewrite rules: > > * Replace MP_WEBROOT with your MailPit web root; or remove it from the regex patterns if you are not using a custom web root. > * You only need to replace localhost:8025 with your MailPit server and port if you are running MailPit on a different server than your IIS reverse proxy, or you configured MP_UI_BIND_ADDR to use a different port. > > <configuration> > <system.webServer> > <rewrite> > <rule name="MailPit Reverse Proxy" stopProcessing="true"> > <match url="^(MP_WEBROOT.*)" /> > <conditions logicalGrouping="MatchAll" trackAllCaptures="false"> > <add input="{SERVER_PROTOCOL}" pattern="wss" negate="true" /> > </conditions> > <action type="Rewrite" url="http://localhost:8025/{R:1}" /> > <serverVariables> > <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" /> > </serverVariables> > </rule> > <rule name="MailPit WebSocket Reverse Proxy" stopProcessing="true"> > <match url="^(MP_WEBROOT.*)" /> > <conditions logicalGrouping="MatchAll" trackAllCaptures="false"> > <add input="{SERVER_PROTOCOL}" pattern="wss" /> > </conditions> > <action type="Rewrite" url="ws://localhost:8025/{R:1}" /> > </rule> > </rewrite> > </system.webServer> > </configuration> I took the `web.config` above to put in IIS and found that it returns 500.12. I later realized that the rules must be wrapped with the `<rules>` tag. So, the final web.config must be: <configuration> <system.webServer> <rewrite> <rules> <rule name="MailPit Reverse Proxy" stopProcessing="true"> <match url="^(MP_WEBROOT.*)" /> <conditions logicalGrouping="MatchAll" trackAllCaptures="false"> <add input="{SERVER_PROTOCOL}" pattern="wss" negate="true" /> </conditions> <action type="Rewrite" url="http://localhost:8025/{R:1}" /> <serverVariables> <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" /> </serverVariables> </rule> <rule name="MailPit WebSocket Reverse Proxy" stopProcessing="true"> <match url="^(MP_WEBROOT.*)" /> <conditions logicalGrouping="MatchAll" trackAllCaptures="false"> <add input="{SERVER_PROTOCOL}" pattern="wss" /> </conditions> <action type="Rewrite" url="ws://localhost:8025/{R:1}" /> </rule> </rules> </rewrite> </system.webServer> </configuration>

kerem commented 2026-03-15 12:30:07 +03:00

Author

Owner

Copy link

@doughless commented on GitHub (Aug 21, 2025):

I took the web.config above to put in IIS and found that it returns 500.12. I later realized that the rules must be wrapped with the <rules> tag.

Thank you, I fixed the original comment.

<!-- gh-comment-id:3210859600 --> @doughless commented on GitHub (Aug 21, 2025): > I took the `web.config` above to put in IIS and found that it returns 500.12. I later realized that the rules must be wrapped with the `<rules>` tag. Thank you, I fixed the original comment.

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

develop

master

v1.29.7

v1.29.6

v1.29.5

v1.29.4

v1.29.3

v1.29.2

v1.29.1

v1.29.0

v1.28.4

v1.28.3

v1.28.2

v1.28.1

v1.28.0

v1.27.11

v1.27.10

v1.27.9

v1.27.8

v1.27.7

v1.27.6

v1.27.5

v1.27.4

v1.27.3

v1.27.2

v1.27.1

v1.27.0

v1.26.2

v1.26.1

v1.26.0

v1.25.1

v1.25.0

v1.24.2

v1.24.1

v1.24.0

v1.23.2

v1.23.1

v1.23.0

v1.22.3

v1.22.2

v1.22.1

v1.22.0

v1.21.8

v1.21.7

v1.21.6

v1.21.5

v1.21.4

v1.21.3

v1.21.2

v1.21.1

v1.21.0

v1.20.7

v1.20.6

v1.20.5

v1.20.4

v1.20.3

v1.20.2

v1.20.1

v1.20.0

v1.19.3

v1.19.2

v1.19.1

v1.19.0

v1.18.7

v1.18.6

v1.18.5

v1.18.4

v1.18.3

v1.18.2

v1.18.1

v1.18.0

v1.17.1

v1.17.0

v1.16.0

v1.15.1

v1.15.0

v1.14.4

v1.14.3

v1.14.2

v1.14.1

v1.14.0

v1.13.3

v1.13.2

v1.13.1

v1.13.0

v1.12.1

v1.12.0

v1.11.1

v1.11.0

v1.10.4

v1.10.3

v1.10.2

v1.10.1

v1.10.0

v1.9.10

v1.9.9

v1.9.8

v1.9.7

v1.9.6

v1.9.5

v1.9.4

v1.9.3

v1.9.2

v1.9.1

v1.9.0

v1.8.4

v1.8.3

v1.8.2

v1.8.1

v1.8.0

v1.7.1

v1.7.0

v1.6.22

v1.6.21

v1.6.20

v1.6.19

v1.6.18

v1.6.17

v1.6.16

v1.6.15

v1.6.14

v1.6.13

v1.6.12

v1.6.11

v1.6.10

v1.6.9

v1.6.8

v1.6.7

v1.6.6

v1.6.5

v1.6.4

v1.6.3

v1.6.2

v1.6.1

v1.6.0

v1.5.5

v1.5.4

v1.5.3

v1.5.2

v1.5.1

v1.5.0

v1.4.0

v1.3.11

v1.3.10

v1.3.9

v1.3.8

v1.3.7

v1.3.6

v1.3.5

v1.3.4

v1.3.3

v1.3.2

v1.3.1

v1.3.0

v1.2.9

v1.2.8

v1.2.7

v1.2.6

1.2.5

1.2.4

1.2.3

1.2.2

1.2.1

1.2.0

1.1.7

1.1.6

1.1.5

1.1.4

1.1.3

1.1.2

1.1.1

1.1.0

1.0.0

1.0.0-beta1

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

0.0.9

0.0.8

0.0.7

0.0.6

0.0.5

0.0.4

0.0.3

0.0.2

0.0.1-beta

Labels

Clear labels   

awaiting feedback

  

bug

  

docker

  

documentation

  

enhancement

  

github_actions

  

invalid

  

pull-request

Mirrored from GitHub Pull Request

  

question

  

stale

  

wontfix

No labels

awaiting feedback

bug

docker

documentation

enhancement

github_actions

invalid

pull-request

question

stale

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/mailpit#88

No description provided.