Prefect Email

Common errors

• smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted.')

  cause 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

  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.
  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'

  cause 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)

  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.
  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.

Warnings

• gotcha 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.
  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')`.
• gotcha SMTP 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.
• gotcha 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.
  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).
• gotcha 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`.
  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.

Install

• pip install prefect-email Install prefect-email

Imports

• EmailServerCredentials
  wrong:

  from prefect_email import EmailServerCredentials

  correct:

  from prefect_email.credentials import EmailServerCredentials

  Credentials are found within the 'credentials' submodule, not directly under the top-level package.
• email_send_message
  wrong:

  from prefect_email import send_email

  correct:

  from prefect_email.tasks import email_send_message

  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.

Quickstart

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()