Registry / workflow / prefect-email

prefect-email

JSON →
library0.4.2pypypi✓ verified 87d ago

Prefect Email provides integrations for sending emails within Prefect workflows, enabling notifications and reporting capabilities. It's an official Prefect integration, currently at version 0.4.2, and its release cadence often aligns with new Prefect core features or significant updates to the Prefect platform.

pip install prefect-email
INSTALL
IMPORT
SIG · PREFECT-EMAIL
P
prefect-email
workflowpythonv0.4.2
Install
20.6s avg
Import
5592ms
Disk
243MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 5.731s · 248.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 20.6s · import 5.452s · 249MB
243MB installed
● package 243MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

EmailServerCredentials
from prefect_email.credentials import EmailServerCredentials
from prefect_email import EmailServerCredentials
Credentials are found within the 'credentials' submodule, not directly under the top-level package.
email_send_message
from prefect_email.tasks import email_send_message
from prefect_email import send_email
The primary task for sending emails is `email_send_message` located in the 'tasks' submodule, not a generic `send_email`.
email_send_html_message
from prefect_email.tasks import email_send_html_message
This task specifically sends HTML-formatted emails.

This quickstart demonstrates how to define a Prefect flow that sends an email using `prefect-email`. It instantiates `EmailServerCredentials` directly from environment variables (recommended to use Prefect Blocks in production) and then uses the `email_send_message` task to send a simple text email. Replace placeholder values or set environment variables for `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `TO_EMAIL`, and `FROM_EMAIL` to run.

import os from prefect import flow from prefect_email.credentials import EmailServerCredentials from prefect_email.tasks import email_send_message @flow(log_prints=True) def send_notification_email_flow(): # For production, it is highly recommended to store credentials # in a Prefect EmailServerCredentials Block for security and reusability. # Example: EmailServerCredentials(host=..., port=..., username=..., password=...).save('my-email-creds') # Then load: credentials = EmailServerCredentials.load('my-email-creds') # For this quickstart, we'll instantiate directly from environment variables. # Ensure these are set: SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, TO_EMAIL, FROM_EMAIL credentials = EmailServerCredentials( host=os.environ.get("SMTP_HOST", "smtp.mailtrap.io"), port=int(os.environ.get("SMTP_PORT", 2525)), username=os.environ.get("SMTP_USERNAME", "YOUR_USERNAME"), password=os.environ.get("SMTP_PASSWORD", "YOUR_PASSWORD"), use_tls=True # Often required for secure SMTP ) to_emails = os.environ.get("TO_EMAIL", "recipient@example.com").split(',') from_email = os.environ.get("FROM_EMAIL", "sender@example.com") subject = "Prefect Email Test Notification" body = "This is a test email sent from a Prefect flow using prefect-email." print(f"Attempting to send email from {from_email} to {to_emails}...") try: email_send_message( smtp_credentials=credentials, subject=subject, msg=body, email_from=from_email, email_to=to_emails ) print("Email sent successfully!") except Exception as e: print(f"Failed to send email: {e}") if __name__ == "__main__": # To run locally, set environment variables like: # export SMTP_HOST="smtp.mailtrap.io" # export SMTP_PORT="2525" # export SMTP_USERNAME="your_mailtrap_username" # export SMTP_PASSWORD="your_mailtrap_password" # export TO_EMAIL="your_email@example.com" # export FROM_EMAIL="prefect@example.com" # Then execute: python your_script_name.py send_notification_email_flow()
Debug
Known issues
gotchaAlways store SMTP credentials securely using Prefect Blocks (e.g., EmailServerCredentials Block) rather than hardcoding them or relying solely on environment variables in production deployments. Blocks provide encrypted storage and better management.
fix
Create an `EmailServerCredentials` block in the Prefect UI or via Python code (`EmailServerCredentials(...).save('my-creds')`) and then load it in your flow: `credentials = EmailServerCredentials.load('my-creds')`.
affects: All versions
gotchaSMTP server connection issues (e.g., 'Connection refused', 'timeout') are often caused by incorrect host/port, firewall restrictions, or incorrect TLS/SSL settings.
fix
Double-check `host`, `port`, and `use_tls` parameters for `EmailServerCredentials`. Ensure the machine running your Prefect agent/flow has network access to the SMTP server on the specified port.
affects: All versions
gotchaFor `EmailServerCredentials.load('block-name')` to work, a Prefect API server must be running and accessible by your flow/agent. If running locally without a server, direct instantiation or using environment variables is necessary.
fix
Ensure `prefect dev start` (for local development) or a Prefect server instance is running and your Prefect client is configured to connect to it (e.g., `PREFECT_API_URL` environment variable).
affects: All versions
gotchaWhen sending HTML emails, use the `email_send_html_message` task and set the `html` parameter to `True` for the `msg` argument in `email_send_message`.
fix
For plain text, use `email_send_message` and pass `msg='Your plain text'`. For HTML, use `email_send_html_message` or pass `html=True` to `email_send_message` and ensure your `msg` argument contains valid HTML.
affects: All versions
Errors
Common errors & fixes
smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted.')
The provided SMTP username or password is incorrect, or the user lacks permission to send email through the server.
fix
Verify your `username` and `password` in `EmailServerCredentials`. Check if two-factor authentication is enabled for the SMTP account and if an app-specific password is required.
ConnectionRefusedError: [Errno 111] Connection refused
The client could not establish a connection to the SMTP server. This usually indicates an incorrect host/port, a firewall blocking the connection, or the SMTP server not running/listening on the specified port.
fix
Confirm the `host` and `port` for `EmailServerCredentials` are correct. Check local and remote firewalls. Ensure the SMTP server is running and configured to accept connections on that port.
ModuleNotFoundError: No module named 'prefect_email'
The `prefect-email` library has not been installed in the current Python environment.
fix
Run `pip install prefect-email` to install the library.
AttributeError: 'NoneType' object has no attribute 'host' (when loading a block)
This typically occurs when `EmailServerCredentials.load('block-name')` is called, but the specified block does not exist in the Prefect API server, or the Prefect API server is not running/reachable.
fix
Ensure the Prefect API server is running and accessible. Verify that an `EmailServerCredentials` block with the exact name 'block-name' has been created and saved to the Prefect server.
Upgrade
Version history
0.4.2latest on PyPI · released Apr 9, 2025
Audit
Dependencies
prefectrequiredprefect-email is an integration for the Prefect workflow orchestration framework and requires Prefect core to function.
Agent activity
33 hits · last 30 days
node
30
OpenAI (training)
1
Resources
prefect-email — pip install prefect-email · libregistry