[GH-ISSUE #15] OpenAPI Specification

kerem commented

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

Owner

Originally created by @antonkomarev on GitHub (Sep 28, 2022).
Original GitHub issue: https://github.com/axllent/mailpit/issues/15

It would be great if project will have OpenAPI Spec describing the backend API.

Originally created by @antonkomarev on GitHub (Sep 28, 2022). Original GitHub issue: https://github.com/axllent/mailpit/issues/15 It would be great if project will have OpenAPI Spec describing the backend API.

kerem

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

closed this issue
added the
documentation
label

kerem commented

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

Author

Owner

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

@antonkomarev Sorry, I have no intention at this stage to maintain an API intended for use for anything other than the web UI, hence why it is not documented. This way it remains flexible for the web UI's requirements, I can change what I like when it suits, and does not mean any commitment from my end to add & maintain features the web UI doesn't use.

May I ask why you are wanting API documentation, as in what exactly are you wanting to use the API for?

@axllent commented on GitHub (Sep 28, 2022): @antonkomarev Sorry, I have no intention at this stage to maintain an API intended for use for anything other than the web UI, hence why it is not documented. This way it remains flexible for the web UI's requirements, I can change what I like when it suits, and does not mean any commitment from my end to add & maintain features the web UI doesn't use. May I ask why you are wanting API documentation, as in what exactly are you wanting to use the API for?

kerem commented

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

Author

Owner

@antonkomarev commented on GitHub (Sep 28, 2022):

Our QA team is writing automation tools to check if email was sent and check it's content.

Right now they are using Mailhog API, and we want to migrate to Mailpit.

@antonkomarev commented on GitHub (Sep 28, 2022): Our QA team is writing automation tools to check if email was sent and check it's content. Right now they are using Mailhog API, and we want to migrate to Mailpit.

kerem commented

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

Author

Owner

@pxDot commented on GitHub (Sep 28, 2022):

Same for me. I wanted to give mailpit a try as a replacement for mailhog in e2e tests. Sadly I couldn't find anything on how to interact with mailpit from code. For mailhog we are currently using the client mailhog-awesome in our tests. It seems like mailpit does not offer any client to interact with, without using the web UI

@pxDot commented on GitHub (Sep 28, 2022): Same for me. I wanted to give mailpit a try as a replacement for mailhog in e2e tests. Sadly I couldn't find anything on how to interact with mailpit from code. For mailhog we are currently using the client `mailhog-awesome` in our tests. It seems like mailpit does not offer any client to interact with, without using the web UI

kerem commented

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

Author

Owner

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

Thank you both for your feedback. Clearly there is some requirement for a stable & documented API (which was also asked in issue #12), so that makes at least 3 of you.

There are some fundamental differences between MailHog and Mailpit that you should be aware of beforehand though.

Mailpit does not have the ability to release emails (relay them to another SMTP). I have no plans to add this either.
Mailpit does not have mailboxes (as mailhog-awesome appears to suggest). There is just one mailbox (I thought MailHog also only had one though).
If I was to build an official API, it would not be a drop-in replacement for MailHog's API, so existing tools like mailhog-awesome can't be used. New implementations would need to be made.
If I added an API, I would not go through the effort of using the OpenAPI Spec, it would be rather a REST-like interface that would be properly documented in Mailpit's wiki. I do not plan to create huge amounts of work for myself for something I do not use myself.
I do not intend on adding JWT API authentication, if authentication is required, then it will have to be the existing basic authentication that already exists.

Does that sound workable/ acceptable to you both for your use-cases?

@axllent commented on GitHub (Sep 28, 2022): Thank you both for your feedback. Clearly there is some requirement for a stable & documented API (which was also asked in issue #12), so that makes at least 3 of you. There are some fundamental differences between MailHog and Mailpit that you should be aware of beforehand though. - Mailpit does not have the ability to release emails (relay them to another SMTP). I have no plans to add this either. - Mailpit does not have mailboxes (as mailhog-awesome appears to suggest). There is just one mailbox (I thought MailHog also only had one though). - If I was to build an official API, it would not be a drop-in replacement for MailHog's API, so existing tools like mailhog-awesome can't be used. New implementations would need to be made. - If I added an API, I would not go through the effort of using the OpenAPI Spec, it would be rather a REST-like interface that would be properly documented in Mailpit's wiki. I do not plan to create huge amounts of work for myself for something I do not use myself. - I do not intend on adding JWT API authentication, if authentication is required, then it will have to be the existing basic authentication that already exists. Does that sound workable/ acceptable to you both for your use-cases?

kerem commented

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

Author

Owner

@pxDot commented on GitHub (Sep 29, 2022):

Mailpit does not have the ability to release emails (relay them to another SMTP). I have no plans to add this either.

Not needed in my case. In e2e tests I just need to check if mails are coming in and testing some mail content.

Mailpit does not have mailboxes (as mailhog-awesome appears to suggest). There is just one mailbox (I thought MailHog also only had one though).

Mailboxes in mailhog-awesome are virtual anyways (e.g. get only emails addressed to a specific email address), as the underlying mailhog does not support mailboxes. So its basically just a search. mailhog-awesome is just a client library for the mailhog API anyways.

Sounds totally workable for me. Thank you for your efforts. This looks like a very promising library already.

@pxDot commented on GitHub (Sep 29, 2022): > Mailpit does not have the ability to release emails (relay them to another SMTP). I have no plans to add this either. Not needed in my case. In e2e tests I just need to check if mails are coming in and testing some mail content. > Mailpit does not have mailboxes (as mailhog-awesome appears to suggest). There is just one mailbox (I thought MailHog also only had one though). Mailboxes in mailhog-awesome are virtual anyways (e.g. get only emails addressed to a specific email address), as the underlying mailhog does not support mailboxes. So its basically just a search. `mailhog-awesome` is just a client library for the mailhog API anyways. Sounds totally workable for me. Thank you for your efforts. This looks like a very promising library already.

kerem commented

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

Author

Owner

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

Thanks again for the information, confirmation and support. It is clear to me now that this is a need-to-have feature rather than a nice-to-have feature to allow you to integrate with Mailpit, so I will put this on my development roadmap for the near future 👍

@axllent commented on GitHub (Sep 29, 2022): Thanks again for the information, confirmation and support. It is clear to me now that this is a need-to-have feature rather than a nice-to-have feature to allow you to integrate with Mailpit, so I will put this on my development roadmap for the near future :+1:

kerem commented

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

Author

Owner

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

@antonkomarev & @squareloop1 - I have just released 1.2.0 which now includes a simple REST API. The documentation was the hardest & most time-consuming part so I have kept it as simple as I could.

Please let me know if this is what you were wanting (for your integrations), and of course if you have any questions or comments.

@axllent commented on GitHub (Oct 7, 2022): @antonkomarev & @squareloop1 - I have just released 1.2.0 which now includes a simple REST API. [The documentation](https://github.com/axllent/mailpit/blob/develop/docs/apiv1/README.md) was the hardest & most time-consuming part so I have kept it as simple as I could. Please let me know if this is what you were wanting (for your integrations), and of course if you have any questions or comments.

kerem commented

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

Author

Owner

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

Very nice. The documentation is perfectly sufficient IMO. What I am missing for my use case is a way to retrieve all headers (even custom ones).

Not sure how to incorporate this into the API, though. Would it be a viable option to add a JSON object Headers containing all header key/value pairs to the Message response?

@alfa-alex commented on GitHub (Oct 10, 2022): Very nice. The documentation is perfectly sufficient IMO. What I am missing for my use case is a way to retrieve all headers (even custom ones). Not sure how to incorporate this into the API, though. Would it be a viable option to add a JSON object `Headers` containing all header key/value pairs to the `Message` response?

kerem commented

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

Author

Owner

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

@alfa-alex Thanks for the feedback. I understand what you are asking, and technically this is something I could add to the API, however there are a few considerations to discuss first.

Firstly the RAW data can be parsed from api/v1/message/<ID>/raw - however would need to be manually extracted / pased by whatever you are using. I realize this is less than ideal. I could include a list of headers in the api/v1/message/<ID> request, but there are some considerations / limitations:

Each header key can be included only once. The email parsing library I use does return a list of unique header keys, and so is possible to return the header key value, but if a header is included more than one (eg: Received which is normally listed multiple times in headers) then only the first one is included/parsed. This may or may not be desirable depending on your requirements.
It would add a lot of crud (data) to every request if I included it in api/v1/message/<ID>, so adding a 20-50% size of the request.
I could add this as a separate API end-point (eg: api/v1/message/<ID>/headers) but it would mean an extra request from your end (I think this is a better option that 2 above).

If you can confirm please what data you are wanting to extract, and whether those headers would potentially be listed multiple times in an actual email, then I can consider the best approach.

@axllent commented on GitHub (Oct 11, 2022): @alfa-alex Thanks for the feedback. I understand what you are asking, and technically this is something I could add to the API, however there are a few considerations to discuss first. Firstly the RAW data can be parsed from `api/v1/message/<ID>/raw` - however would need to be manually extracted / pased by whatever you are using. I realize this is less than ideal. I could include a list of headers in the `api/v1/message/<ID>` request, but there are some considerations / limitations: 1. Each header key can be included only once. The email parsing library I use does return a list of unique header keys, and so is possible to return the header key value, but if a header is included more than one (eg: `Received` which is normally listed multiple times in headers) then only the first one is included/parsed. This may or may not be desirable depending on your requirements. 2. It would add a lot of crud (data) to every request if I included it in `api/v1/message/<ID>`, so adding a 20-50% size of the request. 3. I could add this as a separate API end-point (eg: `api/v1/message/<ID>/headers`) but it would mean an extra request from your end (I think this is a better option that 2 above). If you can confirm please what data you are wanting to extract, and whether those headers would potentially be listed multiple times in an actual email, then I can consider the best approach.

kerem commented

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

Author

Owner

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

Thank you. I don't deal with headers that occur multiple times at the moment and I can't think of a use case for that yet. In addition, neither large replies, nor the need of making an additional request would represent a problem for me. So for me options 2 and 3 would be equally fine.

@alfa-alex commented on GitHub (Oct 12, 2022): Thank you. I don't deal with headers that occur multiple times at the moment and I can't think of a use case for that yet. In addition, neither large replies, nor the need of making an additional request would represent a problem for me. So for me options 2 and 3 would be equally fine.

kerem commented

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

Author

Owner

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

I actually just discovered that the built-in Go mail parsing does handle multiple headers returning a [string][]string format - so each header key (eg: Delivered-To) has an array of 1 or more results.

{
  "Content-Type": [
    "multipart/related; type=\"multipart/alternative\"; boundary=\"----=_NextPart_000_0013_01C6A60C.47EEAB80\""
  ],
  "Date": [
    "Wed, 12 Jul 2006 23:38:30 +1200"
  ],
  "Delivered-To": [
    "user@example.com",
    "user-alias@example.com"
  ],
  "From": [
    "\"User Name\" \\u003remote@example.com\\u003e"
  ],
  "Message-Id": [
    "\\u003c001701c6a5a7$b3205580$0201010a@HomeOfficeSM\\u003e"
  ],
....

It's not pretty, but it does cater for repeated keys (of which there are actually quite a few), and avoids the situation whereby you or someone else may want all the headers for any key, not just the first. All you'd have to do is get the first in your case, eg: headers["From"][0].

I will add this for you as a separate API end point api/v1/message/<ID>/headers in the next couple of days 👍

@axllent commented on GitHub (Oct 12, 2022): I actually just discovered that the built-in Go mail parsing does handle multiple headers returning a `[string][]string` format - so each header key (eg: `Delivered-To`) has an array of 1 or more results. ```json { "Content-Type": [ "multipart/related; type=\"multipart/alternative\"; boundary=\"----=_NextPart_000_0013_01C6A60C.47EEAB80\"" ], "Date": [ "Wed, 12 Jul 2006 23:38:30 +1200" ], "Delivered-To": [ "user@example.com", "user-alias@example.com" ], "From": [ "\"User Name\" \\u003remote@example.com\\u003e" ], "Message-Id": [ "\\u003c001701c6a5a7$b3205580$0201010a@HomeOfficeSM\\u003e" ], .... ``` It's not pretty, but it does cater for repeated keys (of which there are actually quite a few), and avoids the situation whereby you or someone else may want all the headers for any key, not just the first. All you'd have to do is get the first in your case, eg: `headers["From"][0]`. I will add this for you as a separate API end point `api/v1/message/<ID>/headers` in the next couple of days :+1:

kerem commented

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

Author

Owner

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

@alfa-alex The header API has now been released as 1.2.2. Please let me know how you get on with your integration, and whether this meets your requirements?

@axllent commented on GitHub (Oct 13, 2022): @alfa-alex The header API has now been released as 1.2.2. Please let me know how you get on with your integration, and whether this meets your requirements?

kerem commented

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

Author

Owner

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

Thank you so much! It'll probably take a while until I can make that implementation, but the API looks very promising - I might even drop the use of the websocket API entirely and exclusively rely on the stable API now it has all these nice features. 🎉

@alfa-alex commented on GitHub (Oct 13, 2022): Thank you so much! It'll probably take a while until I can make that implementation, but the API looks very promising - I might even drop the use of the websocket API entirely and exclusively rely on the stable API now it has all these nice features. :tada:

kerem commented

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

Author

Owner

@osipovamarya commented on GitHub (Oct 13, 2022):

Thank you very much! You did a great job. This API will come in very handy in our work. However, in the previous implementation we used limits in /search endpoint. It would be great if you could add them here.

Best solution for us would be to add query param like &limit=

@osipovamarya commented on GitHub (Oct 13, 2022): Thank you very much! You did a great job. This API will come in very handy in our work. However, in the previous implementation we used limits in **/search** endpoint. It would be great if you could add them here. Best solution for us would be to add query param like &limit=

kerem commented

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

Author

Owner

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

@osipovamarya I have just added both a limit (default 50) and start (default 0) to the api/v1/search API 👍 This means that the search can now also be paginated exactly like the message listing. See docs.

@axllent commented on GitHub (Oct 14, 2022): @osipovamarya I have just added both a `limit` (default 50) and `start` (default 0) to the `api/v1/search` API :+1: This means that the search can now also be paginated exactly like the message listing. [See docs](https://github.com/axllent/mailpit/blob/develop/docs/apiv1/Search.md).

kerem commented

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

Author

Owner

@osipovamarya commented on GitHub (Oct 15, 2022):

Thank you! That's exactly what we needed.

@osipovamarya commented on GitHub (Oct 15, 2022): Thank you! That's exactly what we needed.

kerem commented

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

Author

Owner

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

I'm closing this issue as I believe it is complete. Any new issues relating to this should be added as a new issue, thanks.

@axllent commented on GitHub (Oct 15, 2022): I'm closing this issue as I believe it is complete. Any new issues relating to this should be added as a new issue, thanks.

kerem commented

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

Author

Owner

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

@alfa-alex The header API has now been released as 1.2.2. Please let me know how you get on with your integration, and whether this meets your requirements?

Finally got around to doing the integration. The API is awesome! Works like a charm.

There's only one request I have to make my life even more convenient: The structs used for the API response are currently a bit scattered over the project (like apiv1.MessagesResult and storage.Message or storage.Summary). Is there any chance you could provide these structs in a central place (perhaps apiv1 is the right package already) and allow/encourage them being imported from client projects? That would be extremely handy!

I'm not fully into the internals, but maybe you could do a simple type alias (type MessageSummary = storage.Summary) in the apiv1 package so you don't need to copy them as long as v1 is the latest API. Once you internally switch to something else you could change the type alias to become the struct that resembles whatever the APIv1 returns.

@alfa-alex commented on GitHub (Oct 20, 2022): > @alfa-alex The header API has now been released as 1.2.2. Please let me know how you get on with your integration, and whether this meets your requirements? Finally got around to doing the integration. The API is awesome! Works like a charm. There's only one request I have to make my life even more convenient: The structs used for the API response are currently a bit scattered over the project (like `apiv1.MessagesResult` and `storage.Message` or `storage.Summary`). Is there any chance you could provide these structs in a central place (perhaps `apiv1` is the right package already) and allow/encourage them being imported from client projects? That would be extremely handy! I'm not fully into the internals, but maybe you could do a simple type alias (`type MessageSummary = storage.Summary`) in the `apiv1` package so you don't need to copy them as long as `v1` is the latest API. Once you internally switch to something else you could change the type alias to become the struct that resembles whatever the APIv1 returns.

kerem commented

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

Author

Owner

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

Any new issues relating to this should be added as a new issue, thanks.

@alfa-alex Please open a new issue, thanks

@axllent commented on GitHub (Oct 20, 2022): > Any new issues relating to this should be added as a new issue, thanks. @alfa-alex Please open a new issue, thanks

Rows
Columns

[GH-ISSUE #15] OpenAPI Specification #13