[GH-ISSUE #12] Can the API be considered stable? #10

New issue

Closed

opened 2026-03-15 12:03:12 +03:00 by kerem · 4 comments

kerem commented

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

Owner

Originally created by @alfa-alex on GitHub (Sep 5, 2022).
Original GitHub issue: https://github.com/axllent/mailpit/issues/12

Version 1.0.0 is out, but the API (/api/...) is not documented outside the code (yet?). So I'm unsure if it's just an internal API (for Frontend<->Backend communication) or whether it is safe (and stable) to use it externally?

My use case is I want to run integration tests and check the mails that are being sent, so I collect the messages via the MailPit websocket endpoint. It seems quite convenient to me, but if that API is subject to change, I shall better not use it.

On a side note, thanks for sharing this excellent software!

Originally created by @alfa-alex on GitHub (Sep 5, 2022). Original GitHub issue: https://github.com/axllent/mailpit/issues/12 Version 1.0.0 is out, but the API (`/api/...`) is not documented outside the code (yet?). So I'm unsure if it's just an internal API (for Frontend<->Backend communication) or whether it is safe (and stable) to use it externally? My use case is I want to run integration tests and check the mails that are being sent, so I collect the messages via the MailPit websocket endpoint. It seems quite convenient to me, but if that API is subject to change, I shall better not use it. On a side note, thanks for sharing this excellent software!

kerem closed this issue

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

kerem commented

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

Author

Owner

@axllent commented on GitHub (Sep 5, 2022):

@alfa-alex Thanks for the kind words!

You are correct, the API isn't documented as it was never intended for use outside of the integrated web UI, and is likely to change from time to time as I see fit (however that mostly relates to features such as search and message listing). I really don't intend on managing different versions of the API for the very small use-case (that I'm aware of) as it adds a relatively large overhead in terms of maintenance, especially if things change down the track. Your use case is to use the websocket just to test messages are received, but the next API user may want to read those messages, another delete messages and so on.

There is nothing stopping you from using it of course, but I cannot make any guarantees that the API won't change in future versions. In saying that, I think it's unlikely that the websocket would ever change (much?), especially if you are just detecting a signal/change (ie: something happened). You could however simply bind your tests to a particular version of Mailpit (eg: 1.0.0) - that way you get your expected results regardless if the API changes.

@axllent commented on GitHub (Sep 5, 2022): @alfa-alex Thanks for the kind words! You are correct, the API isn't documented as it was never intended for use outside of the integrated web UI, and is likely to change from time to time as I see fit (however that mostly relates to features such as search and message listing). I really don't intend on managing different versions of the API for the very small use-case (that I'm aware of) as it adds a relatively large overhead in terms of maintenance, especially if things change down the track. Your use case is to use the websocket just to test messages are received, but the next API user may want to read those messages, another delete messages and so on. There is nothing stopping you from using it of course, but I cannot make any guarantees that the API won't change in future versions. In saying that, I think it's unlikely that the websocket would ever change (much?), especially if you are just detecting a signal/change (ie: something happened). You could however simply bind your tests to a particular version of Mailpit (eg: 1.0.0) - that way you get your expected results regardless if the API changes.

kerem commented

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

Author

Owner

@alfa-alex commented on GitHub (Sep 6, 2022):

Thank you for your fast response! That was exactly what I wanted to know.

And you're right, simply sticking to the current version might be an option. Will consider that. Thanks again!

@alfa-alex commented on GitHub (Sep 6, 2022): Thank you for your fast response! That was exactly what I wanted to know. And you're right, simply sticking to the current version might be an option. Will consider that. Thanks again!

kerem commented

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

Author

Owner

@axllent commented on GitHub (Oct 7, 2022):

@alfa-alex Just a heads-up that I have now introduced and documented an API in Mailpit. This does not include the websocket (which remains the same as before) so should not impact you, however if you're intending to use the API to pull data then these changes may be of use to you.

@axllent commented on GitHub (Oct 7, 2022): @alfa-alex Just a heads-up that I have now introduced and documented an API in Mailpit. This does not include the websocket (which remains the same as before) so should not impact you, however if you're intending to use the API to pull data then these changes may be of use to you.

kerem commented

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

Author

Owner

@alfa-alex commented on GitHub (Oct 10, 2022):

Thanks you for the heads-up! At the moment, the API is missing one feature I'm using, but I've commented on that in #15 because I think it belongs there.

On a side note, the websocket approach worked very well (although I'm only using it to receive the IDs of new mails at the moment - I still fetch the emails subsequently to get all the headers and the body).

@alfa-alex commented on GitHub (Oct 10, 2022): Thanks you for the heads-up! At the moment, the API is missing one feature I'm using, but I've commented on that in #15 because I think it belongs there. On a side note, the websocket approach worked very well (although I'm only using it to receive the IDs of new mails at the moment - I still fetch the emails subsequently to get all the headers and the body).