Email - Usage guide¶

This guide provides practical examples for sending emails in your FastEdgy application.

Configuration¶

First, configure your SMTP settings in your environment file (.env):

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_DEFAULT_FROM=no-reply@yourapp.com
SMTP_USE_TLS=true

Basic email sending¶

Using the Mail service¶

from fastedgy.dependencies import Inject
from fastedgy.mail import Mail
from email.message import EmailMessage


async def send_simple_email(mail: Mail = Inject(Mail)):

    # Create email message
    email = EmailMessage()
    email["To"] = "user@example.com"
    email["Subject"] = "Hello from FastEdgy"
    email.set_content("This is a plain text email.")

    # Send it
    await mail.send(email)

Using in API endpoints¶

from fastedgy.app import FastEdgy
from fastedgy.dependencies import Inject
from fastedgy.mail import Mail
from fastapi import BackgroundTasks

app = FastEdgy()


async def send_email_background(recipient: str, subject: str, message: str, mail: Mail = Inject(Mail)):
    """Background task to send email."""
    from email.message import EmailMessage

    email_msg = EmailMessage()
    email_msg["To"] = recipient
    email_msg["Subject"] = subject
    email_msg.set_content(message)

    await mail.send(email_msg)


@app.post("/send-notification")
async def send_notification(email: str, message: str, background_tasks: BackgroundTasks):
    # Add email sending to background tasks
    background_tasks.add_task(send_email_background, email, "Notification", message)

    # Return immediately without waiting for email
    return {"status": "queued", "message": "Notification will be sent shortly"}

Template-based emails¶

Create your template¶

Create a template file in templates/en/welcome.html:

{% block subject %}Welcome to {{ app_name }}, {{ user_name }}!{% endblock %}

{% block body_html %}
<div style="font-family: Arial, sans-serif;">
    <h1>Welcome {{ user_name }}!</h1>
    <p>Thank you for joining <strong>{{ app_name }}</strong>.</p>
    <p>Your account is now active and ready to use.</p>
    <a href="{{ login_url }}" style="background-color: #007cba; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">
        Login Now
    </a>
</div>
{% endblock %}

{% block body_text %}
Welcome {{ user_name }}!

Thank you for joining {{ app_name }}.
Your account is now active and ready to use.

Login: {{ login_url }}
{% endblock %}

Send templated email¶

async def send_welcome_email(user_email: str, user_name: str, mail: Mail = Inject(Mail)):
    await mail.send_template(
        template_name="welcome",
        tpl_vals={"user_name": user_name, "app_name": "My Awesome App", "login_url": "https://myapp.com/login"},
        email_parts={"To": user_email},
    )

Background templated emails¶

Perfect for user registration workflows:

from fastapi import BackgroundTasks
from pydantic import BaseModel


class UserRegistration(BaseModel):
    email: str
    username: str
    full_name: str


async def send_welcome_email_background(user_email: str, user_name: str, mail: Mail = Inject(Mail)):
    """Send welcome email in background."""
    await mail.send_template(
        template_name="auth/welcome",
        tpl_vals={"user_name": user_name, "app_name": "My Awesome App", "login_url": "https://myapp.com/login"},
        email_parts={"To": user_email},
    )


@app.post("/register")
async def register_user(user_data: UserRegistration, background_tasks: BackgroundTasks):
    # 1. Create user in database (fast)
    # user = await create_user(user_data)

    # 2. Send welcome email in background (slow)
    background_tasks.add_task(send_welcome_email_background, user_data.email, user_data.full_name)

    # 3. Return immediately
    return {"message": "User registered successfully", "status": "welcome_email_queued"}

Back to Overview