Flask¶

Guide for applications built with Flask (Python 3.10+). Mailexam connects as an SMTP server through the standard smtplib module; a minimal Flask application is enough for a test route.

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 flask python-dotenv

requirements.txt:

flask>=3.0
python-dotenv>=1.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¶

587 + STARTTLS (recommended)252525 without TLS

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¶

# 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 == 587 or port == 2525:
            smtp.starttls()
        smtp.login(login, password)
        smtp.send_message(msg)

4. Flask route¶

# app.py
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request

from mail import send_test

load_dotenv()

app = Flask(__name__)


@app.post("/mail/test")
def mail_test():
    data = request.get_json(force=True, silent=True) or {}
    to = data.get("to", "user@example.test")
    subject = data.get("subject", "Flask + Mailexam")
    body = data.get("body", "Mailexam test from Flask")

    send_test(to=to, subject=subject, body=body)
    return jsonify({"status": "ok"})


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000, debug=True)

Start and verify:

python app.py

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

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 Flask logs and traceback on send.

Environment variables not picked up

Call load_dotenv() before reading os.environ.
In production pass variables through the process environment or CI secrets.