{"id":4940,"library":"emails","title":"emails","description":"The 'emails' library is a modern Python package designed for building, templating, transforming, signing, and sending emails. It provides a high-level API to compose HTML and plain-text messages, attach files, embed inline images, render templates, apply HTML transformations, sign with DKIM, and send through SMTP without manually constructing MIME trees. Currently at version 1.1.1, the library is actively maintained with regular releases addressing new features and bug fixes.","status":"active","version":"1.1.1","language":"en","source_language":"en","source_url":"https://github.com/lavr/python-emails","tags":["email","smtp","html-email","templates","dkim","async","mime"],"install":[{"cmd":"pip install emails","lang":"bash","label":"Core installation"},{"cmd":"pip install \"emails[html]\"","lang":"bash","label":"With HTML transformation features (CSS inlining, image embedding)"},{"cmd":"pip install \"emails[jinja]\"","lang":"bash","label":"With Jinja2 template support"},{"cmd":"pip install \"emails[async]\"","lang":"bash","label":"With asynchronous SMTP sending support"}],"dependencies":[{"reason":"Optional, for template rendering via `emails[jinja]` extra.","package":"jinja2","optional":true},{"reason":"Optional, for HTML transformation via `emails[html]` extra.","package":"cssutils","optional":true},{"reason":"Optional, for HTML transformation via `emails[html]` extra.","package":"lxml","optional":true},{"reason":"Optional, for HTML transformation via `emails[html]` extra.","package":"chardet","optional":true},{"reason":"Optional, for HTML transformation via `emails[html]` extra.","package":"requests","optional":true},{"reason":"Optional, for HTML transformation via `emails[html]` extra.","package":"premailer","optional":true},{"reason":"Optional, for asynchronous SMTP sending via `emails[async]` extra.","package":"aiosmtplib","optional":true},{"reason":"Required for DKIM signing. Replaced a vendored package in v1.0.0.","package":"dkimpy","optional":true}],"imports":[{"note":"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()`.","symbol":"emails","correct":"import emails"}],"quickstart":{"code":"import emails\nimport os\n\n# Configure SMTP details using environment variables for security\nSMTP_HOST = os.environ.get('SMTP_HOST', 'smtp.example.com')\nSMTP_PORT = int(os.environ.get('SMTP_PORT', 587))\nSMTP_USER = os.environ.get('SMTP_USER', 'billing@example.com')\nSMTP_PASSWORD = os.environ.get('SMTP_PASSWORD', 'your-app-password')\n\nrecipient_email = os.environ.get('RECIPIENT_EMAIL', 'customer@example.com')\nsender_email = os.environ.get('SENDER_EMAIL', 'billing@example.com')\nsender_name = os.environ.get('SENDER_NAME', 'Billing Dept.')\n\nmessage = emails.html(\n    subject=\"Your Receipt from Example Store\",\n    html=\"<p>Hello!</p><p>Your payment was successfully received for Order #12345.</p><p>Thank you for your business!</p>\",\n    mail_from=(sender_name, sender_email)\n)\n\n# Example of attaching a file (replace with a real file path if needed)\n# with open(\"receipt.pdf\", \"rb\") as f:\n#     message.attach(filename=\"receipt.pdf\", data=f.read())\n\ntry:\n    response = message.send(\n        to=recipient_email,\n        smtp={\n            \"host\": SMTP_HOST,\n            \"port\": SMTP_PORT,\n            \"tls\": True, # Use TLS for secure connection\n            \"user\": SMTP_USER,\n            \"password\": SMTP_PASSWORD,\n        },\n    )\n\n    if response.status_code == 250:\n        print(\"Email sent successfully!\")\n    else:\n        print(f\"Failed to send email. Status code: {response.status_code}, Message: {response.message}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later. Consider using a virtual environment to manage Python versions for different projects.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install with `pip install \"emails[html]\"` to include HTML transformation features.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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).","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install with `pip install \"emails[jinja]\"` to enable Jinja2 templating.","message":"Jinja2 template support is an optional dependency. If you intend to use `JinjaTemplate` or other Jinja2-based features, you must install the `jinja` extra.","severity":"gotcha","affected_versions":">=1.0.2"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}