Add notification template docs (#597)

* Create u_e-mailcow_ui-notification-templates.de.md * Update u_e-mailcow_ui-notification-templates.de.md * Create u_e-mailcow_ui-notification-templates.en.md * Update u_e-mailcow_ui-notification-templates.de.md * Update mkdocs.yml * Fix text * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.de.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.de.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.de.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.de.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.de.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md * Update docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md --------- Co-authored-by: Peter <[email protected]>
mailcow · Aug 7, 2023 · c4a72c3 · c4a72c3
1 parent a8d022f
commit c4a72c3
Show file tree

Hide file tree

Showing 3 changed files with 87 additions and 0 deletions.
diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.de.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.de.md
@@ -0,0 +1,42 @@
+mailcow verwendet für die Benachrichtigungs-Mails die Template-Engine [Jinja](https://jinja.palletsprojects.com/).
+Durch Platzhalter können mit diesen Templates dynamische Inhalte erzeugt werden, indem bei der Ausführung diese Platzhalter mit übergeben Variablen ersetzt werden. Eine Doku zur Entwicklung von Jinja Templates findet sich [hier](https://jinja.palletsprojects.com/en/3.1.x/templates/). 
+
+Für die Templates der Benachrichtungs-Emails können die folgenden Variablen verwendet werden:
+
+## Quarantäne Template 
+
+Die bereitgestellten Variablen können auch auf GitHub aus dem Script [dovecot/quarantine_notify.py](https://github.com/mailcow/mailcow-dockerized/blob/master/data/Dockerfiles/dovecot/quarantine_notify.py#L94) entnommen werden.
+
+!!! info 
+    Das Template für die Qarantäne Mails kann man als Administrator in der Benutzeroberfläche in den globalen Quarantäne-Einstellungen bearbeiten und dort ebenso das Standard Template wiederherstellen. 
+    Code Beispiele kann man dem Standard Template entnehmen. Es kann auch auf [GitHub](https://github.com/mailcow/mailcow-dockerized/blob/master/data/assets/templates/quarantine.tpl) eingesehen werden.
+
+
+| Name           	| Inhalt                                                                                               	|
+|----------------	|------------------------------------------------------------------------------------------------------	|
+| username       	| E-Mail Adresse des Mailbox Benutzers                                                                 	|
+| counter        	| Anzahl der Nachrichten in der Quarantäne, über die in dieser Mail benachrichtigt wird                	|
+| hostname       	| Name der Mailcow Instanz (Siehe auch die Umgebungsvariable _MAILCOW_HOSTNAME_)                       	|
+| quarantine_acl 	| Einstellung der Quarantäne ACL des Benutzers (Berechtigung zur Bearbeitung von Mails in der Quarantäne) 	|
+| meta           	| Array/Liste aller Nachrichten/Einträge in der Quarantäne, über die benachrichtigt wird               	|
+| meta.qhash     	| Hashwert des Quarantäne Eintrags (Bspw für Direktlink zur Nachricht in der Quarantäne)               	|
+| meta.id        	| ID des Quarantäne Eintrags                                                                           	|
+| meta.subject   	| Titel der E-Mail des Quarantäne Eintrags                                                             	|
+| meta.score     	| Spam Score der E-Mail des Quarantäne Eintrags                                                        	|
+| meta.sender    	| Absender Adresse der E-Mail des Quarantäne Eintrags                                                  	|
+| meta.created   	| Datum der Erstellung des Quarantäne Eintrags, bzw Empfang der E-Mail                                 	|
+| meta.action    	| Aktion des Spamfilters (Verschoben in Spam-Ordner oder in die Quarantäne)                            	|
+
+## Quota Template
+
+Die bereitgestellten Variablen können auch auf GitHub aus dem Script [dovecot/quota_notify.py](https://github.com/mailcow/mailcow-dockerized/blob/master/data/Dockerfiles/dovecot/quota_notify.py#L45) entnommen werden.
+
+!!! info 
+    Das Template für die Quota Mails kann man als Administrator in der Benutzeroberfläche in den Quota-Einstellungen bearbeiten und dort ebenso das Standard Template wiederherstellen. 
+    Code Beispiele kann man dem Standard Template entnehmen. Es kann auch auf [GitHub](https://github.com/mailcow/mailcow-dockerized/blob/master/data/assets/templates/quota.tpl) eingesehen werden.
+
+| Name           	| Inhalt                                                                                               	|
+|----------------	|------------------------------------------------------------------------------------------------------	|
+| username       	| E-Mail Adresse des Mailbox Benutzers                                                                 	|
+| percent        	| Prozentualer Anteil des belegten Speicherplatzes der Mailbox                                        	|
+
diff --git a/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md b/docs/manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md
@@ -0,0 +1,42 @@
+mailcow uses the template engine [Jinja](https://jinja.palletsprojects.com/) for the notification mails.
+Placeholders can be used to create dynamic content with these templates by replacing them with passed variables during execution. A documentation about the development of Jinja templates can be found [here](https://jinja.palletsprojects.com/en/3.1.x/templates/).
+
+The following variables can be used for the notification email templates:
+
+## Quarantine template
+
+The provided variables can also be obtained on GitHub from the script [dovecot/quarantine_notify.py](https://github.com/mailcow/mailcow-dockerized/blob/master/data/Dockerfiles/dovecot/quarantine_notify.py#L94).
+
+!!! info 
+    As an administrator, you can edit the template for the quarantine mails in the mailcow user interface in the global quarantine settings and restore the default template there as well. 
+    Code examples can be found in the default template. It can also be viewed on [GitHub](https://github.com/mailcow/mailcow-dockerized/blob/master/data/assets/templates/quarantine.tpl).
+
+| Name           	| Content                                                                                        	|
+|----------------	|------------------------------------------------------------------------------------------------	|
+| username       	| E-mail address of the mailbox user                                                             	|
+| counter        	| Number of messages in the quarantine, about which this e-mail informs                          	|
+| hostname       	| Name of the mailcow instance (See also the environment variable _MAILCOW_HOSTNAME_)            	|
+| quarantine_acl 	| Quarantine ACL setting of the mailbox user (Permission to process the mails in the quarantine) 	|
+| meta           	| Array/list of all messages in the quarantine about which this e-mail informs                   	|
+| meta.qhash     	| Hash value of the quarantine entry (e.g. for direct link to the message in the quarantine)     	|
+| meta.id        	| ID of the quarantine entry                                                                     	|
+| meta.subject   	| Title of the quarantine entry                                                                  	|
+| meta.score     	| Spam score of the quarantine entry                                                             	|
+| meta.sender    	| Sender address of the quarantine entry                                                         	|
+| meta.created   	| Creation date of the quarantine entry / receipt of the e-mail                                  	|
+| meta.action    	| Action of the spam filter (moved to spam folder or quarantine).                                	|
+
+
+## Quota template
+
+The provided variables can also be obtained on GitHub from the script [dovecot/quota_notify.py](https://github.com/mailcow/mailcow-dockerized/blob/master/data/Dockerfiles/dovecot/quota_notify.py#L45).
+
+!!! info 
+    The template for the quota mails can be edited as an administrator in the mailcow user interface in the quota settings and there also restore the default template. 
+    Code examples can be found in the default template. It can also be viewed on [GitHub](https://github.com/mailcow/mailcow-dockerized/blob/master/data/assets/templates/quota.tpl).
+
+| Name           	| Content                                                                                              	|
+|----------------	|------------------------------------------------------------------------------------------------------	|
+| username       	| E-mail address of the mailbox user                                                                   	|
+| percent        	| Percentage of the occupied space of the mailbox                                                      	|
+
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -110,6 +110,7 @@ nav:
       - 'Configuration': 'manual-guides/mailcow-UI/u_e-mailcow_ui-config.md'
       - 'CSS overrides': 'manual-guides/mailcow-UI/u_e-mailcow_ui-css.md'
       - 'Netfilter': 'manual-guides/mailcow-UI/u_e-mailcow_ui-netfilter.md'
+      - 'Notification templates': 'manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.md'
       - 'Pushover': 'manual-guides/mailcow-UI/u_e-mailcow_ui-pushover.md'
       - 'Spamfilter': 'manual-guides/mailcow-UI/u_e-mailcow_ui-spamfilter.md'
       - 'Sub-addressing': 'manual-guides/mailcow-UI/u_e-mailcow_ui-sub_addressing.md'
@@ -241,6 +242,7 @@ plugins:
             ### mailcow UI Subsection
           'Configuration' : 'Konfiguration'
           'CSS overrides' : 'CSS-Überschreibungen'
+          'Notification templates': 'Templates für Benachrichtigungen'
           'Sub-addressing' : 'Sub-Adressierung'
           'Temporary email aliases' : 'Temporäre E-Mail-Aliase'
           'Tags (for Domains and Mailboxes)' : 'Tags (für Domains und Mailboxen)'
@@ -339,6 +341,7 @@ plugins:
         'u_e-mailcow_ui-config.md': 'manual-guides/mailcow-UI/u_e-mailcow_ui-config.en.md'
         'u_e-mailcow_ui-css.md': 'manual-guides/mailcow-UI/u_e-mailcow_ui-css.en.md'
         'u_e-mailcow_ui-netfilter.md': 'manual-guides/mailcow-UI/u_e-mailcow_ui-netfilter.en.md'
+        'u_e-mailcow_ui-notification-templates.md': 'manual-guides/mailcow-UI/u_e-mailcow_ui-notification-templates.en.md'
         'u_e-mailcow_ui-pushover.md': 'manual-guides/mailcow-UI/u_e-mailcow_ui-pushover.en.md'
         'u_e-mailcow_ui-spamfilter.md': 'manual-guides/mailcow-UI/u_e-mailcow_ui-spamfilter.en.md'
         'u_e-mailcow_ui-sub_addressing.md': 'manual-guides/mailcow-UI/u_e-mailcow_ui-sub_addressing.en.md'