Fixes #446 - Replace commands for unprocessable email handling

admin/console/other-useful-commands.rst

@@ -1,9 +1,9 @@
-Other useful commands
+Other Useful Commands
 *********************
 
 .. include:: /admin/console/missing-commands-ask-community.include.rst
 
-Fetch mails
+Fetch Mails
 -----------
 
 The below command will do a manual fetch of mail channels.
@@ -13,29 +13,46 @@ This will also show errors that might appear within that process.
 
    >> Channel.fetch
 
-Reprocess unprocessable mails
------------------------------
+Reprocess Failed Emails
+-----------------------
 
-When Zammad encounters a mail it cannot parse (e.g. due to a parser bug or a
-malformed message), it will store the mail in
-``var/spool/unprocessable_mail/<ID>.eml``,  give up on attempting to parse the
-mail, and will warn on the monitoring page that there are unprocessed mails.
+When Zammad fetches a mail it cannot parse (e.g. due to a parser bug or a
+malformed message), it will store the mail in the database and warn in
+the monitoring section about it.
 
-To force Zammad to reattempt to parse those mails, run the following command:
+In case of a malformed message (e.g. an invalid email address in one of the
+header fields), you may need to manually edit the mail before Zammad can process
+it. To do so, follow the steps below:
 
-.. code-block:: ruby
+Export all Failed Emails to a Local Folder
+   Execute ``rake zammad:email_parser:failed_email:export_all``. You can find
+   the location of the exported email in the output of your console.
+   Every time you perform an export of failed (unprocessable) emails, it
+   creates one folder with all failed emails at the time of execution in it.
 
-   >> Channel::EmailParser.process_unprocessable_mails
+Edit the Email
+   The email has been exported in the step above. Now you can have a look at it
+   and try to repair it. Make sure to leave the file name untouched, as the
+   import will otherwise fail.
 
-In case of a malformed message (e.g. an invalid email address in one of the
-header fields), you may need to manually edit the mail before Zammad can process
-it.
+Import Locally Modified Email Back to Database
+   After editing the email, run
+   ``rake zammad:email_parser:failed_email:import /path/to/your/email.eml``
+   to apply your changes from the file to the database. You can also pass
+   the entire folder as argument, so all .eml files in it will we imported.
+
+Reprocess Edited Emails
+   Run ``rake zammad:email_parser:failed_email:reprocess_all`` to reprocess the
+   parsing of the imported emails.
+
+   In case Zammad successfully reprocessed emails, you can delete the
+   folder/emails in the file system.
 
-If Zammad fails to process the message, it will remain in the
-``var/spool/unprocessable_mail`` folder; otherwise it will be removed after it
-has been parsed successfully.
+If you don't want to import/reprocess emails, you can delete them from the
+database after exporting them with the command
+``rake zammad:email_parser:failed_email:delete email.eml``.
 
-Add translation
+Add Translation
 ---------------
 
 .. warning::
@@ -63,7 +80,7 @@ for several languages.
 
 .. _Weblate: https://translations.zammad.org/
 
-Translating attributes
+Translating Attributes
 ~~~~~~~~~~~~~~~~~~~~~~
 
 By default Zammad will not translate custom attributes.
@@ -90,7 +107,7 @@ with the name of your attribute.
    If you're translating the display name of e.g. an Integer-attribute,
    this works as well!
 
-Fill a test system with test data
+Fill a Test System With Test Data
 ---------------------------------
 
 .. danger::