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.

Direct API Sending

For more control, use send_email_via_api() directly:

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']
)
email_id = send_email_via_api(message)

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")