From bc200c663f09181300c60c3ee89b8b8d16b431b0 Mon Sep 17 00:00:00 2001
From: Ralph Slooten <axllent@gmail.com>
Date: Tue, 13 May 2025 19:27:27 +1200
Subject: [PATCH] Docs: Add Message ListUnsubscribe to swagger / API
 documentation (#494)

---
 internal/storage/structs.go   |  7 +++----
 server/ui/api/v1/swagger.json | 29 +++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/internal/storage/structs.go b/internal/storage/structs.go
index 1ea1ad3..b9e9fc7 100644
--- a/internal/storage/structs.go
+++ b/internal/storage/structs.go
@@ -28,7 +28,6 @@ type Message struct {
 	// Message subject
 	Subject string
 	// List-Unsubscribe header information
-	// swagger:ignore
 	ListUnsubscribe ListUnsubscribe
 	// Message date if set, else date received
 	Date time.Time
@@ -117,10 +116,10 @@ type DBMailSummary struct {
 type ListUnsubscribe struct {
 	// List-Unsubscribe header value
 	Header string
-	// Detected links, maximum one email and one HTTP(S)
+	// Detected links, maximum one email and one HTTP(S) link
 	Links []string
-	// Validation errors if any
+	// Validation errors (if any)
 	Errors string
-	// List-Unsubscribe-Post value if set
+	// List-Unsubscribe-Post value (if set)
 	HeaderPost string
 }
diff --git a/server/ui/api/v1/swagger.json b/server/ui/api/v1/swagger.json
index 03f8a0c..2a162c9 100644
--- a/server/ui/api/v1/swagger.json
+++ b/server/ui/api/v1/swagger.json
@@ -1436,6 +1436,32 @@
       "x-go-name": "Response",
       "x-go-package": "github.com/axllent/mailpit/internal/linkcheck"
     },
+    "ListUnsubscribe": {
+      "description": "ListUnsubscribe contains a summary of List-Unsubscribe \u0026 List-Unsubscribe-Post headers\nincluding validation of the link structure",
+      "type": "object",
+      "properties": {
+        "Errors": {
+          "description": "Validation errors (if any)",
+          "type": "string"
+        },
+        "Header": {
+          "description": "List-Unsubscribe header value",
+          "type": "string"
+        },
+        "HeaderPost": {
+          "description": "List-Unsubscribe-Post value (if set)",
+          "type": "string"
+        },
+        "Links": {
+          "description": "Detected links, maximum one email and one HTTP(S) link",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "x-go-package": "github.com/axllent/mailpit/internal/storage"
+    },
     "Message": {
       "description": "Message data excluding physical attachments",
       "type": "object",
@@ -1484,6 +1510,9 @@
             "$ref": "#/definitions/Attachment"
           }
         },
+        "ListUnsubscribe": {
+          "$ref": "#/definitions/ListUnsubscribe"
+        },
         "MessageID": {
           "description": "Message ID",
           "type": "string"