From e3e4654507f089ba626dbe34151dec8a45dc0662 Mon Sep 17 00:00:00 2001
From: Joe Banks <joe@jb3.dev>
Date: Wed, 14 Aug 2024 23:14:42 +0100
Subject: [PATCH] Add docs on parsing mail in scripts

---
 docs/docs/services/email/mail-services.md | 26 +++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/docs/services/email/mail-services.md b/docs/docs/services/email/mail-services.md
index 134ab392..1c98821d 100644
--- a/docs/docs/services/email/mail-services.md
+++ b/docs/docs/services/email/mail-services.md
@@ -62,3 +62,29 @@ Ideal use-cases for service mail are:
 Anything that is sensitive or otherwise not suited should instead be implemented
 as a feature on King Arthur or any other system with fine-grained access
 control.
+
+### Parsing Mail
+
+In scripts, you should use
+[`mblaze`](https://manpages.ubuntu.com/manpages/focal/en/man7/mblaze.7.html)
+utilities to parse inbound mail to scripts to avoid issues that may arise from
+manually parsing email files.
+
+As an example, from the `fortune@int.pydis.wtf` service:
+
+```sh
+# Read the entire email into a variable
+EMAIL=$(cat)
+
+# Extract the sender's email address
+SENDER=$(echo "$EMAIL" | maddr -a -h from -)
+
+# Extract the Message-ID of the original email
+MESSAGE_ID=$(echo "$EMAIL" | mhdr -h message-id -)
+
+# Extract the original Subject and prefix it with "Re: " if necessary
+ORIGINAL_SUBJECT=$(echo "$EMAIL" | mhdr -h subject -)
+
+# Construct the reply subject
+REPLY_SUBJECT="Re: $ORIGINAL_SUBJECT"
+```