Sending Emails

The package provides two ways to send emails: through Django’s standard email backend or directly via the API.

Using the Email Backend

When you set EMAIL_BACKEND = "notifiedby.NotifiedByEmailBackend", all Django email functions will automatically use NotifiedBy:

from django.core.mail import send_mail, EmailMessage

# Simple text email
send_mail(
    'Subject',
    'Message body',
    'from@example.com',
    ['to@example.com']
)

# HTML email with attachments
email = EmailMessage(
    subject='HTML Email',
    body='<h1>Hello</h1><p>This is HTML content.</p>',
    from_email='from@example.com',
    to=['to@example.com'],
)
email.attach('document.pdf', pdf_content, 'application/pdf')
email.send()

The backend returns the email ID from NotifiedBy, which you can use to check delivery status.

Bypassing the Account Template

By default, emails are wrapped in the sender’s account template configured in the NotifiedBy dashboard. Set use_account_template to False to send the body as-is — useful when the body is already fully rendered HTML.

When using the email backend, set the attribute directly on the message before sending:

from django.core.mail import EmailMessage

email = EmailMessage(
    subject='Fully Rendered Email',
    body='<html><body><p>This is the complete email.</p></body></html>',
    from_email='from@example.com',
    to=['to@example.com'],
)
email.use_account_template = False
email.send()

Direct API Sending

For more control, use send_email_via_api() directly. The use_account_template parameter can also be passed here:

from django.core.mail import EmailMessage
from notifiedby import send_email_via_api

message = EmailMessage(
    subject='Test Email',
    body='Hello, this is a test email.',
    to=['user@example.com']
)

# Send with account template (default)
email_id = send_email_via_api(message)

# Send without account template
email_id = send_email_via_api(message, use_account_template=False)

if email_id:
    print(f"Email sent with ID: {email_id}")
else:
    print("Failed to send email")

Querying Sent Emails

The package provides functions to query emails that have been sent and check their delivery status.

from notifiedby import get_email_detail, list_sent_emails, get_email_delivery_status

# Get details of a specific email by ID
email = get_email_detail(sqid='JDT')
print(f"Subject: {email['subject']}")
print(f"Sent to: {email['recipient']}")
print(f"Sent on: {email['created_on']}")

# Get the most recent email sent to a specific address
recent_email = get_email_detail(email='user@example.com')
print(f"Most recent email: {recent_email['subject']}")

# List sent emails (paginated, most recent first)
emails = list_sent_emails(page=1)
print(f"Total emails sent: {emails['count']}")
for email in emails['results']:
    print(f"{email['subject']} - {email['recipient']} - {email['created_on']}")

# Filter emails by recipient
user_emails = list_sent_emails(recipient='user@example.com')
print(f"Emails sent to user@example.com: {len(user_emails['results'])}")

# Get delivery status of a specific email
status = get_email_delivery_status('JDT')
print(f"Delivery status: {status['status']}")
print(f"SES Message ID: {status['ses_id']}")

Delivery Status Values

The status field can contain the following values:

pending: Email is queued for delivery
delivered: Email was successfully delivered to the recipient
bounced: Email bounced (permanent delivery failure)
complained: Recipient marked the email as spam
failed: Delivery failed for other reasons

Example: Send Email and Check Delivery

from django.core.mail import EmailMessage
from notifiedby import send_email_via_api, get_email_delivery_status
import time

# Send an email
message = EmailMessage(
    subject='Test Email',
    body='Hello, this is a test email.',
    to=['user@example.com']
)
email_id = send_email_via_api(message)

if email_id:
    print(f"Email sent with ID: {email_id}")

    # Wait a moment for delivery processing
    time.sleep(2)

    # Check delivery status
    status = get_email_delivery_status(email_id)
    print(f"Current status: {status['status']}")

    if status['status'] == 'delivered':
        print("✅ Email delivered successfully!")
    elif status['status'] == 'bounced':
        print("❌ Email bounced - check recipient address")
    else:
        print(f"⏳ Email status: {status['status']}")
else:
    print("❌ Failed to send email")