Email Utilities Reference¶

This document describes the email utility functions available in aclarknet/email_utils.py.

Module: aclarknet.email_utils¶

This module provides improved email sending functions with proper headers for better deliverability and authentication.

Functions¶

send_email_with_headers¶

Send email with proper headers for better deliverability and authentication.

Signature:

def send_email_with_headers(
    subject,
    plain_message,
    recipient_list,
    html_message=None,
    from_email=None,
    reply_to=None,
    fail_silently=False,
)

Parameters:

Parameter	Type	Description
`subject`	str	Email subject line
`plain_message`	str	Plain text message body
`recipient_list`	list	List of recipient email addresses
`html_message`	str (optional)	HTML version of the message
`from_email`	str (optional)	Sender email (defaults to `DEFAULT_FROM_EMAIL`)
`reply_to`	str (optional)	Reply-to address (defaults to `from_email`)
`fail_silently`	bool (optional)	Whether to suppress exceptions (default: False)

Returns:

Type:: int
Description:: Number of successfully sent emails

Headers Added:

This function automatically adds the following headers to improve deliverability:

Header	Purpose
`Reply-To`	Specifies where replies should go
`X-Mailer: aclark.net`	Identifies the sending application
`X-Auto-Response-Suppress: OOF, AutoReply`	Prevents auto-reply loops
`Precedence: bulk`	Indicates automated mail

Example Usage:

from aclarknet.email_utils import send_email_with_headers

send_email_with_headers(
    subject="Welcome to aclark.net",
    plain_message="Thank you for signing up!",
    recipient_list=["user@example.com"],
    html_message="<p>Thank you for signing up!</p>",
    from_email="aclark@aclark.net",
    reply_to="support@aclark.net",
)

send_notification_email¶

Send a notification email to the site admin.

This is a convenience wrapper for internal notifications.

Signature:

def send_notification_email(
    subject,
    plain_message,
    html_message=None,
    from_email=None,
    recipient_email=None,
)

Parameters:

Parameter	Type	Description
`subject`	str	Email subject line
`plain_message`	str	Plain text message body
`html_message`	str (optional)	HTML version of the message
`from_email`	str (optional)	Sender email (defaults to `DEFAULT_FROM_EMAIL`)
`recipient_email`	str (optional)	Recipient email (defaults to `DEFAULT_FROM_EMAIL`)

Returns:

Type:: int
Description:: Number of successfully sent emails

Example Usage:

from aclarknet.email_utils import send_notification_email

send_notification_email(
    subject="New contact form submission",
    plain_message="A user submitted the contact form.",
    html_message="<p>A user submitted the contact form.</p>",
)

Usage in Application¶

db/signals.py¶

The send_email_on_time_creation signal uses send_notification_email to send notifications when Time objects are created:

from aclarknet.email_utils import send_notification_email

@receiver(post_save, sender=Time)
def send_email_on_time_creation(sender, instance, created, **kwargs):
    if created:
        # ... prepare email content ...
        send_notification_email(
            subject=subject,
            plain_message=plain_message,
            html_message=html_content,
            from_email=from_email,
        )

cms/views.py¶

The ContactView uses send_email_with_headers to send contact form notifications with proper Reply-To headers:

from aclarknet.email_utils import send_email_with_headers

send_email_with_headers(
    subject=email_subject,
    plain_message=email_body,
    recipient_list=[contact_email],
    from_email=settings.DEFAULT_FROM_EMAIL,
    reply_to=email,  # Set to contact form submitter's email
    fail_silently=False,
)

Benefits¶

Using these utility functions provides several benefits:

Consistent Headers: All emails include proper headers for better deliverability
Authentication Support: Headers help with SPF, DKIM, and DMARC authentication
Spam Prevention: Proper headers reduce the chance of emails being marked as spam
Reply Management: Reply-To headers ensure replies go to the correct address
Auto-Reply Prevention: X-Auto-Response-Suppress prevents auto-reply loops
Code Reuse: Centralized email sending logic reduces code duplication