Django¶

Guide for projects built with Django (4.2 LTS and 5.x). Mailexam connects via the built-in SMTP backend django.core.mail — settings in settings.py and a call to send_mail are enough.

What you need¶

A Mailexam account and a project with SMTP credentials.
Python 3.10+ and an installed Django project.

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

requirements.txt:

django>=5.0
python-dotenv>=1.0

2. Environment variables¶

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

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

Host in Django settings: {MAILEXAM_LOGIN}.mailexam.io.

Sender address

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

Alternative ports¶

587 + TLS (recommended)252525 without TLS

MAILEXAM_PORT=587

In settings.py: EMAIL_USE_TLS = True.

MAILEXAM_PORT=2525

EMAIL_USE_TLS = True.

MAILEXAM_PORT=25

EMAIL_USE_TLS = False.

3. `settings.py` configuration¶

At the top of the file load .env (optional, for local development):

from pathlib import Path

from dotenv import load_dotenv

BASE_DIR = Path(__file__).resolve().parent.parent
load_dotenv(BASE_DIR / ".env")

Mailexam mail block:

import os

MAILEXAM_LOGIN = os.environ["MAILEXAM_LOGIN"]
MAILEXAM_PASSWORD = os.environ["MAILEXAM_PASSWORD"]
MAILEXAM_PORT = int(os.environ.get("MAILEXAM_PORT", "587"))

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = f"{MAILEXAM_LOGIN}.mailexam.io"
EMAIL_PORT = MAILEXAM_PORT
EMAIL_USE_TLS = MAILEXAM_PORT in (587, 2525)
EMAIL_HOST_USER = MAILEXAM_LOGIN
EMAIL_HOST_PASSWORD = MAILEXAM_PASSWORD
DEFAULT_FROM_EMAIL = os.environ.get("MAIL_FROM", "noreply@example.test")

4. Sending a test email¶

Via shell¶

python manage.py shell

from django.core.mail import send_mail

send_mail(
    "Django + Mailexam",
    "Mailexam test from Django",
    None,  # from DEFAULT_FROM_EMAIL
    ["user@example.test"],
)

Via view¶

# myapp/views.py
import json

from django.conf import settings
from django.core.mail import send_mail
from django.http import JsonResponse
from django.views.decorators.http import require_POST


@require_POST
def mail_test(request):
    data = json.loads(request.body or "{}")
    send_mail(
        subject=data.get("subject", "Django + Mailexam"),
        message=data.get("body", "Mailexam test from Django"),
        from_email=settings.DEFAULT_FROM_EMAIL,
        recipient_list=[data.get("to", "user@example.test")],
    )
    return JsonResponse({"status": "ok"})

# myapp/urls.py
from django.urls import path

from . import views

urlpatterns = [
    path("mail/test", views.mail_test, name="mail_test"),
]

Start and verify:

python manage.py runserver

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"}'

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

5. Local development and CI¶

Environment	Recommendation
`local`	`.env` + `load_dotenv` or export variables in shell
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.

For unit tests without network use EMAIL_BACKEND = "django.core.mail.backends.locmem.EmailBackend".

6. Common issues¶

TLS or connection error

EMAIL_HOST must be {login}.mailexam.io, where {login} is the same value as EMAIL_HOST_USER / MAILEXAM_LOGIN.
Login and password are a pair from the email; do not combine credentials from different projects.
For port 587 enable EMAIL_USE_TLS = True.

Message not in the dashboard

Make sure you are viewing the inbox of the same Mailexam project.
Check that EMAIL_BACKEND is not overridden to console or file backend in production.

Settings not applied

Restart runserver after changing settings.py.
In production set environment variables in the process (gunicorn/uwsgi), not only in a .env file on disk.