[GH-ISSUE #119] [Suggestion] Tags from custom header

kerem commented

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

Owner

Originally created by @tminich on GitHub (May 31, 2023).
Original GitHub issue: https://github.com/axllent/mailpit/issues/119

Just discovered mailpit and so far loving what I see. One thing that immediately crossed my mind was the ability to set tags via a custom mail header (e.g. a comma (or whatever) separated list in X-Mailpit-Tags). We are currently using mailhog as a central mail debugging tool for several applications and it would be very helpful if, after we switch to mailpit, we could achieve automatic tagging 'pushed' by the applications so we can easily filter by source.

Originally created by @tminich on GitHub (May 31, 2023). Original GitHub issue: https://github.com/axllent/mailpit/issues/119 Just discovered mailpit and so far loving what I see. One thing that immediately crossed my mind was the ability to set tags via a custom mail header (e.g. a comma (or whatever) separated list in X-Mailpit-Tags). We are currently using mailhog as a central mail debugging tool for several applications and it would be very helpful if, after we switch to mailpit, we could achieve automatic tagging 'pushed' by the applications so we can easily filter by source.

kerem closed this issue

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

kerem commented

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

Author

Owner

@axllent commented on GitHub (Jun 1, 2023):

@tminich This is a fantastic idea, thanks! I am however wary of two things worth consideration:

Currently tags are loaded simply like a search (eg: tag:test to filter by the "test" tag). This is not a mailbox as such, just a filter that gets applied for all messages. This means that when viewing a tag, it is treated just like a search - no pagination, and a maximum of 200 results. The reason for no pagination and 200 results is it is expensive (CPU / database) to search/filter, unlike just browsing the inbox itself. The other downside is that tags do not display total (unread messages) for the same reason, and new messages are not "refreshed automatically" when viewing a tag. Do you see this (only seeing the latest 200 messages in any single tag) as a problem?
Given that tags are translated to searches, there are restrictions around the characters allowed in tag names. Currently I can validate this on startup (if one uses the auto-tag option) and when tags are manually applied in the web UI, however if they are supplied within such a header there would be no interactive validation, so invalid tags will just get silently ignored (the tags, not the messages). Yes I can provide a warning in the Mailbox console (server) eg: ignoring invalid tag "blaah<D>%", but that's about all. Do you see this as a problem?

I image something like a comma-separated header eg X-Mailpit-tags: This is a tag, This is another, Another (or even possibly just X-Tags:) as a feasible option, I'm just a big concerned about the expectation for someone using this.

Keen to get your feedback / thoughts.

@axllent commented on GitHub (Jun 1, 2023): @tminich This is a fantastic idea, thanks! I am however wary of two things worth consideration: 1. Currently tags are loaded simply like a search (eg: `tag:test` to filter by the "test" tag). This is not a mailbox as such, just a filter that gets applied for all messages. This means that when viewing a tag, it is treated just like a search - no pagination, and a maximum of 200 results. The reason for no pagination and 200 results is it is expensive (CPU / database) to search/filter, unlike just browsing the inbox itself. The other downside is that tags do not display total (unread messages) for the same reason, and new messages are not "refreshed automatically" when viewing a tag. Do you see this (only seeing the latest 200 messages in any single tag) as a problem? 2. Given that tags are translated to searches, there are restrictions around the characters allowed in tag names. Currently I can validate this on startup (if one uses the [auto-tag option](https://github.com/axllent/mailpit/wiki/Tagging#automatically-tagging-messages)) and when tags are manually applied in the web UI, however if they are supplied within such a header there would be no interactive validation, so invalid tags will just get silently ignored (the tags, not the messages). Yes I can provide a warning in the Mailbox console (server) eg: `ignoring invalid tag "blaah<D>%"`, but that's about all. Do you see this as a problem? I image something like a comma-separated header eg `X-Mailpit-tags: This is a tag, This is another, Another` (or even possibly just `X-Tags:`) as a feasible option, I'm just a big concerned about the expectation for someone using this. Keen to get your feedback / thoughts.

kerem commented

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

Author

Owner

@tminich commented on GitHub (Jun 1, 2023):

By adding an disclaimer to the documentation I think the restrictions are perfectly fine. Maybe trying to sanitize tags by dropping/replacing invalid characters would be better instead of silently ignoring the whole tag though.

One thing that would be beneficial in general for searches, be it tags or other, is a delete all button that applies to the search results. With automated tags I imagine that could be a common use case.
Performance in this case should not be an issue for the user (imo), a delete is expected to take some time.

@tminich commented on GitHub (Jun 1, 2023): By adding an disclaimer to the documentation I think the restrictions are perfectly fine. Maybe trying to sanitize tags by dropping/replacing invalid characters would be better instead of silently ignoring the whole tag though. One thing that would be beneficial in general for searches, be it tags or other, is a delete all button that applies to the search results. With automated tags I imagine that could be a common use case. Performance in this case should not be an issue for the user (imo), a delete is expected to take some time.

kerem commented

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

Author

Owner

@maleoadvfr commented on GitHub (Jun 1, 2023):

Hi, I've been using Mailpit for a while now and I'm very happy with it.

Managing several projects, I would indeed be interested in being able to add tags via a specific header in my emails.

I had started by looking in the documentation if it was possible but no 😅

X-Tags would be nice 👍

@maleoadvfr commented on GitHub (Jun 1, 2023): Hi, I've been using Mailpit for a while now and I'm very happy with it. Managing several projects, I would indeed be interested in being able to add tags via a specific header in my emails. I had started by looking in the documentation if it was possible but no 😅 `X-Tags` would be nice 👍

kerem commented

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

Author

Owner

@axllent commented on GitHub (Jun 2, 2023):

I have just added X-Tags support in message headers used to set tags in Mailpit (I still need to document this, but I've run out of time right now). In essence, tags can be added via a comma-separated X-Tags: tag1, tag 2, this is a long tag in the message headers. Tags are "cleaned" to only support certain characters, and only if the tag (after cleaning) is less than 3 characters is it silently ignored.

In relation to this, I have also added a feature which lets you delete the current search results, or mark them as read. This applies to any search. It will only delete or mark up to 200 search results (ie: those displayed on-screen) as that is what is returned by the search, so if your tag has > 200 messages, you may have to run through it a couple of times to delete all.

This new functionality has just been released as v1.6.14 - please let me know if this works for you both?

@axllent commented on GitHub (Jun 2, 2023): I have just added `X-Tags` support in message headers used to set tags in Mailpit (I still need to document this, but I've run out of time right now). In essence, tags can be added via a comma-separated `X-Tags: tag1, tag 2, this is a long tag` in the message headers. Tags are "cleaned" to only support certain characters, and only if the tag (after cleaning) is less than 3 characters is it silently ignored. In relation to this, I have also added a feature which lets you delete the current search results, or mark them as read. This applies to any search. It will only delete or mark up to 200 search results (ie: those displayed on-screen) as that is what is returned by the search, so if your tag has > 200 messages, you may have to run through it a couple of times to delete all. This new functionality has just been released as v1.6.14 - please let me know if this works for you both?

kerem commented

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

Author

Owner

@tminich commented on GitHub (Jun 2, 2023):

Sounds pretty much perfect to me, thanks a lot!

@tminich commented on GitHub (Jun 2, 2023): Sounds pretty much perfect to me, thanks a lot!

kerem commented

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

Author

Owner

@maleoadvfr commented on GitHub (Jun 2, 2023):

Hi, I just tested the X-Tags header and it's OK, thank you very much! 🙏

@maleoadvfr commented on GitHub (Jun 2, 2023): Hi, I just tested the X-Tags header and it's OK, thank you very much! 🙏

kerem commented

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

Author

Owner

@axllent commented on GitHub (Jun 2, 2023):

You're both welcome, and thanks again for the suggestion 👍 I'm closing this as completed, but let me know if you have any issues.

@axllent commented on GitHub (Jun 2, 2023): You're both welcome, and thanks again for the suggestion :+1: I'm closing this as completed, but let me know if you have any issues.

kerem commented

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

Author

Owner

@tminich commented on GitHub (Jun 2, 2023):

Thanks again, just tried the feature, works perfectly fine.

One thing I came across is if the header occurs multiple times only the first one is evaluated. Personally I didn't even think of that because I was unaware that that's actually valid in mails (until I looked into the code of how Larvel/Symfony store them in the Message class...).
As mailpit handles multiple occurrences of the same header fine in the headers tab it probably should also be handled when parsing the tags. It would certainly make it easier to add tags during message processing (e.g. adding an application level tag just before sending when there might have been one or more added specific to the message earlier).

@tminich commented on GitHub (Jun 2, 2023): Thanks again, just tried the feature, works perfectly fine. One thing I came across is if the header occurs multiple times only the first one is evaluated. Personally I didn't even think of that because I was unaware that that's actually valid in mails (until I looked into the code of how Larvel/Symfony store them in the Message class...). As mailpit handles multiple occurrences of the same header fine in the headers tab it probably should also be handled when parsing the tags. It would certainly make it easier to add tags during message processing (e.g. adding an application level tag just before sending when there might have been one or more added specific to the message earlier).

kerem commented

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

Author

Owner

@axllent commented on GitHub (Jun 2, 2023):

@tminich Yes and no. I understand what you are asking, but I don't fully agree. Email headers serve two purposes - defining a value (eg: From, To, Cc, Subject etc), and a "running log" (Received, ARC-Seal etc). What you are requesting is that X-Tags acts like a log, rather than a value.

I think that you should be setting, not adding the X-Tag header (I haven't looked at Symfony src but I assume this is possible). If it is your intention to append to existing tags (if already set), then that logic should be in your app.

@axllent commented on GitHub (Jun 2, 2023): @tminich Yes and no. I understand what you are asking, but I don't fully agree. Email headers serve two purposes - defining a value (eg: `From`, `To`, `Cc`, `Subject` etc), and a "running log" (`Received`, `ARC-Seal` etc). What you are requesting is that `X-Tags` acts like a log, rather than a value. I think that you should be setting, not adding the X-Tag header (I haven't looked at Symfony src but I assume this is possible). If it is your intention to append to existing tags (if already set), then that logic should be in your app.

kerem commented

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

Author

Owner

@tminich commented on GitHub (Jun 5, 2023):

Fair point, I'll do it like that.

@tminich commented on GitHub (Jun 5, 2023): Fair point, I'll do it like that.

kerem referenced this issue

2026-03-15 14:18:49 +03:00

[PR #81] [MERGED] Bump actions/setup-go from 3 to 4 #436

Rows
Columns

[GH-ISSUE #119] [Suggestion] Tags from custom header #81