From 91b0c19fe822389b3d9ed506c0dc5703ae6dd81c Mon Sep 17 00:00:00 2001
From: Aki Tuomi <aki.tuomi@open-xchange.com>
Date: Thu, 9 Apr 2026 19:35:01 +0300
Subject: [PATCH] sieve: Add examples

---
 .../core/config/sieve/extensions/duplicate.md | 29 +++++++++++++++++++
 .../config/sieve/extensions/editheader.md     | 12 ++++++++
 docs/core/config/sieve/extensions/include.md  | 11 +++++++
 .../sieve/extensions/spamtest_virustest.md    | 13 +++++++++
 docs/core/config/sieve/extensions/vacation.md | 12 ++++++++
 .../core/config/sieve/extensions/variables.md | 17 +++++++++++
 docs/core/plugins/sieve_extprograms.md        | 11 +++++++
 7 files changed, 105 insertions(+)

diff --git a/docs/core/config/sieve/extensions/duplicate.md b/docs/core/config/sieve/extensions/duplicate.md
index ceb7ba652..343f3fef5 100644
--- a/docs/core/config/sieve/extensions/duplicate.md
+++ b/docs/core/config/sieve/extensions/duplicate.md
@@ -41,3 +41,32 @@ sieve_script personal {
 sieve_duplicate_default_period = 1h
 sieve_duplicate_max_period = 1d
 ```
+
+## Sieve Example
+
+```sieve
+require ["duplicate"];
+
+if duplicate {
+  discard;
+  stop;
+}
+```
+
+This example discards duplicate messages based on the default message ID tracking.
+
+## Advanced Sieve Example
+
+```sieve
+require ["duplicate", "fileinto"];
+
+if duplicate :header "Message-ID" {
+  fileinto "Duplicates";
+  stop;
+}
+
+fileinto "Inbox";
+```
+
+This example uses the `Message-ID` header explicitly and files duplicate
+messages into a dedicated mailbox instead of discarding them.
diff --git a/docs/core/config/sieve/extensions/editheader.md b/docs/core/config/sieve/extensions/editheader.md
index eb1991319..0e146f99c 100644
--- a/docs/core/config/sieve/extensions/editheader.md
+++ b/docs/core/config/sieve/extensions/editheader.md
@@ -40,3 +40,15 @@ sieve_editheader_header X-Seen {
   forbid_delete = yes
 }
 ```
+
+## Sieve Example
+
+```sieve
+require ["editheader"];
+
+deleteheader "X-Spam-Flag";
+addheader "X-Processed-By" "Dovecot Sieve";
+```
+
+This example removes an existing header field and adds a new header field to
+mark the message as processed.
diff --git a/docs/core/config/sieve/extensions/include.md b/docs/core/config/sieve/extensions/include.md
index 478756363..1898681c3 100644
--- a/docs/core/config/sieve/extensions/include.md
+++ b/docs/core/config/sieve/extensions/include.md
@@ -24,3 +24,14 @@ The include extension is available by default.
 ### Settings
 
 <SettingsComponent tag="sieve-include" level="3" />
+
+## Sieve Example
+
+```sieve
+require ["include"];
+
+include :personal "spam_rules";
+```
+
+This example includes a personal Sieve script named `spam_rules` from the
+user's script storage.
diff --git a/docs/core/config/sieve/extensions/spamtest_virustest.md b/docs/core/config/sieve/extensions/spamtest_virustest.md
index f191c0e95..2ee065faf 100644
--- a/docs/core/config/sieve/extensions/spamtest_virustest.md
+++ b/docs/core/config/sieve/extensions/spamtest_virustest.md
@@ -125,3 +125,16 @@ sieve_virustest_text_value {
 }
 ```
 :::
+
+## Sieve Example
+
+```sieve
+require ["spamtest", "fileinto", "relational", "comparator-i;ascii-numeric"];
+
+if spamtest :value "ge" :comparator "i;ascii-numeric" "5" {
+  fileinto "Spam";
+}
+```
+
+This example files messages into the Spam folder when the spam score
+meets or exceeds the configured threshold.
diff --git a/docs/core/config/sieve/extensions/vacation.md b/docs/core/config/sieve/extensions/vacation.md
index ad2e4ecd3..e29c51f90 100644
--- a/docs/core/config/sieve/extensions/vacation.md
+++ b/docs/core/config/sieve/extensions/vacation.md
@@ -109,3 +109,15 @@ sieve_vacation_default_period = 10d
 # Thirty days at maximum
 sieve_vacation_max_period = 30d
 ```
+
+## Sieve Example
+
+```sieve
+require ["vacation"];
+
+vacation :days 7
+  :subject "Out of office"
+  "I am currently away and will reply when I return.";
+```
+
+This example sends an automatic reply at most once every 7 days per sender.
diff --git a/docs/core/config/sieve/extensions/variables.md b/docs/core/config/sieve/extensions/variables.md
index 22ba30f1f..d0c1fcd6b 100644
--- a/docs/core/config/sieve/extensions/variables.md
+++ b/docs/core/config/sieve/extensions/variables.md
@@ -17,3 +17,20 @@ The variables extension is available by default.
 ### Settings
 
 <SettingsComponent tag="sieve-variables" level="3" />
+
+## Sieve Example
+
+```sieve
+require ["variables", "header", "fileinto"];
+
+if header :matches "Subject" "*" {
+  set "subject" "${1}";
+}
+
+if string :contains "${subject}" "report" {
+  fileinto "Reports";
+}
+```
+
+This example extracts the Subject header into a variable and files matching
+messages into a folder based on its contents.
diff --git a/docs/core/plugins/sieve_extprograms.md b/docs/core/plugins/sieve_extprograms.md
index 2a0dc51aa..5075975e9 100644
--- a/docs/core/plugins/sieve_extprograms.md
+++ b/docs/core/plugins/sieve_extprograms.md
@@ -269,3 +269,14 @@ the sender address and a time interval specified in seconds. The time
 interval is used to specify the minimum amount of time that needs to have
 passed since the sender was last seen. If the script returns exit code 0,
 then message is redirected in the Sieve script shown above.
+
+## Sieve Example
+
+```sieve
+require ["vnd.dovecot.pipe"];
+
+pipe "process-message";
+```
+
+This example pipes the message to an external program named
+`process-message`, which must be configured and available via the plugin.