Webhook Support

[JUVOJustin]

Getting mails via rest api is already awesome. But getting a proactive notification via webhook would be a nice addition.

We currently use mailpit as a tool to dump mail from various services with legacy integration into. These mails are then queried all 15s and marked with tags. Having webhooks would greatly improve the efficiency of this process.

Love the tool <3

[axllent]

Hi @JUVOJustin . This is an interesting request. In theory it sounds like a good idea, and for low-volume mail it probably would be OK, however if one is receiving 100 emails a second the webhook is probably really a bad idea. Not only would it potentially DOS the other end, but it would potentially cause all kinds of delays in the receiving process, or spawn off thousands of "routines" (background processes) depending on how it was implemented.

I know some other users are already doing something similar (requiring a third-party integration to trigger something), but they are subscribing to the event websocket (/api/events) which provides real-time notifications. Websockets sounds to me like a far better approach for you, if possible. Have you considered that approach? The current websocket endpoint is actually designed for the web UI and wasn't actually intended for third party use (so has multiple uses), but I could create a new (and documented) API endpoint specific for message websocket notifications.

Your thoughts?

[JUVOJustin]

I think you are right about the webhook feature. Unfortunately, we use n8n for our service which does not come with websockets support.

Maybe sending one webhook each second max. would be a way. It could auto-group the mails since then. But that is obviously just working around low code limitations :D

[axllent]

OK, that is unfortunate - it's basically the whole point of websockets in general - which prevents a lot of overhead TCP networking and only communicates with connected clients :)

What information would you expect to receive via a webhook?

Keep in mind that all configuration is currently done via command line options or environment variables, so I'm not really considering a customisable websocket (other than the URL) at this stage else that would add a lot of extra options, which means a lot of extra work to code and maintain. What I'm thinking at this stage is a JSON POST request to a URL of your choosing, a maximum of 1 request per second (to prevent DOS attacks, additional requests within that second are ignored), with the data from the MessageSummary struct seen here. This would only trigger for new messages, and not other actions such as message deletion or state change (read/unread etc).

Would this solution work?

[axllent]

I have been playing with this today, including n8n (which is pretty cool!). The webhook very works well (from my local development version of Mailpit), and n8n can parse the data (I'm testing by passing info to Gotify). At the moment I have added a default rate limit of 1 request per second (configurable) which works nicely. The risk of an unintended DOS attack is huge though if Mailpit received a burst of email, so an default rate limit of 1 per second is definitely a very good idea.

It could auto-group the mails since then

I looked into this, but it does complicate things significantly, much more than I like for just adding a webhook. The issue with webhooks is they can fail at any point (eg: temporary networking issues, server overload / slow responses / temporary IP ban, DNS resolution error etc), so I don't believe that relying on a webhook is a 100% safe idea. I also do not want to cater for retries of failed attempts etc - it's all too complicated. I think I'm going to stick with one message per webhook (unless greater than the rate limit in which case they are just ignored). Does this sound acceptable to you?

I think that the webhook functionality could be used as a general notification system ("Hey, you just received a message from XYZ - go and take a look"), or to trigger some integration like you have (which in itself will take time to run), but there is always the chance a webhook request doesn't get delivered for some reason.

To come back to your usage with n8n, I think the solution depends on the amount of mail you are receiving. You could set the rate-limit to 0, and with every webhook you receive you use the database ID to call the Mailpit API directly and assign tags - you should be able to handle most messages - that is unless you're getting 100 messages per second. If your volume is high, then polling is your best answer.

Also on that note, I trust you are aware that you can automatically tag messages in Mailpit based on a string match (the functionality is quite limited though, which is maybe why you're doing it via n8n)?

[axllent]

Sorry, I needed to get a new release out so I have included this feature in v.1.9.9 🚀 Please let me know how you get on?

[JUVOJustin]

Haha no worries. Thank you very much for the effort. I appreciate it.

I think the way you implemented this feature solves all the issues I have. Will give it a test after the weekend and let you know how it goes.

[JUVOJustin]

Just wanted to give the the feedback that it works flawless. I am thinking of adding a webhook service in front to add some queuing while websockets are not integrated with n8n. Thank you very much. Awesome job!

[axllent]

Glad to hear it, and thanks for the feedback!