Skip to content

FastAPI

Guide for applications built with FastAPI (Python 3.10+). Mailexam connects as an SMTP server via smtplib; sending can be extracted into a separate module and called from an async handler.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • Python 3.10+ and a virtual environment.

Copy from the welcome email (or dashboard) for your project:

  • YOUR_LOGIN — SMTP login (for example, xxxxx);
  • YOUR_PASSWORD — SMTP password (a unique pair with the login);
  • host — YOUR_LOGIN.mailexam.io (matches the login).

1. Dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn python-dotenv email-validator

requirements.txt:

fastapi>=0.115
uvicorn[standard]>=0.32
python-dotenv>=1.0
email-validator>=2.0

2. Environment variables

.env file in the project root (do not commit passwords to git):

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

The host is built from the login: {MAILEXAM_LOGIN}.mailexam.io.

Sender address

MAIL_FROM can be any test address — the message goes to Mailexam, not to a real recipient.

Alternative ports

MAILEXAM_PORT=587

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

For port 25 do not call starttls() in code (see module below).

3. Mail sending module

Same approach as in Flask:

# mail.py
import os
import smtplib
from email.message import EmailMessage


def smtp_host() -> str:
    login = os.environ["MAILEXAM_LOGIN"]
    return f"{login}.mailexam.io"


def send_test(*, to: str, subject: str, body: str) -> None:
    login = os.environ["MAILEXAM_LOGIN"]
    password = os.environ["MAILEXAM_PASSWORD"]
    port = int(os.environ.get("MAILEXAM_PORT", "587"))
    mail_from = os.environ.get("MAIL_FROM", "noreply@example.test")

    msg = EmailMessage()
    msg["From"] = mail_from
    msg["To"] = to
    msg["Subject"] = subject
    msg.set_content(body)

    with smtplib.SMTP(smtp_host(), port, timeout=30) as smtp:
        if port in (587, 2525):
            smtp.starttls()
        smtp.login(login, password)
        smtp.send_message(msg)

smtplib is synchronous — in an async application call it via asyncio.to_thread so the event loop is not blocked.

4. FastAPI route

# main.py
import asyncio

from dotenv import load_dotenv
from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

from mail import send_test

load_dotenv()

app = FastAPI()


class SendRequest(BaseModel):
    to: EmailStr = "user@example.test"
    subject: str = "FastAPI + Mailexam"
    body: str = "Mailexam test from FastAPI"


@app.post("/mail/test")
async def mail_test(payload: SendRequest):
    await asyncio.to_thread(
        send_test,
        to=str(payload.to),
        subject=payload.subject,
        body=payload.body,
    )
    return {"status": "ok"}

Start and verify:

uvicorn main:app --reload --host 127.0.0.1 --port 8000

curl -X POST http://127.0.0.1:8000/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","body":"Hello"}'

API documentation: http://127.0.0.1:8000/docs

The message will appear in the Mailexam dashboard → your project → inbox.

5. Local development and CI

Environment Recommendation
local .env with a personal Mailexam project
CI Secrets MAILEXAM_LOGIN, MAILEXAM_PASSWORD in GitLab CI/CD Variables

Example for .gitlab-ci.yml:

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

After an integration test with message sending, verify delivery via the Mailexam API.

6. Common issues

TLS or connection error

  • Host must be {login}.mailexam.io, where {login} is the same value as MAILEXAM_LOGIN from the email.
  • Login and password are a pair from the email; do not combine credentials from different projects.
  • For port 587 call smtp.starttls() before login().

Message not in the dashboard

  • Make sure you are viewing the inbox of the same Mailexam project.
  • Check the /mail/test response and uvicorn logs.

Event loop blocking

  • Do not call send_test() directly in async def — use asyncio.to_thread() or a background task.

Environment variables not picked up

  • Call load_dotenv() at application startup.
  • When running via systemd/Docker pass variables into the container environment.

See also