feat: more mail sending backends and plugability (#9608)

* [FR] Improve Email handeling
Fixes #7950

* extend implementation of email thread and message models

* add missing args

* add unit test

* increase test coverage

* make key not necessary

* do not consider in coverage

* add email apis

* Add email admin

* fix email configuration check

* improve rendering

* squash migrations

* add config value overview

* log if mails were send

* add additional headers

* fix api unit test

* fix url resolving

* add InvenTree specific task to issue mails
required to extend sending options (prio, reply to)

* use internal sending task to keep telemetry cleaner

* add prio handling

* add plugin handling

* add setting

* factor plugin method out

* add typing

* move function

* bump version

* fix import path

* add a test for the test endpoint

* fix checking logic

* Add anymail sending / tracking handling

* add more ordering fields to api

* remove unneeded assingment

* add basic docs

* handle incoming emails with anymail

* Add inbox handling
Closes https://github.com/inventree/InvenTree/issues/7951

* add list of supported ESPs

* add better error transparency when sending fails

* add missing migration

* combine migrations back down

* fix todos

* fix qc export

* fix missing model props

* add tests

* ensure things are passed as a list

* fix list formatting

* fix deps

* move tests

* add testing with anymail

* allow handling of priority and headers

* add test for events

* add test for inbound messages

* rename variable

* increase coverage

* fix format

* add setting doc

* fix link

* rename fnc

* disable pro test

* make messages clearer

* fix doc syntax

* fix assign

* fix test

* revert test disablement

* add enum

* disable check for now

* try changing test around

* add incoming mail processing

* fix import

* add docs

* Fix mail.md

* bump deps

* fix api version

docs/docs/api/index.md

@@ -99,7 +99,7 @@ headers = {
 response = request.get('http://localhost:8080/api/part/', data=data, headers=headers)
 ```
 
-### oAuth2 / OIDC
+### oAuth2 and OIDC
 
 !!! warning "Experimental"
     This is an experimental feature that needs to be specifically enabled. See [Experimental features](../settings/experimental.md) for more information.

docs/docs/plugins/mixins/api.md

@@ -1,5 +1,5 @@
 ---
-title: Schedule Mixin
+title: Api Mixin
 ---
 
 ## APICallMixin

docs/docs/plugins/mixins/mail.md

@@ -0,0 +1,19 @@
+---
+title: Mail Mixin
+---
+
+## MailMixin
+
+The MailMixin class provides basic functionality for processing in- and outgoing mails.
+
+### Sample Plugin
+
+The following example demonstrates how to use the `MailMixin` class to process incoming and outgoing emails:
+
+::: plugin.samples.mail.mail_sample.MailPluginSample
+    options:
+        show_bases: False
+        show_root_heading: False
+        show_root_toc_entry: False
+        show_source: True
+        members: []

docs/docs/settings/email.md

@@ -8,5 +8,34 @@ InvenTree can be configured to send emails to users, for various purposes.
 
 To enable this, email configuration settings must be supplied to the InvenTree [configuration options](../start/config.md#email-settings).
 
-!!! info "Password Reset"
-    The *Password Reset* functionality requires the email backend to be correctly configured.
+!!! info "Functionality might be degraded"
+    Multiple functions of InvenTree require functioning email delivery, including *Password Reset*, *Notififications*, *Update Infos*
+
+### Outgoing
+
+Mail can be delivered through various ESPs and SMTP. You can only configure one delivery method at a time.
+
+### Incoming
+
+Mail can be received though various ESPs, POP3 and IMAP.
+
+When using POP3/IMAP InvenTree removes email that were processed. This is to prevent duplicate processing of the same email. You can specify a archive folder, that mails should be moved to after processing. This is useful for retaining manual access.
+
+### Supported ESPs
+
+InvenTree uses django-anymail to support various ESPs. A full list of supported ESPs can be found in [their docs](https://anymail.dev/en/stable/esps/).
+
+Most popular providers are supported:
+
+- Amazon SES
+- Brevo (EU)
+- Postal (Self hosted)
+- Mailgun
+- Postmark
+- SendGrid
+
+### Logging / Admin Insights
+
+Superusers can view the email log in the [Admin Center](./admin.md#admin-center). This is useful for debugging and tracking email delivery / receipt.
+
+{{ image("admin/email_settings.png", "Email Control Pane") }}

docs/docs/settings/error_codes.md

@@ -54,16 +54,19 @@ During startup of the backend InvenTree tries to detect branch, commit hash and
 This information is not needed for operation but very helpful for debugging and support. These issues might be caused by running a deployment version that delivers without git information, not having git installed or not having dulwich installed.
 You can ignore this warning if you are not interested in the git information.
 
+
 #### INVE-W2
 **Dulwich module not found - Backend**
 
 See [INVE-W1](#inve-w1)
 
+
 #### INVE-W3
 **Could not detect git information - Backend**
 
 See [INVE-W1](#inve-w1)
 
+
 #### INVE-W4
 **Server is running in debug mode - Backend**
 
@@ -71,6 +74,7 @@ InvenTree is running in debug mode. This is **not** recommended for production u
 
 It is recommended to run InvenTree in production mode for better security and performance. See [Debug Mode Information](../start/index.md#debug-mode).
 
+
 #### INVE-W5
 **Background worker process not running - Backend**
 
@@ -78,6 +82,7 @@ The background worker seems to not be running. This is detected by a heartbeat t
 Check if the process for background workers is running and reaching the database. Steps vary between deployment methods.
 See [Background Worker Information](../start/processes.md#background-worker).
 
+
 #### INVE-W6
 **Server restart required - Backend**
 
@@ -99,6 +104,7 @@ There are database migrations waiting to be applied. This might lead to integrit
 Some deployment methods support [auto applying of updates](../start/config.md#auto-update). See also [Perform Database Migrations](../start/install.md#perform-database-migrations).
 Steps very between deployment methods.
 
+
 #### INVE-W9
 **Wrong Invoke Environment - Backend**
 
@@ -106,6 +112,13 @@ The command that was used to run invoke is not the one that is recommended. This
 The warning text will show the recommended command for intended use.
 
 
+#### INVE-W10
+**Exception during mail delivery - Backend**
+
+Collective exception for errors that occur during mail delivery. This might be caused by a misconfiguration of the email provider or a network issue.
+These issues are raised directly from the mail backend so it is unlikely that the error is caused by django or InvenTree itself.
+Check the logs for more information.
+
 ### INVE-I (InvenTree Information)
 Information — These are not errors but information messages. They might point out potential issues or just provide information.
 

docs/docs/settings/experimental.md

@@ -14,4 +14,4 @@ Superusers can configure run-time conditions [as per django-flags](https://cfpb.
 
 | Feature | Key | Description |
 | --- | --- | --- |
-| oAuth provider / api | OIDC | Use oAuth and OIDC to authenticate users with the API - [read more](../api/index.md#oauth2--oidc) |
+| oAuth provider / api | OIDC | Use oAuth and OIDC to authenticate users with the API - [read more](../api/index.md#oauth2-and-oidc) |

docs/docs/settings/global.md

@@ -239,6 +239,7 @@ Refer to the [return order settings](../sales/return_order.md#return-order-setti
 {{ globalsetting("ENABLE_PLUGINS_SCHEDULE") }}
 {{ globalsetting("ENABLE_PLUGINS_EVENTS") }}
 {{ globalsetting("ENABLE_PLUGINS_INTERFACE") }}
+{{ globalsetting("ENABLE_PLUGINS_MAILS") }}
 
 ### Project Codes