Commentail 1.2.0: Django email backends and the project task queue

I released Commentail 1.2.0. This version makes it easier to connect the library to an existing Django project: mail can use its email backend, and background processing can run through its task queue. I also updated the comment form and malformed input handling. The project page gives an overview of the library; this article covers the release changes.

Mail through EMAIL_BACKEND

Commentail now uses Django’s configured EMAIL_BACKEND for guest email verification and queued mail delivery. If the project already sends mail through a provider API, it can use the corresponding Django backend. That transport no longer requires SMTP settings it does not use.

The backend is installed and configured in the host project. EMAIL_BACKEND takes its Python class path; configure the API key, sender and timeout according to the chosen backend’s documentation. Commentail does not add a separate provider SDK. Credentials stay in the project environment or secret store.

For a local guest-flow check, mail can be printed to the console:

EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
DEFAULT_FROM_EMAIL = "comments@example.invalid"

This backend lets you follow the flow without an external mail service, but messages appear in the background process output, not an inbox. Keep their action links private: they grant access to comment actions.

Guest form availability is checked through configuration. That check does not contact the provider or validate its keys. For a mail job to be marked sent, the backend must report one accepted message. If it merely passes mail to another queue, monitor subsequent delivery through that queue or provider.

For a third-party backend, set a finite network timeout shorter than MAIL_LEASE_SECONDS, which defaults to 300 seconds. SMTP timeout protection remains in place; SMTP-specific timeout arguments are not passed to arbitrary backends. See the email and background processing guide.

Background processing in the project task queue

The public commentail.background.process_pending() entry point can now be called from a periodic task. It processes the mail outbox and removes expired unconfirmed comments, as well as cleaning expired CAPTCHA proofs, guest grants, form tickets and old rate events. If the project already uses Celery or another task queue, a separate Commentail command schedule is unnecessary.

For example, an installed host app using Celery can define this task. Replace myapp with the actual app name:

from celery import shared_task
from commentail.background import process_pending


@shared_task(name="myapp.process_commentail")
def process_commentail_task():
    return process_pending(mail_limit=100)

With Celery’s usual CELERY settings namespace, add an entry to the existing CELERY_BEAT_SCHEDULE, retaining the project’s other tasks:

CELERY_BEAT_SCHEDULE = {
    # Keep the project's other periodic tasks here.
    "commentail-every-minute": {
        "task": "myapp.process_commentail",
        "schedule": 60.0,
    },
}

Celery remains optional: Commentail does not install it, register tasks or configure a broker. The entry point is synchronous, so another queue can use a similar wrapper. Run it after Django initialization, with the site database and settings, outside transaction.atomic() and with autocommit enabled. Calling it inside a transaction raises an error before cleanup or sending.

mail_limit defaults to 100. It limits mail claims per pass, including deferred and cancelled jobs, not the amount of cleanup. The result is a dictionary with sent and removed: messages accepted by the backend and expired unconfirmed comments erased.

Commentail’s database outbox still owns mail state: claims, access checks, retries and original protected-link deadlines remain in place. A queue delay does not extend a link. An uncertain send can still lead to duplicate mail; a task queue does not guarantee exactly-once delivery.

Choose one schedule running once per minute: the host task or python manage.py process_commentail. An existing SMTP setup with the minute-by-minute command needs no configuration change for this release.

Comment form changes

Cancel reply moves to the bottom of the form, beside submission. It is a compact text action normally, with a button surface on hover or keyboard focus. Inline dismissal, ordinary navigation without JavaScript and focus restoration to Reply are preserved.

The guest form is more compact: spacing is reduced, the arithmetic CAPTCHA input is shorter, and refresh sits beside it. The hint explains that email confirmation happens after submission. The submit button uses the host site’s text colors without a fixed light or dark palette.

Project template overrides retain precedence. To adopt the new layout, compare your commentail/form.html and commentail/captcha.html with the installed versions. Updating the package does not rewrite host templates.

Input validation and protected links in logs

Oversized numeric navigation and filter IDs are validated before conversion. Null bytes in comment text and guest names are rejected, as are guest email addresses longer than the stored field. Malformed input receives a validation error instead of a server or database error. Ordinary HTML draft recovery drops unsupported null bytes while preserving the remaining text.

Django log redaction now also hides protected-link secrets when the token parameter name is percent-encoded. Proxy and web-server logs and external error reporting need their own redaction configuration.

This release also verifies Wagtail 8.0.1 in the supported Wagtail 8 combinations while retaining existing compatibility bounds. Test environment dependencies were updated to address known vulnerabilities. Those pins belong to the library’s test environment and do not replace dependency management for the host site.

Upgrading from 1.1.0

Back up the database, settings, templates, media, SECRET_KEY and exact dependency versions. Rehearse the upgrade on a restored test database with local mail:

python -m pip install --upgrade commentail==1.2.0
python manage.py migrate
python manage.py check
python manage.py collectstatic --noinput

No new Commentail migrations are added over 1.1.0; upgraded frameworks may have their own. Existing comments, settings, subscriptions, issued links and queued jobs are retained. Link deadlines are not extended.

After collecting static assets, refresh cached resources and restart the application and background processes through the project’s normal procedure. Check guest submission and email confirmation, moderation, replies, eligible edits and unsubscribe. Also test keyboard navigation, forms without JavaScript and the site’s actual themes. When adopting the host queue, verify the task through its real worker and remove the previous separate command schedule.

See the release notes for the complete upgrade procedure and the changelog for the change list.