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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 5.731s · 248.3MB
glibcpy 3.10–3.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()
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.
fixVerify 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.
fixConfirm 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.
fixRun `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.
fixEnsure 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.