doc of mail setup is confusing

[woodz-]

Here is what the doc states:

...

Features

• ...
• Email task notification
• ...
• Integrated mail tracking (unify a task list with an email box)

...

For email notifications to work, make sure your site/project is set up to send email.

...

Settings

...
# The following two settings are relevant only if you want todo to track a support mailbox -
# see Mail Tracking below.
TODO_MAIL_BACKENDS
TODO_MAIL_TRACKERS

...

Mail Tracking

What if you could turn django-todo into a shared mailbox? Django-todo includes an optional feature that allows emails sent to a dedicated mailbox to be pushed into todo as new tasks, and responses to be added as comments on those tasks. This allows support teams to work with a fully unified email + bug tracking system to avoid confusion over who's seen or responded to what.

To enable mail tracking, you need to:

• Define an email backend for outgoing emails
• Define an email backend for incoming emails
• Start a worker, which will wait for new emails

In settings:

from todo.mail.producers import imap_producer
from todo.mail.consumers import tracker_consumer
from todo.mail.delivery import smtp_backend, console_backend

# email notifications configuration
# each task list can get its own delivery method
TODO_MAIL_BACKENDS = {
    # mail-queue is the name of the task list, not the worker name
    "mail-queue": smtp_backend(
        host="smtp.example.com",
        port=465,
        use_ssl=True,
        username="test@example.com",
        password="foobar",
        # used as the From field when sending notifications.
        # a username might be prepended later on
        from_address="test@example.com",
        # additionnal headers
        headers={}
    ),
}

# incoming mail worker configuration
TODO_MAIL_TRACKERS = {
    # configuration for worker "test_tracker"
    "test_tracker": {
        "producer": imap_producer(
            host="imap.example.com",
            username="text@example.com",
            password="foobar",
            # process_all=False, # by default, only unseen emails are processed
            # preserve=False, # delete emails if False
            # nap_duration=1, # duration of the pause between polling rounds
            # input_folder="INBOX", # where to read emails from
        ),
        "consumer": tracker_consumer(
            group="Mail Queuers",
            task_list_slug="mail-queue",
            priority=1,
            task_title_format="[TEST_MAIL] {subject}",
        )
    }
}

Here is, what I sorted out:

1. Setting up send email according to django doc is insufficient
2. The statement in settings # The following two settings are relevant only if you want todo to track a support mailbox - # see Mail Tracking below. isn't true.
3. At least TODO_MAIL_BACKENDSis required to set up with a valid from_address to have mail notifications to work. Other values are taken from the global settings (set up to send email)
4. The statement # mail-queue is the name of the task list, not the worker name is inaccurate. The name of a task list could contain special characters, which can make trouble in program code. The slug is working too here.
5. Defining a mail backend for each new task list can be quite cumbersome. Isn't there a global way for multiple or all task lists?
6. The code for mailing functionality makes intense use of the TODO_MAIL_BACKENDS setting, even on task and comment notifications
7. It's unclear, how global mail settings and backend settings work together or override each other
8. A revision of the doc would clarify things here. I could do an approach, but have no deep technical understanding about the conceptual idea of the architecture related to the current implementation

[woodz-]

Closing, some parts are fixed, some need refinement, for some the initial position wasn't true or preparation was insufficient.