[GH-ISSUE #412] [Feature-request] Add validation token to hook and API requests #265

New issue

Closed

opened 2026-03-15 13:32:40 +03:00 by kerem · 4 comments

kerem commented

2026-03-15 13:32:40 +03:00

Owner

Originally created by @baiomys on GitHub (Dec 16, 2024).
Original GitHub issue: https://github.com/axllent/mailpit/issues/412

For instance telegram bot API uses X-Telegram-Bot-Api-Secret-Token passed in header.
It is user definable during webhook initialization.

Is it possible to implement same mechanism in API calls and maybe in webhook?
Most of interaction with API occurs on private networks, but sometimes it is necessary to expose REST endpoints.
Currently all path and header validation runs on reverse proxy side, which is a bit inconvenient.

Originally created by @baiomys on GitHub (Dec 16, 2024). Original GitHub issue: https://github.com/axllent/mailpit/issues/412 For instance telegram bot API uses _X-Telegram-Bot-Api-Secret-Token_ passed in header. It is user definable during webhook initialization. Is it possible to implement same mechanism in API calls and maybe in webhook? Most of interaction with API occurs on private networks, but sometimes it is necessary to expose REST endpoints. Currently all path and header validation runs on reverse proxy side, which is a bit inconvenient.

kerem closed this issue

2026-03-15 13:32:45 +03:00

kerem commented

2026-03-15 13:32:51 +03:00

Author

Owner

@axllent commented on GitHub (Dec 20, 2024):

Sorry, I'm not ignoring you @baiomys - I've just been recovering after the operation ... and thinking about this. Your question is actually two-fold, first for webhook requests, and secondly incoming API requests. Currently neither is possible using tokens. I'm not saying I won't consider this, I would just like to understand your requirements better, as supporting like this becomes a huge change in how Mailpit works.

Webhooks
From what I can tell, the Telegram API allows a token to be set in either a header, or in the URL. Is there any reason you can't use it in the URL, or do I misunderstand the difference between a secret token and (regular?) token?

API
As far as authentication is (currently) concerned, both the web UI and the API are directly linked, and currently only supports basic authentication. If basic auth is set, then HTTP requests should be made in the form of https://<user>:<pass>@example.com/api/v1/<endpoint>. Can the external bot service not use this syntax?

When it comes to custom integrations (like what I think you are working towards), then you may have to consider a custom self written "proxy service" (PHP, Go, node server etc) that can receive requests from either end and then process / customize the data, and pass that on either way (<Mailpit> <-> <proxy> <-> <Telegram>). This both limits your Mailpit exposure to the internet, and allows you the flexibility to do whatever you like without requiring both ends to communicate directly.

@axllent commented on GitHub (Dec 20, 2024): Sorry, I'm not ignoring you @baiomys - I've just been recovering after the operation ... and thinking about this. Your question is actually two-fold, first for webhook requests, and secondly incoming API requests. Currently neither is possible using tokens. I'm not saying I won't consider this, I would just like to understand your requirements better, as supporting like this becomes a huge change in how Mailpit works. **Webhooks** From what I can tell, the Telegram API allows a token to be set in either a header, or [in the URL](https://core.telegram.org/bots/api#making-requests). Is there any reason you can't use it in the URL, or do I misunderstand the difference between a secret token and (regular?) token? **API** As far as authentication is (currently) concerned, both the web UI and the API are directly linked, and currently only supports basic authentication. If basic auth is set, then HTTP requests should be made in the form of `https://<user>:<pass>@example.com/api/v1/<endpoint>`. Can the external bot service not use this syntax? When it comes to custom integrations (like what I think you are working towards), then you may have to consider a custom self written "proxy service" (PHP, Go, node server etc) that can receive requests from either end and then process / customize the data, and pass that on either way (`<Mailpit>` <-> `<proxy>` <-> `<Telegram>`). This both limits your Mailpit exposure to the internet, and allows you the flexibility to do whatever you like without requiring both ends to communicate directly.

kerem commented

2026-03-15 13:32:56 +03:00

Author

Owner

@baiomys commented on GitHub (Dec 20, 2024):

Thanks for detailed response. Secret token in telegram serve as protection against guessing hook URL and tampering with it.
Entire hook, including this token, can be set at runtime.

https://api.telegram.org/botxxxxxxxxx:yyyyyyyyyyyyyyyyyyyyyyyyy/setWebhook?url=https://domain.tld/tghook/4af3a9903c03f97283e663e878746490&drop_pending_updates=True&max_connections=40&secret_token=49188f1beec02c87d653723975180445189f6a6a8bda509b5a8f75ac73f74e28

Which makes all calls perfectly secure.
Tampering with webhook in MAILPIT can't do any serious harm, so implementing such protection right away is not necessary.

On the other hand tampering with API calls can be a REAL DISASTER.
Pls consider in near future JWT or other protection apart from user:password.
=)

@baiomys commented on GitHub (Dec 20, 2024): Thanks for detailed response. Secret token in telegram serve as protection against guessing hook URL and tampering with it. Entire hook, including this token, can be set at runtime. https://api.telegram.org/botxxxxxxxxx:yyyyyyyyyyyyyyyyyyyyyyyyy/setWebhook?url=https://domain.tld/tghook/4af3a9903c03f97283e663e878746490&drop_pending_updates=True&max_connections=40&secret_token=49188f1beec02c87d653723975180445189f6a6a8bda509b5a8f75ac73f74e28 Which makes all calls perfectly secure. Tampering with webhook in MAILPIT can't do any serious harm, so implementing such protection right away is not necessary. On the other hand tampering with API calls can be a REAL DISASTER. Pls consider in near future JWT or other protection apart from user:password. =)

kerem commented

2026-03-15 13:33:01 +03:00

Author

Owner

@axllent commented on GitHub (Dec 20, 2024):

Whilst I understand what damage can be caused by tampering with API calls, I still don't understand how a token is more secure than basic auth though? Both are transmitted as HTTP headers (client to server), and both a username and password can be as long & complex as you like.

@axllent commented on GitHub (Dec 20, 2024): Whilst I understand what damage can be caused by tampering with API calls, I still don't understand how a token is more secure than basic auth though? Both are transmitted as HTTP headers (client to server), and both a username and password can be as long & complex as you like.

kerem commented

2026-03-15 13:33:06 +03:00

Author

Owner

@axllent commented on GitHub (Dec 20, 2024):

Sorry, I should say that JWT is more secure in that it is time based, however if someone is literally tampering with your HTTPS connection, then you have far bigger problems to worry about.

@axllent commented on GitHub (Dec 20, 2024): Sorry, I should say that JWT is more secure in that it is time based, however if someone is literally tampering with your HTTPS connection, then you have far bigger problems to worry about.