{"id":8441,"library":"prefect-email","title":"Prefect Email","description":"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.","status":"active","version":"0.4.2","language":"en","source_language":"en","source_url":"https://github.com/PrefectHQ/prefect/tree/main/src/integrations/prefect-email","tags":["prefect","email","automation","notifications","data pipelines","integrations"],"install":[{"cmd":"pip install prefect-email","lang":"bash","label":"Install prefect-email"}],"dependencies":[{"reason":"prefect-email is an integration for the Prefect workflow orchestration framework and requires Prefect core to function.","package":"prefect"}],"imports":[{"note":"Credentials are found within the 'credentials' submodule, not directly under the top-level package.","wrong":"from prefect_email import EmailServerCredentials","symbol":"EmailServerCredentials","correct":"from prefect_email.credentials import EmailServerCredentials"},{"note":"The primary task for sending emails is `email_send_message` located in the 'tasks' submodule, not a generic `send_email`.","wrong":"from prefect_email import send_email","symbol":"email_send_message","correct":"from prefect_email.tasks import email_send_message"},{"note":"This task specifically sends HTML-formatted emails.","symbol":"email_send_html_message","correct":"from prefect_email.tasks import email_send_html_message"}],"quickstart":{"code":"import os\nfrom prefect import flow\nfrom prefect_email.credentials import EmailServerCredentials\nfrom prefect_email.tasks import email_send_message\n\n@flow(log_prints=True)\ndef send_notification_email_flow():\n    # For production, it is highly recommended to store credentials\n    # in a Prefect EmailServerCredentials Block for security and reusability.\n    # Example: EmailServerCredentials(host=..., port=..., username=..., password=...).save('my-email-creds')\n    # Then load: credentials = EmailServerCredentials.load('my-email-creds')\n\n    # For this quickstart, we'll instantiate directly from environment variables.\n    # Ensure these are set: SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, TO_EMAIL, FROM_EMAIL\n    credentials = EmailServerCredentials(\n        host=os.environ.get(\"SMTP_HOST\", \"smtp.mailtrap.io\"),\n        port=int(os.environ.get(\"SMTP_PORT\", 2525)),\n        username=os.environ.get(\"SMTP_USERNAME\", \"YOUR_USERNAME\"),\n        password=os.environ.get(\"SMTP_PASSWORD\", \"YOUR_PASSWORD\"),\n        use_tls=True # Often required for secure SMTP\n    )\n\n    to_emails = os.environ.get(\"TO_EMAIL\", \"recipient@example.com\").split(',')\n    from_email = os.environ.get(\"FROM_EMAIL\", \"sender@example.com\")\n    subject = \"Prefect Email Test Notification\"\n    body = \"This is a test email sent from a Prefect flow using prefect-email.\"\n\n    print(f\"Attempting to send email from {from_email} to {to_emails}...\")\n\n    try:\n        email_send_message(\n            smtp_credentials=credentials,\n            subject=subject,\n            msg=body,\n            email_from=from_email,\n            email_to=to_emails\n        )\n        print(\"Email sent successfully!\")\n    except Exception as e:\n        print(f\"Failed to send email: {e}\")\n\nif __name__ == \"__main__\":\n    # To run locally, set environment variables like:\n    # export SMTP_HOST=\"smtp.mailtrap.io\"\n    # export SMTP_PORT=\"2525\"\n    # export SMTP_USERNAME=\"your_mailtrap_username\"\n    # export SMTP_PASSWORD=\"your_mailtrap_password\"\n    # export TO_EMAIL=\"your_email@example.com\"\n    # export FROM_EMAIL=\"prefect@example.com\"\n\n    # Then execute: python your_script_name.py\n    send_notification_email_flow()","lang":"python","description":"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."},"warnings":[{"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')`.","message":"Always 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"SMTP server connection issues (e.g., 'Connection refused', 'timeout') are often caused by incorrect host/port, firewall restrictions, or incorrect TLS/SSL settings.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"For `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The provided SMTP username or password is incorrect, or the user lacks permission to send email through the server.","error":"smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted.')"},{"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.","cause":"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.","error":"ConnectionRefusedError: [Errno 111] Connection refused"},{"fix":"Run `pip install prefect-email` to install the library.","cause":"The `prefect-email` library has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'prefect_email'"},{"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.","cause":"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.","error":"AttributeError: 'NoneType' object has no attribute 'host' (when loading a block)"}]}