Mailer

Services

MailerService

The MailerService is responsible for sending transactional emails in the application, such as password resets, email verification, organization invitations, test emails, and invoices. It leverages an external task queue (e.g., Celery) for asynchronous processing using the send_email.delay method.

Key Methods:

• _prepare_content: Renders HTML and text content based on the provided context and templates.
• _update_context_with_common_data: Adds shared data (e.g., business name) to email contexts.
• send_reset_password_email: Sends an email with a password reset link.
• send_validate_email_link: Sends an email verification link.
• send_invitation: Sends an organization invitation.
• send_test_email: Sends a test email with optional attachments.
• send_invoice: Sends an invoice email with an attachment.

The class handles errors, such as missing templates, using ApiException, and logs key actions for diagnostics.

MailSender

The MailSender class is responsible for sending emails using different email providers, such as Mailgun and SMTP. It supports transactional emails, including password resets, invoices, and invitations.

Key Features:

1. Email Providers:
   • The providers property maps provider names (MailProviders) to specific implementations like MailGunProvider and SMTPProvider, adhering to the ESPInterface.
2. Constructor __init__:
   • Sets the default provider based on the DEFAULT_EMAIL_PROVIDER environment variable.
3. Method send_email:
   • Sends an email using specified parameters (recipient address, subject, HTML and text content, attachments).
   • Initializes the selected provider with the initialize method.
   • Throws a NoProviderMailerException if the provider is not configured properly.

This integration with the task queue ensures flexibility and scalability, allowing easy extension to new email providers.

ESPProviders

This package includes clients implementing email delivery. Each client must implement the ESPInterface, which defines the contract for email service providers (ESP).

Key Features

1. initialize:
   • An asynchronous method responsible for initializing the provider before use.
   • Verifies configurations or connections.
   • Returns a boolean (True or False).
2. send_email:
   • An asynchronous method for sending emails.
   • Parameters:
     • to: Recipient's email address.
     • subject: Email subject.
     • html: HTML content.
     • text: Text content.
     • attachments: List of attachments (optional).
   • Returns True if the email is sent successfully, otherwise False.

Purpose

• Provides flexibility for adding and using various email providers.
• Standardizes provider implementations, ensuring consistency and seamless integration with the rest of the application.

This is the foundation for implementing classes like MailGunProvider and SMTPProvider.

Commands

The sendtestemail command allows testing email provider integration and delivery. It supports optional attachments and requires a running Celery instance for processing.

Key Features

• Test Email:
  • Sends a test email to verify the configured email provider.
• Attachment Support:
  • Allows attaching a file with the -attachment_path argument.

Usage

python manage.py sendtestemail receiver@testemail.com --attachment_path path/to/attachment.png

• receiver@testemail.com: Recipient email address.
• --attachment_path: (Optional) Path to the attachment file.

Behavior

1. Configuration:

• Reads the email provider from the DEFAULT_EMAIL_PROVIDER environment variable.

2. Celery Dependency:

• Requires a running Celery worker for asynchronous email processing.

3. Execution:

• Uses the MailerService to send the test email.

Purpose

This command verifies email configurations, ensuring the provider is properly set up before deployment.

Tasks

Defines an asynchronous Celery task named send_email, enabling email delivery using the MailSender class.

Features

• Offloads email delivery to background tasks, improving system performance and responsiveness.
• Supports system scalability by distributing the load across Celery workers.

Templates

This directory contains email templates in text and HTML formats. Each template can be customized or replaced as needed. Available templates:

• invitation: For user invitations to an organization.
• password_reset: For password reset links.
• validate_email: For email verification links.
• invoice: For newly issued invoices.
• test: For testing email delivery using the sendtestemail command.

Examples of Use

1. Send a Password Reset Email:

   await mailer_service.send_reset_password_email(user_email, reset_link)

2. Send an Invoice:

await mailer_service.send_invoice(user_email, invoice_attachment)

3. Test Email Delivery: Run the command:

python manage.py sendtestemail receiver@testemail.com