Send email through SMTP

Lesson 6 / 22 · Commentail 1.3.2

Guests need both mail delivery and a queue worker. SMTP hands messages to your mail service. For an HTTP API, follow the next lesson instead of configuring SMTP.

Obtain transport settings

Find your provider's SMTP host, port, username and SMTP/app password. A webmail password may not work. Authorize the sender according to the provider's rules. For a custom domain, verify ownership and publish the supplied DNS records with the service hosting your DNS zone.

DKIM checks a signature, SPF identifies authorized sending sources and DMARC defines domain-checking policy. Use the provider's actual values. Merge authorized sources into an existing SPF policy rather than adding a second SPF record for the same name. Do not delete working inbound-mail MX records to configure comment notifications.

Configure Django

Set these values in a macOS/Linux terminal. In PowerShell use $env:NAME = 'value' as in lesson 5:

export EMAIL_HOST='YOUR_SMTP_HOST'
export EMAIL_HOST_USER='YOUR_SMTP_USERNAME'
export EMAIL_HOST_PASSWORD='YOUR_SMTP_PASSWORD'
export DEFAULT_FROM_EMAIL='Comments <comments@YOUR_VERIFIED_DOMAIN>'

Replace the previous console/API backend in the active settings file:

import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = os.environ["EMAIL_HOST"]
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_USE_SSL = False
EMAIL_HOST_USER = os.environ["EMAIL_HOST_USER"]
EMAIL_HOST_PASSWORD = os.environ["EMAIL_HOST_PASSWORD"]
DEFAULT_FROM_EMAIL = os.environ["DEFAULT_FROM_EMAIL"]
EMAIL_TIMEOUT = 20

This uses STARTTLS on port 587. If the provider requires implicit TLS on 465, use EMAIL_PORT = 465, EMAIL_USE_TLS = False, EMAIL_USE_SSL = True. Never enable both switches. Do not disable encryption to work around invalid credentials.

Restart the website and worker, then run python manage.py check. Check Send emails for the correct Site. Site hostname, port and HTTPS configuration must produce correct email links.

Test the complete path

In a private window submit as a guest to an address you control and that the provider currently permits. Check for a job under Comments → Email delivery, then run:

python manage.py process_commentail

Find the email, inspect its sender and link domain, and check spam if needed. Open the link and confirm with the button. Approve the comment and run the worker again for its editing link. Submit a direct reply as another author, approve it and check the reply notice and unsubscribe action.

If status is sent but no email arrives, the backend accepted it: inspect provider events and recipient restrictions. If queued, check the worker schedule and database. If failed, correct the cause and retry an eligible message in the admin; the original link deadline does not extend.

New submissions with email automatically subscribe to direct published replies when mail is enabled; there is no checkbox. Disabling Send emails cancels queued jobs. Reenabling does not replay them.

Related lessons

• 5. Environment variables without key confusion
• 8. Schedule email processing and cleanup
• 21. Troubleshoot a Commentail installation

Related documentation

• Email-and-worker