emails

Warnings

• breaking Starting with version 1.0.0, 'emails' requires Python 3.10 or newer. Older Python 3.x versions (e.g., 3.9) are no longer supported.
  Fix: Upgrade your Python environment to 3.10 or later. Consider using a virtual environment to manage Python versions for different projects.
• breaking HTML transformation dependencies (like `cssutils`, `lxml`, `chardet`, `requests`, `premailer`) are no longer installed by default since version 1.0.0. If you use features like CSS inlining or image embedding, you must install the `html` extra.
  Fix: Install with `pip install "emails[html]"` to include HTML transformation features.
• breaking The vendored `emails.packages.dkim` module was replaced with the upstream `dkimpy` package in version 1.0.0. Direct imports from `emails.packages.dkim` will no longer work.
  Fix: If you were using DKIM signing, you should now `import dkim` directly and ensure `dkimpy` is installed (implicitly handled by `emails` core requirements if using DKIM features).
• gotcha Jinja2 template support is an optional dependency. If you intend to use `JinjaTemplate` or other Jinja2-based features, you must install the `jinja` extra.
  Fix: Install with `pip install "emails[jinja]"` to enable Jinja2 templating.
• gotcha The `cc` and `bcc` parameters in the `Message` constructor are for setting email *headers* (e.g., to make recipients visible), not for adding recipients to the actual delivery list. All recipients, including CC/BCC recipients who should receive the email, must be specified in the `to` parameter of the `send()` method.
  Fix: Ensure all intended recipients are included in the `to` parameter when calling `message.send()`. If you want CC/BCC headers to appear, set them in the `Message` constructor as `cc='cc@example.com'` or `bcc='bcc@example.com'`.

Install

• pip install emails Core installation
• pip install "emails[html]" With HTML transformation features (CSS inlining, image embedding)
• pip install "emails[jinja]" With Jinja2 template support
• pip install "emails[async]" With asynchronous SMTP sending support

Imports

• emails

  import emails

  The primary entry point for creating and sending messages is the `emails` module itself, often used via factory functions like `emails.html()` or `emails.text()`.

Quickstart

This quickstart example demonstrates how to create and send an HTML email using the `emails` library. It initializes an HTML email message with a subject, HTML body, and sender information. It then attempts to send the email via an SMTP server, retrieving SMTP credentials from environment variables for security. The example includes basic error handling for the `send` operation. For full functionality like HTML transformations or templating, remember to install the respective optional dependencies.

import emails
import os

# Configure SMTP details using environment variables for security
SMTP_HOST = os.environ.get('SMTP_HOST', 'smtp.example.com')
SMTP_PORT = int(os.environ.get('SMTP_PORT', 587))
SMTP_USER = os.environ.get('SMTP_USER', 'billing@example.com')
SMTP_PASSWORD = os.environ.get('SMTP_PASSWORD', 'your-app-password')

recipient_email = os.environ.get('RECIPIENT_EMAIL', 'customer@example.com')
sender_email = os.environ.get('SENDER_EMAIL', 'billing@example.com')
sender_name = os.environ.get('SENDER_NAME', 'Billing Dept.')

message = emails.html(
    subject="Your Receipt from Example Store",
    html="<p>Hello!</p><p>Your payment was successfully received for Order #12345.</p><p>Thank you for your business!</p>",
    mail_from=(sender_name, sender_email)
)

# Example of attaching a file (replace with a real file path if needed)
# with open("receipt.pdf", "rb") as f:
#     message.attach(filename="receipt.pdf", data=f.read())

try:
    response = message.send(
        to=recipient_email,
        smtp={
            "host": SMTP_HOST,
            "port": SMTP_PORT,
            "tls": True, # Use TLS for secure connection
            "user": SMTP_USER,
            "password": SMTP_PASSWORD,
        },
    )

    if response.status_code == 250:
        print("Email sent successfully!")
    else:
        print(f"Failed to send email. Status code: {response.status_code}, Message: {response.message}")
except Exception as e:
    print(f"An error occurred: {e}")