Send email from Django over SMTP

Before you start

1. Sign in and verify the domain you send from. Viesti accepts a message only when its From address is on a domain verified in your workspace and the envelope sender (MAIL FROM), which most libraries take from the From address, is on the same domain. DNS setup lists the records.
2. Create an API key on the Credentials page of the dashboard. It is shown once. The key is the SMTP password; the username is apikey.

Set the environment

export VIESTI_API_KEY="mr_your_api_key"
export MAIL_FROM="Acme <[email protected]>"

Django 6.1: MAILERS

Add to settings.py:

import os

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {
            "host": "smtp.viesti.email",
            "port": 587,
            "use_tls": True,
            "username": "apikey",
            "password": os.environ["VIESTI_API_KEY"],
            "timeout": 10,
        },
    },
}
DEFAULT_FROM_EMAIL = os.environ["MAIL_FROM"]
SERVER_EMAIL = DEFAULT_FROM_EMAIL

"use_tls" is STARTTLS, the right choice for 587. Django 6.1 deprecates EMAIL_BACKEND and the EMAIL_* connection settings in favor of MAILERS: they still work, but each one emits a RemovedInDjango70Warning asking you to migrate before Django 7.0.

Django 5.2 and 6.0: EMAIL_* settings

import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.viesti.email"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "apikey"
EMAIL_HOST_PASSWORD = os.environ["VIESTI_API_KEY"]
EMAIL_TIMEOUT = 10
DEFAULT_FROM_EMAIL = os.environ["MAIL_FROM"]
SERVER_EMAIL = DEFAULT_FROM_EMAIL

Set both sender settings. DEFAULT_FROM_EMAIL is used when you pass no sender, and SERVER_EMAIL sends error reports to ADMINS. Their defaults, webmaster@localhost and root@localhost, are not on a verified domain, so Viesti refuses them.

Send an email

from django.core.mail import send_mail

send_mail(
    "Your receipt",
    "Thanks for your order.",
    None,  # None sends from DEFAULT_FROM_EMAIL
    ["[email protected]"],
)

Test it

Django ships a command that sends a test message from DEFAULT_FROM_EMAIL with the default mailer:

python manage.py sendtestemail [email protected]

No output means Viesti accepted it; check Activity in the dashboard. Django's test runner swaps in the in-memory backend, so your test suite never sends through Viesti.

Port 465

Replace "use_tls": True with "use_ssl": True and set "port": 465; on Django 6.0 and earlier, set EMAIL_USE_SSL = True and EMAIL_PORT = 465 instead of EMAIL_USE_TLS. Never set both.

Common errors

Replies from Viesti

Whatever the library, its error includes the server's reply. These are the ones caused by your setup or account:

A 250 reply means Viesti accepted the message. Content screening runs before relay; mail it flags is held for review and shows as quarantined on the Activity page.

Next steps

• DNS setup: DKIM, SPF, DMARC and return-path records for your domain.
• SMTP reference: ports, TLS and authentication in detail.
• HTTP API: send the same message as JSON over HTTPS.
• Limits and Bounces: quotas, message size and suppressions.

Settings are from the Django 6.1 Sending email documentation; tested with Django 6.1.1 and 5.2.17. Checked 26 September 2026.