More details

admin_manual/configuration_server/email_configuration.rst

@@ -79,9 +79,59 @@ place, in your mail server configuration.
 Using email templates
 ---------------------
 
-With Nextcloud 12 we have introduced a new way of customizing email templates.
-You will find the documentation in our support portal:
-`support portal <https://portal.nextcloud.com/article/customized-email-templates-29.html>`_
+We removed the template editor in Nextcloud 12 because we changed how emails
+are generated. While the customization capabilities offered by the template editor
+were easy to use, they often resulted in broken emails. To fix this, we designed a
+much easier mechanism that automatically generates emails which follow the theme
+settings and look the same in all the different email clients out there.
+
+.. note:: If, for some reason, you need text-only emails, consider simply configuring
+   this on the client side or let the receiving (or even sending) mail server drop the
+   HTML part. Note that there is no security impact from **sending** HTML emails, just
+   from displaying them and thus any security risk can only be mitigated by disabling
+   showing HTML on the client (or removing the HTML part in the mail server).
+
+Modifying the look of emails beyond the theming app capabilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can now overwrite templates by writing a class that implements the template interface 
+(or extends it to not need to copy over everything). Easiest way is then put this class into 
+an app and load it (so you do not need to patch it in on every update).
+
+This is the interface of the class that needs to be implemented: https://github.com/nextcloud/server/blob/master/lib/public/Mail/IEMailTemplate.php
+
+That is the implementation that could be extended and used to see how it works: https://github.com/nextcloud/server/blob/master/lib/private/Mail/EMailTemplate.php
+
+An example from `a GitHub issue <https://portal.nextcloud.com/article/customized-email-templates-29.html>`_:
+
+1. Look at the source code of extended class `OC\Mail\EMailTemplate::class <https://github.com/nextcloud/server/blob/master/lib/private/Mail/EMailTemplate.php>`_
+
+2. Then override what you need in your own `OC\Mail\EMailTemplate::class` extension
+
+**Example:**
+
+Let's assume that we need to override the email header::
+
+   <?php
+
+   namespace \OCA\MyApp;
+
+   use OC\Mail\EMailTemplate;
+
+   class MyClass extends EMailTemplate
+   {
+      protected $header = <<<EOF 
+         <table align="center" class="wrapper">
+               // your theme email header modification
+         </table>
+      EOF;
+   }
+
+3. Then in ``config/config.php`` change ``mail_template_class`` to your class namespace::
+
+   'mail_template_class' => 'OCA\\MyApp\\MyClass',
+
+You will find a detailed step by step guide in our `support portal <https://portal.nextcloud.com/article/customized-email-templates-29.html>`_.
 
 Setting mail server parameters in config.php
 --------------------------------------------