[GH-ISSUE #171] Feature request: Support of modern auth / OAuth authentication for using office.com as relay

kerem commented

2026-03-15 12:39:44 +03:00

Owner

Originally created by @akaer on GitHub (Sep 26, 2023).
Original GitHub issue: https://github.com/axllent/mailpit/issues/171

Currently the usage of Office 365 / office.com as relay is challenging because of the missing support of "modern auth" / OAuth.

So the best would be to follow the implementation suggestions from Microsoft for Authenticate a SMTP connection using OAuth: https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#smtp-protocol-exchange

Originally created by @akaer on GitHub (Sep 26, 2023). Original GitHub issue: https://github.com/axllent/mailpit/issues/171 Currently the usage of Office 365 / office.com as relay is challenging because of the missing support of "modern auth" / OAuth. So the best would be to follow the implementation suggestions from Microsoft for Authenticate a SMTP connection using OAuth: https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#smtp-protocol-exchange

kerem

2026-03-15 12:39:44 +03:00

closed this issue
added the
wontfix
label

kerem commented

2026-03-15 12:40:00 +03:00

Author

Owner

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

I'll see what I can do. Unfortunately I don't think I'll be able to test this as I don't have/use Office 365, so I'll need you to test once I have implemented this. I've found this which should help me with the necessary bits.

@axllent commented on GitHub (Sep 27, 2023): I'll see what I can do. Unfortunately I don't think I'll be able to test this as I don't have/use Office 365, so I'll need you to test once I have implemented this. I've found [this](https://github.com/jacobalberty/smtpoauth2) which should help me with the necessary bits.

kerem commented

2026-03-15 12:40:05 +03:00

Author

Owner

@akaer commented on GitHub (Sep 27, 2023):

That sounds great. I try to help were I can!

@akaer commented on GitHub (Sep 27, 2023): That sounds great. I try to help were I can!

kerem commented

2026-03-15 12:40:10 +03:00

Author

Owner

@axllent commented on GitHub (Sep 28, 2023):

@akaer I'm just looking at this again and I think there may be an issue. Setting a token as part of the oauth2 SMTP authentication looks easy enough - but what I am concerned about is where that token is generated.

Up until now I had assumed that you pre-generated that token in Office365 (ie: like an "app password"), however looking more into that link you sent, it appears that a token needs to be generated via the application (Mailpit) with an integration into the Microsoft authentication system.

If this is true - that you can't just get the access code from somewhere and paste it into the email relay configuration - then I'm afraid this is not an option for Mailpit. Microsoft is only one of many large-scale services that use Oauth/Oauth2, and I'm not going to entertain the idea of adding custom integrations for any of these as I simply cannot maintain or support this, then you're better off using another SMTP relay server such as Mailgun.

Please can you confirm if you generate the token yourself, or whether the application needs to do this?

@axllent commented on GitHub (Sep 28, 2023): @akaer I'm just looking at this again and I think there may be an issue. Setting a token as part of the oauth2 SMTP authentication looks easy enough - but what I am concerned about is where that token is generated. Up until now I had assumed that you pre-generated that token in Office365 (ie: like an "app password"), however looking more into that link you sent, it appears that a token needs to be generated via the application (Mailpit) with an integration into the [Microsoft authentication system](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#get-an-access-token). If this is true - that you can't just get the access code from somewhere and paste it into the email relay configuration - then I'm afraid this is not an option for Mailpit. Microsoft is only one of many large-scale services that use Oauth/Oauth2, and I'm not going to entertain the idea of adding custom integrations for any of these as I simply cannot maintain or support this, then you're better off using another SMTP relay server such as [Mailgun](https://www.mailgun.com). Please can you confirm if you generate the token yourself, or whether the application needs to do this?

kerem commented

2026-03-15 12:40:15 +03:00

Author

Owner

@ulken commented on GitHub (Sep 28, 2023):

I haven't worked with OAuth2 in SMTP specifically, but pretty sure it's up to the application to request an access token.

That being said, I think you can get away with providing a generic OAuth2 integration. Probably still means quite some initial work, but should leave you with less maintenance 🤷

Here's an example of "regular" generic OAuth2 in Grafana:

https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/generic-oauth

@ulken commented on GitHub (Sep 28, 2023): I haven't worked with OAuth2 in SMTP specifically, but pretty sure it's up to the application to request an access token. That being said, I think you can get away with providing a generic OAuth2 integration. Probably still means quite some initial work, but should leave you with less maintenance 🤷 Here's an example of "regular" generic OAuth2 in Grafana: https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/generic-oauth

kerem commented

2026-03-15 12:40:20 +03:00

Author

Owner

@ulken commented on GitHub (Sep 28, 2023):

In this particular case, I think this is the kind of flow that is applicable:

https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#use-client-credentials-grant-flow-to-authenticate-smtp-imap-and-pop-connections

You must use https://outlook.office365.com/.default in the scope property in the body payload for the access token request.

I think most of the setup is done on the user end and necessary parameters can be supplied to Mailpit via env vars/option flags or maybe config file.

@ulken commented on GitHub (Sep 28, 2023): In this particular case, I think this is the kind of flow that is applicable: https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#use-client-credentials-grant-flow-to-authenticate-smtp-imap-and-pop-connections > You must use https://outlook.office365.com/.default in the scope property in the body payload for the access token request. I think most of the setup is done on the user end and necessary parameters can be supplied to Mailpit via env vars/option flags or maybe config file.

kerem commented

2026-03-15 12:40:25 +03:00

Author

Owner

@akaer commented on GitHub (Sep 28, 2023):

@axllent You are absolutely right and I can absolutely understand that it is not desired to bring in additional code to support such third party authentication mechanisms. Especially with OAuth2 it looks like everyone is doing it a bit differently.

So I looked around a bit and found this nice library called Email OAuth 2.0 Proxy. And since I'm running Mailpit as a Docker container, there's also a ready-made Docker container for it here Email OAuth 2.0 Proxy - Docker.
I was able to use this proxy with Mailpit - so for me everything is fine and working.

If you still want to implement an OAuth2 mechanism, I'm happy to help with further testing.

@akaer commented on GitHub (Sep 28, 2023): @axllent You are absolutely right and I can absolutely understand that it is not desired to bring in additional code to support such third party authentication mechanisms. Especially with OAuth2 it looks like everyone is doing it a bit differently. So I looked around a bit and found this nice library called [Email OAuth 2.0 Proxy](https://github.com/simonrob/email-oauth2-proxy). And since I'm running Mailpit as a Docker container, there's also a ready-made Docker container for it here [Email OAuth 2.0 Proxy - Docker](https://github.com/blacktirion/email-oauth2-proxy-docker). I was able to use this proxy with Mailpit - so for me everything is fine and working. If you still want to implement an OAuth2 mechanism, I'm happy to help with further testing.

kerem commented

2026-03-15 12:40:31 +03:00

Author

Owner

@axllent commented on GitHub (Sep 28, 2023):

Thank you both for the information, and it 100% confirms my suspicions - this is a major piece of work to implement, even if it is "just" a generic oauth implementation.

The problem I foresee here is this: Let's say I did add generic oauth functionality, if you see the combined documentation required on the Grafana website, it is really a lot, and very complicated for most. This is largely why Grafana has preconfigured oauth for several of the most common ones (which makes sense), but for me to add that means a lot more code in the codebase (I'll refer to my previous comments), and a lot more to maintain.

The sole purpose of Mailpit is to provide a very functional, easy to use, easy to integrate mail testing tool, for users to capture emails and view them, or run automated testing. The mail release was an afterthought which I originally was not planning on adding, but it became clear users wanted/needed a way to do this, so this was added. Mail release is however only a very small part of the project, and far from its core purpose.

Not even including all the time needed to implement oauth into the code and documentation, adding oauth to the message release means that I would have a continuous flow of support questions ("I can't get it to work", "where do I find this option in provider X", "I run Mailpit behind a proxy and can't access..." etc etc), none of which I can support, and none of which I want to support. It is not the focus of the project, and there are easy alternative ways users can release messages using the standard SMTP protocol with "normal" authentication using any of the hundreds of existing SMTP services available (many with free tiers), or just implementing your own SMTP service. As @akaer just pointed out, there is already an existing proxy one can use for those really wanting to use oauth.

I realise it is not ideal for you, but by not implementing this, it saves me hundreds of hours of development work and support, a lot of stress, and allows me to continue developing Mailpit for what it is intended for.

I trust that my reasoning for not adding this feature makes sense? As much as I would love to support everyone's wishes, it is not always possible or feasible.

@axllent commented on GitHub (Sep 28, 2023): Thank you both for the information, and it 100% confirms my suspicions - this is a major piece of work to implement, even if it is "just" a generic oauth implementation. The problem I foresee here is this: Let's say I did add generic oauth functionality, if you see the combined documentation required on the Grafana website, it is really a lot, and very complicated for most. This is largely why Grafana has preconfigured oauth for several of the most common ones (which makes sense), but for me to add that means a lot more code in the codebase (I'll refer to my previous comments), and a lot more to maintain. The sole purpose of Mailpit is to provide a very functional, easy to use, easy to integrate mail testing tool, for users to capture emails and view them, or run automated testing. The mail release was an afterthought which I originally was not planning on adding, but it became clear users wanted/needed a way to do this, so this was added. Mail release is however only a very small part of the project, and far from its core purpose. Not even including all the time needed to implement oauth into the code and documentation, adding oauth to the message release means that I would have a continuous flow of support questions ("I can't get it to work", "where do I find this option in provider X", "I run Mailpit behind a proxy and can't access..." etc etc), none of which I can support, and none of which I want to support. It is not the focus of the project, and there are easy alternative ways users can release messages using the standard SMTP protocol with "normal" authentication using any of the hundreds of existing SMTP services available (many with free tiers), or just implementing your own SMTP service. As @akaer just pointed out, there is already an existing proxy one can use for those really wanting to use oauth. I realise it is not ideal for you, but by not implementing this, it saves me hundreds of hours of development work and support, a lot of stress, and allows me to continue developing Mailpit for what it is intended for. I trust that my reasoning for not adding this feature makes sense? As much as I would love to support everyone's wishes, it is not always possible or feasible.

kerem commented

2026-03-15 12:40:36 +03:00

Author

Owner

@akaer commented on GitHub (Sep 28, 2023):

@axllent Perfectly summarized and to the point. I absolutely agree with you that Mailpit has a different focus here and that's good. Since I opened the ticket, I'm happy for it to be closed, since using other components like the proxy for OAuth2 solved the problem.

Regardless, I would just like to say thank you! Thank you for the quick response and detailed discussion. Mailpit is a really great product with an even better developer. Just thanks for that!

@akaer commented on GitHub (Sep 28, 2023): @axllent Perfectly summarized and to the point. I absolutely agree with you that Mailpit has a different focus here and that's good. Since I opened the ticket, I'm happy for it to be closed, since using other components like the proxy for OAuth2 solved the problem. Regardless, I would just like to say thank you! Thank you for the quick response and detailed discussion. Mailpit is a really great product with an even better developer. Just thanks for that!

kerem commented

2026-03-15 12:40:41 +03:00

Author

Owner

@axllent commented on GitHub (Sep 28, 2023):

Thanks for your kind words @akaer, not to mention the sponsorship ❤️ I really appreciate that, and am glad Mailpit is helping you too!

@axllent commented on GitHub (Sep 28, 2023): Thanks for your kind words @akaer, not to mention the sponsorship :heart: I really appreciate that, and am glad Mailpit is helping you too!

Rows
Columns

[GH-ISSUE #171] Feature request: Support of modern auth / OAuth authentication for using office.com as relay #117