Emails need metadata in the headers (e.g. repo, notice kind, issue state)

[6543]

Emails should have some basic metadata in the headers to convey this information:

• forge identifier
• repository identifier
• notice kind (mention, new issue, issue comment, commit alert, new assignment, etc)
• issue number & state (if it's an issue, state whether the issue is open, closed, etc)
• unsubscribe link (a unique link to enable recipients to unwatch a topic without having to login)

Github does this relatively well and I suggest modeling somewhat after Github. E.g.

X-GitHub-Sender: Alice
X-GitHub-Recipient: Bob
X-GitHub-Reason: mention
List-ID: guardianproject/haven <haven.guardianproject.github.com>
List-Archive: https://github.com/guardianproject/haven
List-Unsubscribe: <mailto:unsub+IKEF_yadayada_CVQAQ@reply.github.com>
X-GitHub-Recipient-Address: bob@bobsemaildomain.tld

Rationale:

It's useful for recipients to have headers by which to filter their inbound email. Advanced users write filters for tools like Procmail and Sieve, and they generally do it in a generic way. Instead of manually creating an inbox like "codeberg_repo_A" and then manually writing a filter for each repo they work on, advanced users write just one filter that parses the metadata from the headers and auto generates inboxes on-the-fly. This is particularly important for gitea because unlike Github there are many Gitea forges and projects are scattered.

forge-custom headers insufficient:

Someone raised an issue that was vaguely similar, and the solution was insufficient. They made it possible for every forge to add their own custom headers. That's useful for some things but lousy for the metadata above. It's a bad idea for every Gitea forge to customize the same basic info in different ways because it requires users to create a different mail filter for every gitea instance.

to-from-subject-body <= bad places

The suggestion to use "To", "From", "Subject", and email bodies is bad -- far from ideal. Some mail servers and processors (particularly forwarding services and tools like spamassassin) will amend/corrupt/destroy/munge/botch the following headers in various bizarre ways that makes these specific headers unsuitable for mail filtering:

• To
• From
• Subject

One mail forwarding service completely removes all traces of the original "To" address which makes life difficult, so paradoxically even the X-GitHub-Recipient-Address header is quite useful as well. The body is also a bad place because procmail code gets pretty ugly and error prone when it must look at the body, which is also slower.

---

gitea version: v1.14.2
source: https://codeberg.org/Codeberg/Community/issues/450