{"id":3486,"library":"fastapi-mail","title":"FastAPI-Mail","description":"fastapi-mail is a simple, lightweight library for sending emails in FastAPI applications. It integrates seamlessly with FastAPI's asynchronous nature and background tasks to prevent blocking the event loop. The current version is 1.6.2, and it maintains an active development pace with frequent minor updates and bug fixes addressing community needs.","status":"active","version":"1.6.2","language":"en","source_language":"en","source_url":"https://github.com/sabuhish/fastapi-mail","tags":["fastapi","email","smtp","async","mail"],"install":[{"cmd":"pip install fastapi-mail","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required only if using `DefaultChecker` for features like rate limiting or connection pooling.","package":"redis","optional":true}],"imports":[{"symbol":"FastMail","correct":"from fastapi_mail import FastMail"},{"symbol":"MessageSchema","correct":"from fastapi_mail import MessageSchema"},{"symbol":"ConnectionConfig","correct":"from fastapi_mail import ConnectionConfig"}],"quickstart":{"code":"from fastapi import FastAPI, BackgroundTasks\nfrom fastapi_mail import FastMail, MessageSchema, ConnectionConfig\nfrom pydantic import EmailStr\nimport os\n\napp = FastAPI()\n\n# Configure email connection settings\n# It's recommended to use environment variables for sensitive data\nconf = ConnectionConfig(\n    MAIL_USERNAME=os.environ.get(\"MAIL_USERNAME\", \"your_email@example.com\"),\n    MAIL_PASSWORD=os.environ.get(\"MAIL_PASSWORD\", \"your_password\"),\n    MAIL_FROM=EmailStr(os.environ.get(\"MAIL_FROM\", \"your_email@example.com\")),\n    MAIL_PORT=int(os.environ.get(\"MAIL_PORT\", 587)),\n    MAIL_SERVER=os.environ.get(\"MAIL_SERVER\", \"smtp.gmail.com\"),\n    MAIL_FROM_NAME=os.environ.get(\"MAIL_FROM_NAME\", \"My FastAPI App\"),\n    MAIL_STARTTLS=bool(os.environ.get(\"MAIL_STARTTLS\", True)),\n    MAIL_SSL_TLS=bool(os.environ.get(\"MAIL_SSL_TLS\", False)),\n    USE_CREDENTIALS=bool(os.environ.get(\"USE_CREDENTIALS\", True)),\n    VALIDATE_CERTS=bool(os.environ.get(\"VALIDATE_CERTS\", True)),\n    TEMPLATE_FOLDER=None # Path to your Jinja2 templates, e.g., './templates'\n)\n\n@app.post(\"/send-email\")\nasync def send_test_email(email_to: EmailStr, background_tasks: BackgroundTasks):\n    # Create a message schema\n    message = MessageSchema(\n        subject=\"FastAPI Mail Test\",\n        recipients=[email_to], # List of recipients\n        body=\"<p>This is a test email sent from <strong>FastAPI-Mail</strong>!</p>\",\n        subtype=\"html\" # Can be \"plain\" or \"html\"\n    )\n    \n    # Instantiate FastMail with the configuration\n    fm = FastMail(conf)\n    \n    # Send the email using background tasks to avoid blocking the API response\n    background_tasks.add_task(fm.send_message, message)\n    \n    return {\"message\": \"Email has been scheduled for sending\"}","lang":"python","description":"This quickstart demonstrates how to set up `fastapi-mail` to send an HTML email asynchronously using FastAPI's `BackgroundTasks`. It uses environment variables for sensitive SMTP credentials and defines a simple endpoint to trigger an email send. Remember to replace placeholder values with your actual SMTP server details."},"warnings":[{"fix":"Pass `fm.send_message` to `background_tasks.add_task()` within your FastAPI endpoint, or `await fm.send_message()` in an `async` context.","message":"Sending emails is a blocking I/O operation. To prevent your FastAPI application from freezing, always use `FastMail.send_message` with `BackgroundTasks` for non-blocking execution, or ensure it's `await`ed within an `async` function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-check your SMTP provider's documentation for the correct server, port, and TLS/SSL settings. Experiment with `MAIL_STARTTLS` and `MAIL_SSL_TLS` (they are mutually exclusive and often one implies the other).","message":"Incorrect SMTP configuration (e.g., `MAIL_PORT`, `MAIL_SERVER`, `MAIL_STARTTLS`, `MAIL_SSL_TLS`, `USE_CREDENTIALS`) is a common cause of connection failures. These settings must precisely match your email provider's requirements.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Before creating `AttachmentFile` or `MessageSchema` with a file-like object, call `file_object.seek(0)`.","message":"When attaching files, ensure the file pointer for the attachment is reset to the beginning (e.g., using `file_object.seek(0)`) before passing it to `MessageSchema`. Failure to do so might result in empty or malformed attachments.","severity":"gotcha","affected_versions":"Prior to v1.6.2 (where an internal fix was made), but still good practice for user-managed file objects."},{"fix":"Install `redis` separately: `pip install redis`. If using `DefaultChecker` ensure the Redis client is properly initialized and passed to `ConnectionConfig`.","message":"The `redis` dependency is optional. If you intend to use `DefaultChecker` for features like email rate limiting or connection pooling, you must explicitly install `redis` (`pip install redis`) and configure it alongside `fastapi-mail`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}